Payment ReconcilerDocumentation
QFind anything/
API Reference

Authentication

How authentication works—auth modes, JWT vs API keys, and when to use each.

Overview

The API supports two authentication methods:

MethodUse caseHeader
JWT (Bearer)Interactive users, Swagger, short-lived sessionsAuthorization: Bearer <token>
API keyService-to-service, scripts, long-lived programmatic accessX-Api-Key: <key>

Both require tenant context: X-Tenant-Id and X-Environment. With an API key, those headers are required and must match the key’s tenant and environment. See Required Headers for details.

Auth modes

The server AUTH_MODE setting controls how JWTs are validated. Documented platform integration uses Keycloak:

ModeJWT sourceWhen to use
keycloakPOST /auth/token → Keycloak access tokenProduction and typical development with Keycloak.
bothTry Keycloak first, then symmetric JWT where applicableMigration or mixed environments.

Other AUTH_MODE values may exist for legacy or internal tooling; they are not part of the external integration path. Use Keycloak and token exchange as described in Token Exchange.

Use POST /auth/token with username and password to obtain a Keycloak access token, then send it as Authorization: Bearer <access_token> on business APIs.

JWT flow

  1. Obtain a token — Token exchange (POST /auth/token with Keycloak credentials).
  2. Include in requests — Authorization: Bearer <access_token>
  3. Token contains — tenant_id, environment, user_id, roles, permissions. The API validates the tenant and user against the database. See Users for provisioning.

JWT expiry follows Keycloak and your realm settings. Refresh tokens are not supported by this API; obtain a new token when expired.

API key flow

  1. Create — POST /auth/api-keys (JWT only). Response includes apiKey (pr_<public>.<secret>), id, and publicId. Only the secret segment is stored hashed (Argon2id) in the database.
  2. List / revoke — GET /auth/api-keys and DELETE /auth/api-keys/:id are JWT only; listing returns metadata, never the secret.
  3. Use on business APIs — Send X-Api-Key: <full key> or Authorization: Bearer <full key> (opaque). Include X-Tenant-Id and X-Environment; they must match the key. If both X-Api-Key and Authorization are sent, X-Api-Key wins.
  4. Permissions — Keys carry read / write flags. Read-only HTTP methods require read; mutating methods require write.

API keys are scoped to one tenant and environment. Optional expiresAt and revocation apply to all requests using that key. Use keys for background jobs, internal services, or scripts that call the API without an interactive user.

Public endpoints

These endpoints do not require authentication:

  • GET /api/health — Health check
  • POST /auth/token — Token exchange (Keycloak)

All other endpoints require Authorization or X-Api-Key plus X-Tenant-Id and X-Environment (unless the route is explicitly public, e.g. POST /tenants in development).

Next steps