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
/api/v1/platform/tenantsCreates 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
| Code | When |
|---|---|
201 | Tenant created |
400 | Invalid body (missing name/slug, too long) |
409 | A tenant with that slug already exists |
List tenants
/api/v1/platform/tenantsReturns 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
/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
| Code | When |
|---|---|
200 | Tenant returned |
404 | No tenant with that id |
Disable a tenant
/api/v1/platform/tenants/{id}/disableSoft-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
/api/v1/platform/tenants/{id}/rotate-api-keyGenerates 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
| Code | When |
|---|---|
200 | Key rotated; raw key in data.api_key |
404 | No tenant with that id |
Last updated on