The Contember Tenant API is a specialized GraphQL API for managing projects, tokens, users, and roles. Unlike the Content API, the Tenant API is shared across all projects and is accessible at https://engine-hostname/tenant. Every request needs a Bearer token in the Authorization header.
Key Concepts
- Identity — Carries roles and project memberships. The unit that authorization is bound to. May or may not have an attached person.
- Person — An identity with credentials (email + optional password) and additional profile fields. Persons can sign in; bare identities cannot.
- API Key / Token — A bearer token. Either permanent (created for an application or backend service, no expiry) or session (minted at sign-in time, short-lived, tied to a person). See API keys and sessions.
Authorization
Just like the Content API, every Tenant API request needs a bearer token — including sign-in operations.
The default tokens for the login and super_admin roles are configured via the CONTEMBER_LOGIN_TOKEN and CONTEMBER_ROOT_TOKEN environment variables. For local development they are visible in docker-compose.yaml.
The login token authorizes the public auth flows: signIn, signInIDP, signInPasswordless, createResetPasswordRequest, resetPassword, signUp.
Unpersisted root tokens
CONTEMBER_ROOT_TOKEN is seeded into the tenant database during setup — its hash is stored in the api_key table. As an alternative (or in addition), you can configure unpersisted root tokens that are verified at runtime and resolve to a super_admin identity without being stored in the database:
CONTEMBER_ROOT_TOKENS— a comma- or whitespace-separated list of plain root tokens.CONTEMBER_ROOT_TOKEN_HASHES— a comma- or whitespace-separated list of sha256 hashes (lower- or upper-case hex) of root tokens, so the plain secret never has to be handed to the engine.
In the JSON/YAML config these map to tenant.credentials.rootTokens and tenant.credentials.rootTokenHashes, which may also be supplied as arrays.
Because these tokens are never written to the database, rotation is trivial — just change the environment variable (or config) and restart; no migration or database write is involved, and revoking a token is as simple as removing it from the list. Incoming tokens are matched against the configured hashes using a constant-time comparison.
A request authenticated by an unpersisted root token is granted the super_admin role (full access) and is attributed to a fixed virtual identity id that has no row in the identity table.
Choosing the right token
Picking the correct token for a given operation can be confusing. The canonical example — generating a permanent API key so an application can read from the Content API:
- Locate the login token from your environment configuration.
- Sign in — call
signInagainst the Tenant API using the login token as the bearer. - Receive the session token in the response. It's short-lived.
- Create the API key — call
createApiKeyusing the session token as the bearer. - Read the permanent API token out of the response. This is what your application stores.
- Use the permanent API token against the Content API.
Where to read next
| You need to … | Page |
|---|---|
| Create new users from the public-facing endpoint | Sign-up |
| Authenticate existing users (password, IdP, passwordless, admin-impersonation) | Sign-in · IdP · Passwordless |
| Run the public password-reset flow | Password reset |
| Set up TOTP two-factor authentication | Two-factor |
| Require users to verify their e-mail (sign-up or e-mail change) | E-mail verification |
| Change profile or password (self or admin) | Profile and password changes |
| Invite users to projects | Invites |
| Manage project membership | Memberships |
| Permanently disable an account | Disabling a person |
| Create or revoke long-lived API keys for applications | API keys |
| Create or update projects, set project secrets | Project management |
| List, revoke, or force-end user sessions | Sessions |
| Have a backend service forward real user IP/UA to Contember | Proxy trust |
| Tune password policy, captcha, rate limits | Password policy · Anti-abuse |
| Customize transactional mails | Mail templates |
| Inspect what actions were taken against the tenant | Audit log |
| See the full configuration surface in one place | Configuration |
Audit
Every authentication-relevant operation and every administrative tenant mutation is recorded in person_auth_log. The audit log page is the complete reference of event types, event_data payloads, and how to query them.