TrellisDevelopers
API reference

Foundation

List locations available to the authenticated administrator

GET
/foundation/locations

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/locations" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "locations": [    {      "id": "string",      "code": "string",      "name": "string",      "timezone": "string",      "kind": "restaurant",      "isDefault": true    }  ]}

List the canonical Trellis POS permission catalog

GET
/foundation/permissions

Toast-style operational permission matrix represented with Trellis-native permission primitives. Staff role assignments can grant or deny these primitives in scopes.accessPrimitives.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/permissions" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "permissions": [    {      "code": "string",      "reference": "string",      "category": "string",      "label": "string",      "description": "string",      "supportsManagerOverride": true    }  ],  "matrix": [    {      "role": "owner",      "grants": [        "string"      ]    }  ],  "page": {    "total": 0  }}

Resolve the current staff authorization snapshot

GET
/foundation/me/authorization

Returns the effective Trellis permission primitives after role defaults, role assignment grants/denies, and job-based grants/denies are applied.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/me/authorization" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "staffUser": {    "id": "string",    "tenantId": "string",    "authProvider": "hexclave",    "authUserId": "string",    "email": "user@example.com",    "firstName": "string",    "lastName": "string",    "status": "invited",    "lastLoginAt": "2019-08-24T14:15:22Z",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "roles": [    "owner"  ],  "primitives": [    "string"  ],  "assignments": [    {      "id": "string",      "tenantId": "string",      "staffUserId": "string",      "locationId": "string",      "role": "owner",      "grantedByStaffUserId": "string",      "scopes": {        "property1": null,        "property2": null      },      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

List persisted tenants

GET
/foundation/tenants

First Postgres-backed layer. This route reads the actual tenant records from Postgres instead of the in-memory store.

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/tenants" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "tenants": [    {      "id": "string",      "slug": "string",      "name": "string",      "status": "active",      "ownerEmail": "user@example.com",      "defaultCurrency": "str",      "timezone": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "page": {    "total": 0  }}

Create a persisted tenant

POST
/foundation/tenants

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/foundation/tenants" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "slug": "string",    "name": "string",    "ownerEmail": "user@example.com"  }'
{  "id": "string",  "slug": "string",  "name": "string",  "status": "active",  "ownerEmail": "user@example.com",  "defaultCurrency": "str",  "timezone": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Retrieve a persisted tenant

GET
/foundation/tenants/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/tenants/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "slug": "string",  "name": "string",  "status": "active",  "ownerEmail": "user@example.com",  "defaultCurrency": "str",  "timezone": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

List persisted staff users for a tenant

GET
/foundation/tenants/{tenantId}/staff-users

Path Parameters

tenantId*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/tenants/string/staff-users" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "staffUsers": [    {      "id": "string",      "tenantId": "string",      "authProvider": "hexclave",      "authUserId": "string",      "email": "user@example.com",      "firstName": "string",      "lastName": "string",      "status": "invited",      "lastLoginAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "page": {    "total": 0  }}

Create a persisted staff user

POST
/foundation/tenants/{tenantId}/staff-users

Path Parameters

tenantId*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/foundation/tenants/string/staff-users" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "authProvider": "hexclave",    "authUserId": "string",    "email": "user@example.com"  }'
{  "id": "string",  "tenantId": "string",  "authProvider": "hexclave",  "authUserId": "string",  "email": "user@example.com",  "firstName": "string",  "lastName": "string",  "status": "invited",  "lastLoginAt": "2019-08-24T14:15:22Z",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

Retrieve a persisted staff user

GET
/foundation/staff-users/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/staff-users/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "tenantId": "string",  "authProvider": "hexclave",  "authUserId": "string",  "email": "user@example.com",  "firstName": "string",  "lastName": "string",  "status": "invited",  "lastLoginAt": "2019-08-24T14:15:22Z",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}

List persisted audit logs for a tenant

GET
/foundation/tenants/{tenantId}/audit-logs

Path Parameters

tenantId*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 200

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/tenants/string/audit-logs" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "auditLogs": [    {      "id": "string",      "tenantId": "string",      "actorType": "staff",      "actorStaffUserId": "string",      "actorAuthProvider": "hexclave",      "actorAuthUserId": "string",      "locationId": "string",      "action": "string",      "entityType": "string",      "entityId": "string",      "orderId": "string",      "requestId": "string",      "ipAddress": "string",      "userAgent": "string",      "metadata": {        "property1": null,        "property2": null      },      "beforeState": {        "property1": null,        "property2": null      },      "afterState": {        "property1": null,        "property2": null      },      "occurredAt": "2019-08-24T14:15:22Z"    }  ],  "page": {    "total": 0  }}

Write a persisted audit log

POST
/foundation/tenants/{tenantId}/audit-logs

Path Parameters

tenantId*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/foundation/tenants/string/audit-logs" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "actorType": "staff",    "action": "string",    "entityType": "string"  }'
{  "id": "string",  "tenantId": "string",  "actorType": "staff",  "actorStaffUserId": "string",  "actorAuthProvider": "hexclave",  "actorAuthUserId": "string",  "locationId": "string",  "action": "string",  "entityType": "string",  "entityId": "string",  "orderId": "string",  "requestId": "string",  "ipAddress": "string",  "userAgent": "string",  "metadata": {    "property1": null,    "property2": null  },  "beforeState": {    "property1": null,    "property2": null  },  "afterState": {    "property1": null,    "property2": null  },  "occurredAt": "2019-08-24T14:15:22Z"}

List persisted staff role assignments for a tenant

GET
/foundation/tenants/{tenantId}/staff-role-assignments

Path Parameters

tenantId*string
Length1 <= length

Query Parameters

staffUserId?string
locationId?string

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/tenants/string/staff-role-assignments" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "staffRoleAssignments": [    {      "id": "string",      "tenantId": "string",      "staffUserId": "string",      "locationId": "string",      "role": "owner",      "grantedByStaffUserId": "string",      "scopes": {        "property1": null,        "property2": null      },      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "page": {    "total": 0  }}

Create a persisted staff role assignment

POST
/foundation/tenants/{tenantId}/staff-role-assignments

Path Parameters

tenantId*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/foundation/tenants/string/staff-role-assignments" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "staffUserId": "string",    "role": "owner"  }'
{  "id": "string",  "tenantId": "string",  "staffUserId": "string",  "locationId": "string",  "role": "owner",  "grantedByStaffUserId": "string",  "scopes": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z"}

Retrieve a persisted staff role assignment

GET
/foundation/staff-role-assignments/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/foundation/staff-role-assignments/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "tenantId": "string",  "staffUserId": "string",  "locationId": "string",  "role": "owner",  "grantedByStaffUserId": "string",  "scopes": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z"}

Delete a persisted staff role assignment

DELETE
/foundation/staff-role-assignments/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X DELETE "https://example.com/foundation/staff-role-assignments/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "tenantId": "string",  "staffUserId": "string",  "locationId": "string",  "role": "owner",  "grantedByStaffUserId": "string",  "scopes": {    "property1": null,    "property2": null  },  "createdAt": "2019-08-24T14:15:22Z"}

Departments

Previous Page

Fulfillment

Next Page