Authentication & Tokens¶

Every API request (except a small number of public endpoints) must include an Authorization header. Two token types are accepted:

Authorization: Bearer <jwt-or-static-token>

See Getting Started: Authentication for how to obtain tokens and which type to use. This page covers the technical contract.

JWT bearer tokens¶

JWT tokens are issued by the Rodauth login endpoint:

POST /login
Content-Type: application/json

{ "login": "you@example.com", "password": "..." }

The JWT is returned in the response Authorization header, not the body.

Token claims:

JWTs are short-lived. When a token expires, re-authenticate via POST /login.

Static API tokens¶

Static tokens are long-lived, org-scoped, and carry explicit permission scopes. They are created through the dashboard or directly in the database. Static tokens:

• Do not expire automatically.
• Carry Bearer prefix exactly like JWTs — the API determines the type from the token format.
• Are scoped to one organization; cross-org requests with a static token are rejected.
• Require at least one scope; empty-scope tokens are denied (deny-by-default).

Scopes follow <category>:<action>, e.g.:

dns:read
dns:write
rgw_users:*
projects:read

Unauthenticated endpoints¶

These endpoints do not require a token:

All other endpoints return 401 Unauthorized when no valid token is supplied.

Error responses¶