Identity & Authentication Service API

The identity service (open-security-identity, FastAPI with fastapi-users) owns users, JWT (JSON Web Token) login, API keys and teams, and answers the gateway’s authorization checks.

Gateway path: https://<host>/api/v1/identity/... (proxied to the service’s /api/v1/...); login at https://<host>/auth/jwt/login
Local port: listed in Service ports
Authentication: JWT bearer token; identity validates it itself on its routes

This page lists the routes registered in open-security-identity/app/main.py and the modules it includes. For request and response schemas, the service publishes its OpenAPI document at /openapi.json, Swagger UI at /docs and ReDoc at /redoc on its local port (not through the gateway), only when ENVIRONMENT is development. The .env written by make generate-secrets sets ENVIRONMENT=production, so those three paths answer 404 in the default stack.


Authentication

Log In

POST /api/v1/auth/jwt/login (gateway: POST /auth/jwt/login)

Form-encoded body, as defined by OAuth2 password flow: username (the email address) and password. Returns:

{
  "access_token": "<JWT>",
  "token_type": "bearer"
}

Wrong credentials return 400. After 5 failed logins for the same email the account is locked for 15 minutes: every login, even with the right password, returns 429 with Retry-After: 900. Tokens are HS256 JWTs valid for 30 minutes, with no refresh endpoint. Lifetime, claims, revocation, the lockout and password hashing are described once, in the Authentication and sessions guide.

TOKEN=$(curl -s --cacert open-security-gateway/ssl/wildbox.crt \
  -X POST https://localhost/auth/jwt/login \
  --data-urlencode "username=$ADMIN_EMAIL" \
  --data-urlencode "password=$ADMIN_PASSWORD" | jq -r .access_token)

The Quick Start shows where ADMIN_EMAIL and ADMIN_PASSWORD come from.

Log Out

POST /api/v1/auth/logout (gateway: POST /auth/logout), or the fastapi-users route POST /api/v1/auth/jwt/logout (gateway: POST /auth/jwt/logout), with Authorization: Bearer <token>. Has the gateway refuse the token’s jti and adds it to a blacklist until the token would have expired. POST /api/v1/auth/logout returns 200 whether or not the token was already revoked. POST /api/v1/auth/jwt/logout returns 204 with no body, and 401 for a token that is already revoked, because it authenticates the token first. Both return 401 without a bearer token; 400 for a token without a jti (issued before the release that added it), which expires on its own; 503 when the gateway did not confirm the revocation or the blacklist could not be written, in which case the token is still valid and the logout can be repeated.

Other Authentication Routes

All under /api/v1/auth (fastapi-users):

Method Path Purpose
POST /register Create an account (gateway: /auth/register)
POST /forgot-password Request a password reset token
POST /reset-password Reset a password with that token
POST /request-verify-token Request an email verification token
POST /verify Verify an email address

Current User

Method Path Purpose
GET /api/v1/users/me The authenticated user
PATCH /api/v1/users/me Update the authenticated user (fastapi-users); an email change needs current_password, a password is refused
PATCH /api/v1/admin/me/profile Change the email; body email, current_password
PUT /api/v1/admin/me Same as PATCH /api/v1/admin/me/profile
PUT /api/v1/admin/me/password Change password; same body as below
POST /api/v1/admin/me/change-password Change password; body current_password, new_password; answers a new access_token and ends the account’s other sessions
DELETE /api/v1/admin/me/account Deactivate own account; body password, confirm_deletion
GET /api/v1/admin/me/activity Own account summary, not an activity log: user_id, email, created_at, team_memberships (oldest first, the first being the team the session works in), active_api_keys and account_status; last_login is always null

Despite the /admin prefix, the /admin/me/... routes act on the caller’s own account and need only a valid token.

A wrong current_password (or password on account deletion) counts towards the login lockout, and a locked account answers 429 there as at login.

Every route that sets a password hashes it with Argon2id through fastapi-users’ PasswordHelper, the same helper login verifies with; bcrypt hashes from older releases still verify.

Password Policy

Every route that sets a password applies the same rule (UserManager.validate_password()): 12 to 128 characters, not containing the account’s email address or the part before the @ (when it has at least 4 characters), and not one of the 10,000 most common passwords of that length (a list vendored in identity). There are no composition rules. The authentication guide explains the choices.

