# Authentication

API keys, tenant resolution, and the two authorization policies.

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



Shiwake has two authentication paths, one for each of its two namespaces.
Ledger operations use per-tenant API keys. Platform operations use a bearer
token issued to platform administrators.

Ledger API: API keys [#ledger-api-api-keys]

Every request to `/api/v1/ledger/*` must carry an `X-Api-Key` header. The key
identifies the tenant; there is no separate tenant header to provide.

```http
GET /api/v1/ledger/accounts HTTP/1.1
Host: api.shiwake.example.com
X-Api-Key: sk_live_7cL9pQ2mN8hR3vT5wY1xZ4bJ6fK0dG2a
```

How keys map to tenants [#how-keys-map-to-tenants]

When a tenant is provisioned, Shiwake generates a 32-byte random key,
base64-encodes it, returns it **once** to the caller, and stores only its
SHA-256 hash. On every request the middleware hashes the incoming header
and looks up the matching tenant by hash. The raw key is never persisted
and cannot be recovered. If you lose it, you must
[rotate it](/docs/api/tenants).

Missing or invalid key [#missing-or-invalid-key]

<CodeBlockTabs defaultValue="missing">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="missing">
      Missing
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="invalid">
      Invalid
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="missing">
    ```json
    {
      "code": 401,
      "message": "X-Api-Key header is required.",
      "data": null
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="invalid">
    ```json
    {
      "code": 401,
      "message": "Invalid API key.",
      "data": null
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Disabled tenants [#disabled-tenants]

If the tenant has been disabled via
`POST /platform/tenants/{id}/disable`, the request is rejected with
`403 Forbidden` even though the key is valid:

```json
{
  "code": 403,
  "message": "Tenant is disabled.",
  "data": null
}
```

Platform API: bearer tokens [#platform-api-bearer-tokens]

Endpoints under `/api/v1/platform/*` require a bearer token issued to
platform administrators. These operations bypass the tenant query filter
because they manage tenants themselves.

```http
POST /api/v1/platform/tenants HTTP/1.1
Host: api.shiwake.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json
```

The token must carry a claim indicating platform-admin privileges. Consult
your deployment's identity provider for how to obtain one.

Authorization policies [#authorization-policies]

Shiwake enforces two policies at the controller level:

| Policy          | Applied to               | Required credential                          |
| --------------- | ------------------------ | -------------------------------------------- |
| `TenantAccess`  | All `/ledger/*` routes   | Valid `X-Api-Key` mapped to an active tenant |
| `PlatformAdmin` | All `/platform/*` routes | Bearer token with platform-admin claim       |

A request that passes authentication but fails authorization returns
`403 Forbidden`. A request with no credentials at all returns `401 Unauthorized`.

Storing keys [#storing-keys]

<Callout type="warn">
  Treat API keys like passwords. Store them in a secret manager (Azure Key
  Vault, AWS Secrets Manager, HashiCorp Vault) and inject them as environment
  variables. Never commit them to source control or hard-code them in
  client-side applications.
</Callout>

Rotating keys [#rotating-keys]

Keys can be rotated at any time via
[`POST /platform/tenants/{id}/rotate-api-key`](/docs/api/tenants). Rotation is
immediate: the old key stops working the moment the new one is generated, so
coordinate the rollout with any long-running clients.
