ShiwakeDocs

Tenants

Platform-level endpoints for managing tenants and API keys.

Tenants are the top-level isolation boundary in Shiwake: every account, journal entry, and hold belongs to exactly one tenant, and tenant-scoped requests can never read or write another tenant's data.

These endpoints live under /api/v1/platform/tenants and require the PlatformAdmin policy: a bearer JWT, not an X-Api-Key. They are not rate-limited and are intended for use by trusted operator tooling only. See Authentication.

The Tenant object

{
  "id": "ten_01HZ...",
  "name": "Acme Finance",
  "slug": "acme-finance",
  "isActive": true,
  "createdAt": "2026-01-15T09:00:00Z"
}

Prop

Type


Create a tenant

POST/api/v1/platform/tenants

Creates a new tenant. The slug must be unique across the platform. After creation, call rotate-api-key to mint the first API key for the tenant.

Request body

Prop

Type

curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants" \
  -H "Authorization: Bearer $PLATFORM_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Finance",
    "slug": "acme-finance"
  }'

Status codes

CodeWhen
201Tenant created
400Invalid body (missing name/slug, too long)
409A tenant with that slug already exists

List tenants

GET/api/v1/platform/tenants

Returns all tenants ordered by name. Not paginated. Platform operators typically have a small, bounded number of tenants.

curl "https://api.shiwake.example.com/api/v1/platform/tenants" \
  -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"

Get a tenant

GET/api/v1/platform/tenants/{id}
curl "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ..." \
  -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"

Status codes

CodeWhen
200Tenant returned
404No tenant with that id

Disable a tenant

POST/api/v1/platform/tenants/{id}/disable

Soft-deletes a tenant by flipping isActive to false. Any subsequent ledger request authenticated as this tenant will be rejected with 403 Tenant is disabled. Data is preserved and can be reactivated later (directly in the database: there is no enable endpoint).

curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ.../disable" \
  -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"

Rotate API key

POST/api/v1/platform/tenants/{id}/rotate-api-key

Generates a new 32-byte API key for the tenant and replaces any existing key. The raw key is returned once in the response: the server only stores its SHA-256 hash. If you lose it you must rotate again.

This endpoint is how you mint the first key for a newly-created tenant, and how you respond to a suspected key compromise.

Rotating immediately invalidates the previous key. Any in-flight requests using the old key will start returning 401 Invalid API key. Coordinate rotations with the tenant's own deploys.

curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ.../rotate-api-key" \
  -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"

Status codes

CodeWhen
200Key rotated; raw key in data.api_key
404No tenant with that id
Edit on GitHub

Last updated on

On this page