Contract snapshot 0.101.0 · Deployment and client release availability follow the integration note for your environment.
Bearer credentials
Use Authorization: Bearer <token>. Clerk session tokens use the rewalto-core template and rewalto-core-api audience. API keys begin rwk_. The server derives organisation membership from the credential, not from an organisation supplied by a browser.
Sessions and keys have different roles
Use a fresh session token for each signed-in request. Use an authorised API key for unattended workflows. Key operations may require a signed-in administrator; consult each operation’s permissions before exposing a control.
Keep secrets out of the browser
Use the generated client from server code. Never put a long-lived key in a public environment variable, URL, static page, source control or a copied support message. Refresh an expired session before retrying a read.
Diagnose an authentication failure
Check the base URL, credential type, token expiry and expected audience without printing the credential. Distinguish an expired session from an absent permission. Replacing a token cannot grant a scope the caller does not have, and changing an organisation identifier in a browser must not be used to select another tenant.
Choose credentials for the execution context
Interactive account actions and unattended data reads can require different permissions. Follow each operation’s contract rather than reusing an administrator credential everywhere. Keep separate environment configuration for local development and the connected service so a test does not silently target another environment.
GET
/v1/whoami
Who is calling, their organisation, role and plan
Accepts a Clerk session token or an API key. For a signed-in user without an organisation it creates one personal organisation on the first call (idempotent). A session token that carries `org_name` keeps the stored organisation name in step with Clerk. Costs nothing; the credits balance is GET /v1/credits/balance.
| Status | Meaning |
|---|---|
| 200 | Success |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.