Service keys
Two credentials share Authorization: Bearer. Sibling services use an esk_ key. The admin app uses an identity-service JWT.
Issue the key in email-service, then set EMAIL_SERVICE_API_KEY on the caller. storage-service and hosting-service also need EMAIL_SERVICE_ALLOW_PRIVATE=true when EMAIL_SERVICE_URL is a private or loopback address. See Configuration.
Key format
Prefix esk_, then token_urlsafe(32). Stored as a 12-character prefix and a SHA-256 hash.
A key carries:
service(for exampleidentity)allowed_lanesallowed_template_prefixes(a template key must start with one of them)allowed_company_ids, optional. Leave it unset to allow every company. An empty list allows none.
Issue a key as staff:
POST /api/v1/service-clients
or:
uv run python manage.py create_service_key --service identity --lanes auth,transactional --prefixes identity.
The command and the POST response print the key once. Callers set EMAIL_SERVICE_API_KEY.
create_service_key and a POST that omits allowed_company_ids allow every company. In Django admin, a new key starts as an empty list, which allows none. Type null in that field to allow every company. An empty list stored before this change is migrated to null, so those keys keep the scope they already had.
Recommended scopes: identity auth and transactional with prefix identity.; storage and hosting transactional with prefixes storage. and hosting..
Identity JWTs
Admin routes verify RS256 tokens with the same JWKS client as storage-service and hosting-service.
| Setting | Role |
|---|---|
IDENTITY_JWKS or IDENTITY_JWKS_FILE | Pinned public keys. Preferred when the container cannot reach identity-service. |
IDENTITY_SERVICE_URL | identity-service base URL. JWKS is {url}/.well-known/jwks.json when no document is pinned. |
IDENTITY_JWKS_URL | Explicit JWKS fetch URL when no document is pinned. |
IDENTITY_ISSUER | Required when DEBUG=false. Match identity JWT_ISSUER. |
IDENTITY_AUDIENCE | Required when DEBUG=false. Match identity JWT_AUDIENCE. |
JWT_HS256_FALLBACK_SECRET | Local only, when identity is in DEBUG with HS256. |
The token kid must name a key in the JWKS. A missing or unknown kid is rejected, including when the document has one key. During rotation, leave the previous key in the document until tokens signed with it expire.
The principal needs is_staff or is_company_owner. If the token has company_id, it must equal the requested company unless the caller is staff. A mismatch is 403 company_mismatch.
GET /api/v1/metrics follows storage-service: staff, or the pat_agm claim, sees every company. A company owner sees their own company. The endpoint is not anonymous.
Health
GET /api/v1/health does not require a credential.