Route Refusal
POST /api/v1/auth/register 400, error.details.code REGISTER_INVALID_PASSWORD
POST /api/v1/auth/reset-password 400, error.details.code RESET_PASSWORD_INVALID_PASSWORD
PATCH /api/v1/users/{id} (superuser) 400, error.details.code UPDATE_USER_INVALID_PASSWORD
POST /api/v1/admin/me/change-password, PUT /api/v1/admin/me/password 400; 422 for fewer than 12 or more than 128 characters
POST /api/v1/admin/teams/{team_id}/members 400; 422 for fewer than 12 or more than 128 characters

error.message carries the reason, for example:

{"error": {"code": 400, "message": "The password must be at least 12 characters long.",
  "type": "HTTPException", "request_id": "...",
  "details": {"code": "REGISTER_INVALID_PASSWORD",
              "reason": "The password must be at least 12 characters long."}}}
curl -s --cacert open-security-gateway/ssl/wildbox.crt \
  -H "Authorization: Bearer $TOKEN" https://localhost/api/v1/identity/users/me

API Keys

Personal API keys, sent to the gateway as X-API-Key: <key>. The secret is returned once, when the key is created.

Method Path Purpose
POST /api/v1/api-keys Create a key for the caller
GET /api/v1/api-keys List the caller’s own keys
GET /api/v1/api-keys/{key_prefix} Show one of the caller’s keys
DELETE /api/v1/api-keys/{key_prefix} Revoke one of the caller’s keys

