![](https://rewalto.com/brand/neo/assets/sample-hero-light.svg)![](https://rewalto.com/brand/neo/assets/sample-hero-dark.svg)

DEVELOPER DOCS / CONTRACT 0.101.0

# Authentication and organisations

Session tokens and scoped API keys identify the caller and their organisation.

Get started with your AI agent.Copy agent prompt

Search API documentation

Search all ten API documentation guides

[Documentation overview](https://rewalto.com/developers/docs)[Make your first request](https://rewalto.com/developers/docs/quickstart)[Authentication and organisations](https://rewalto.com/developers/docs/authentication)[Create and manage API keys](https://rewalto.com/developers/docs/api-keys)[Read commerce data](https://rewalto.com/developers/docs/data)[Balances, usage and receipts](https://rewalto.com/developers/docs/credits)[Review and approve a quote](https://rewalto.com/developers/docs/quotes)[Refunds by receipt](https://rewalto.com/developers/docs/refunds)[Errors and safe retries](https://rewalto.com/developers/docs/errors)[Use the TypeScript client](https://rewalto.com/developers/docs/client)[API, CLI and MCP (preview)](https://rewalto.com/developers/docs/cli-mcp)[Discover the data catalogue](https://rewalto.com/developers/docs/catalogue)[Check held data and request a missing type](https://rewalto.com/developers/docs/intake)[Dataset snapshots and exports](https://rewalto.com/developers/docs/dataset-purchases)[Download OpenAPI JSON](https://rewalto.com/developers/openapi.json)

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.

Response status codes

| 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.

[All API documentation](https://rewalto.com/developers/docs)[Read OpenAPI contract](https://rewalto.com/developers/openapi.json)

---

Canonical page: https://rewalto.com/developers/docs/authentication
Last content change: 2026-10-26