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_7cL9pQ2mN8hR3vT5wY1xZ4bJ6fK0dG2aHow 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/jsonThe 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:
| 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
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.
Last updated on