These act in the caller’s primary team and on the keys the caller created: another member’s key answers 404, as a key that does not exist does. They used to match any key of the team, so a member could revoke a teammate’s or the owner’s key (#664).

All the keys of a team, whoever created them:

Method Path Role in the team
POST /api/v1/teams/{team_id}/api-keys admin or owner
GET /api/v1/teams/{team_id}/api-keys any member
GET /api/v1/teams/{team_id}/api-keys/{key_prefix} any member
DELETE /api/v1/teams/{team_id}/api-keys/{key_prefix} admin or owner

Revocation Takes Effect at Once

A revoked key is refused by the gateway on the next request. Before it marks the key inactive, identity has the gateway refuse it, by the key’s id, and the gateway confirms; if it does not, the key stays active and the DELETE answers 503, to be repeated. The same holds, with the same 503, for every other change that disables keys: deactivating or deleting an account (all its keys and sessions), deleting one’s own account, and removing a member from a team (the member’s keys for that team). A key’s expires_at is honored even when the gateway has a decision for the key in its cache. See Revoking an API key.

Removing a member from a team, and deleting an account, also tell guardian, once the change is made, so that the user is no longer accepted or named as one of the team’s users there. That notice never fails the request: see Team memberships.

/internal/authorize reports, for an API key, api_key_id (what the gateway revokes the key by) and credential_expires_at (the key’s expiry in epoch seconds, or null); for a session token, credential_expires_at is the token’s exp.


Teams

Method Path Purpose
GET /api/v1/admin/teams/{team_id}/members List members
POST /api/v1/admin/teams/{team_id}/members Create an account in the team; body email, password, role
PUT /api/v1/admin/teams/{team_id} Update a team
DELETE /api/v1/admin/teams/{team_id}/members/{user_id} Remove a member

Listing members is open to any member of the team. Creating, updating and removing need the owner or admin role in that team, or a superuser.

Create a Member

POST /api/v1/admin/teams/{team_id}/members creates a new account whose only membership is this team; it gets no team of its own, so its sessions work in this team. There is no adding of an existing account, and no email is sent: the administrator gives the new member the initial password.

{"email": "new.member@example.com", "password": "an initial password", "role": "member"}
  • password: must meet the password policy. The account is created with must_change_password: true.
  • role: member (the default) or admin, strictly below the caller’s own role: an owner (or a superuser) creates admins and members, an admin creates members. owner is never accepted.
Status When
201 Created; the body is the new membership, as in the member list
403 The caller is not an owner or admin of the team, or the role is not one it may give
404 A superuser named a team that does not exist
400 The password does not meet the policy; error.message says why
409 The email is already registered (in any letter case)
422 Invalid email, unknown role, or a password under 12 or over 128 characters

The creation is logged (audit: team_member_created) with the caller, the new account, the team and the role, never the password.

Accounts That Must Change Their Password

While must_change_password is true (GET /api/v1/users/me reports it), the account’s sessions can only read the account (GET /api/v1/users/me), change the password (POST /api/v1/admin/me/change-password, or PUT /api/v1/admin/me/password) and log out. Every other identity route answers 403 with the message PASSWORD_CHANGE_REQUIRED, and the gateway answers 403 {"error": "PASSWORD_CHANGE_REQUIRED"} for every other service, because /internal/authorize reports password_change_required: true. Changing the password clears the flag and returns a new token, as for any password change.


Platform Administration

These require a superuser (is_superuser); being the owner or admin of a team is not enough.

Method Path Purpose
GET /api/v1/admin/users List users
GET /api/v1/admin/users/{user_id} One user with teams
GET /api/v1/admin/users/{user_id}/can-delete Check whether a user can be deleted
PATCH /api/v1/admin/users/{user_id}/status Activate or deactivate
PATCH /api/v1/admin/users/{user_id}/superuser Grant or revoke superuser
PATCH /api/v1/admin/users/{user_id}/role Promote or demote a superuser
DELETE /api/v1/admin/users/{user_id} Delete a user
GET /api/v1/analytics/admin/system-stats Platform statistics
GET /api/v1/analytics/admin/user-activity User activity
GET /api/v1/analytics/admin/usage-summary Usage summary
GET /api/v1/admin/metrics User, team and active API-key counts

/api/v1/admin/metrics used to accept the X-Gateway-Secret header in place of a user, and the gateway sent that header on every request it passed to identity, so anyone could read the counts (#664). It now takes a superuser’s bearer token like the other routes here, and the gateway sends its secret only on requests it authenticated itself.

fastapi-users also registers GET, PATCH and DELETE on /api/v1/users/{id} for superusers.

Deactivating an account (through either route) or deleting it ends its API keys and sessions at the gateway before the change is committed; when the gateway does not confirm, nothing changes and the answer is 503.


Service Routes

Method Path Purpose
GET /health Health check
GET / Service information
GET /metrics Prometheus exposition, scraped by monitoring/prometheus.yml; not routed by the gateway
POST /internal/authorize Token and API-key validation for the gateway; requires X-Gateway-Secret and is not routed by the gateway
POST /internal/team-contacts For guardian’s worker: the address and role of the active members of one team, selected by user_ids or by roles. Requires X-Guardian-Contacts-Secret (GUARDIAN_CONTACTS_SECRET, not the gateway’s secret) and is not routed by the gateway

/internal/authorize is the only identity route that accepts X-Gateway-Secret. The gateway calls it on its own behalf, with the secret from its environment; no gateway location maps a client path to /internal.


Errors

Every error of the service has the body every Wildbox service answers:

{
  "error": {
    "code": 404,
    "message": "User not found",
    "type": "HTTPException",
    "request_id": "6f1c2d..."
  }
}

error.code is the HTTP status, error.message the reason and error.request_id the correlation id, the X-Request-ID the gateway sent or one the service generated. There is no top-level detail.

Status error.message error.type
404, raised by a route The route’s own message: User not found, Team not found, API key not found HTTPException
404, no such path Not Found HTTPException
422, invalid request Request validation failed; error.details lists the field errors ValidationError
500, unhandled error An internal error occurred; the cause is in the service log under the same request id InternalServerError
503, database unreachable Database temporarily unavailable HTTPException

A field error says where and what, and does not repeat what was sent:

{"error": {"code": 422, "message": "Request validation failed",
  "type": "ValidationError", "request_id": "...",
  "details": [{"type": "string_too_short", "loc": ["body", "new_password"],
               "msg": "String should have at least 12 characters"}]}}

Each item has type, loc and msg only. The refused value (input in FastAPI’s default body) is not returned: for a missing field it was the whole request body, a password in it included.

A fastapi-users error keeps its code at error.details (see Password Policy); when the detail is a bare code, such as LOGIN_BAD_CREDENTIALS, the code is error.message.