# Tenants

Platform-level endpoints for managing tenants and API keys.

URL: https://docs.shiwake.app/docs/api/tenants



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.

<Callout type="warn">
  These endpoints live under `/api/v1/platform/tenants&#x60; and require the
  &#x2A;*`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](/docs/api/authentication).
</Callout>

The Tenant object [#the-tenant-object]

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

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: <>ULID, prefixed <code>ten_</code></> },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable display name&#x22; },
  slug: { type: &#x22;string&#x22;, required: true, description: &#x22;URL-safe unique identifier (immutable)&#x22; },
  isActive: { type: &#x22;bool&#x22;, required: true, description: <><code>false</code> means the tenant is disabled; all ledger requests return <code>403</code></> },
  createdAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Creation timestamp&#x22; },
}"
/>

***

Create a tenant [#create-a-tenant]

<Endpoint method="POST" path="/api/v1/platform/tenants" />

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

Request body [#request-body]

<TypeTable
  type="{
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Display name, max 255 chars&#x22; },
  slug: { type: &#x22;string&#x22;, required: true, description: &#x22;URL-safe, max 100 chars. Immutable after creation&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Tenant created.",
      "data": {
        "id": "ten_01HZ...",
        "name": "Acme Finance",
        "slug": "acme-finance",
        "isActive": true,
        "createdAt": "2026-04-07T12:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#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 [#list-tenants]

<Endpoint method="GET" path="/api/v1/platform/tenants" />

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

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl "https://api.shiwake.example.com/api/v1/platform/tenants" \
      -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": [
        {
          "id": "ten_01HZ...",
          "name": "Acme Finance",
          "slug": "acme-finance",
          "isActive": true,
          "createdAt": "2026-01-15T09:00:00Z"
        }
      ]
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

Get a tenant [#get-a-tenant]

<Endpoint method="GET" path="/api/v1/platform/tenants/{id}" />

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ..." \
      -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-1]

| Code  | When                   |
| ----- | ---------------------- |
| `200` | Tenant returned        |
| `404` | No tenant with that id |

***

Disable a tenant [#disable-a-tenant]

<Endpoint method="POST" path="/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).

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ.../disable" \
      -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Tenant disabled.",
      "data": {
        "id": "ten_01HZ...",
        "name": "Acme Finance",
        "slug": "acme-finance",
        "isActive": false,
        "createdAt": "2026-01-15T09:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

Rotate API key [#rotate-api-key]

<Endpoint method="POST" path="/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.

<Callout type="warn">
  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.
</Callout>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ.../rotate-api-key" \
      -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "API key rotated. Store this key securely: it cannot be retrieved again.",
      "data": {
        "api_key": "sk_live_KJH3k2jh4KJH3...=="
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-2]

| Code  | When                                   |
| ----- | -------------------------------------- |
| `200` | Key rotated; raw key in `data.api_key` |
| `404` | No tenant with that id                 |
