ShiwakeDocs

Authentication

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

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

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.

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

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.

Missing or invalid key

{
  "code": 401,
  "message": "X-Api-Key header is required.",
  "data": null
}

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:

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

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.

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

Shiwake enforces two policies at the controller level:

PolicyApplied toRequired credential
TenantAccessAll /ledger/* routesValid X-Api-Key mapped to an active tenant
PlatformAdminAll /platform/* routesBearer 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

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.

Rotating keys

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

Edit on GitHub

Last updated on

On this page