Auth API
Operational

Standalone Authentication Service

Domain-agnostic authentication API providing credential verification, JWT token management, refresh token rotation, and revocation.

Swagger UI OpenAPI Spec
Configuration
Access Token TTL
15 min
Refresh Token TTL
7 days
Algorithm
HS256
Auth Header
x-application-secret
Internal API
POST /auth/register

Create a new account. Called by an External API when a new user or device is created on their side.

Request
POST /auth/register Content-Type: application/json x-application-secret: YOUR_SECRET { "identifier": "[email protected]", "password": "P@ssw0rd123", "type": "user", "refId": "507f1f77bcf86cd799439011" }
201 Response
{ "accountId": "a3b1c9d2-..." }
POST /auth/login

Authenticate and get tokens. Auth API verifies credentials, resolves the application, then calls back the External API's claims endpoint.

Flow: Verify password → Find application by secret → Call POST {claimsUrl} with account info → Sign JWT with returned claims → Generate refresh token → Return both.
Request
POST /auth/login Content-Type: application/json x-application-secret: YOUR_SECRET { "identifier": "[email protected]", "password": "P@ssw0rd123" }
200 Response
{ "accessToken": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "a1b2c3d4e5f6..." }
POST /auth/refresh

Rotate refresh token and get new tokens. Old refresh token is revoked. Fresh claims are fetched from the External API.

Request
POST /auth/refresh Content-Type: application/json x-application-secret: YOUR_SECRET { "refreshToken": "a1b2c3d4e5f6..." }
200 Response
{ "accessToken": "eyJhbGciOiJIUzI1NiIs...(new)", "refreshToken": "x9y8z7w6v5u4...(new)" }
POST /auth/revoke

Revoke a refresh token (logout). The access token is not invalidated — it expires naturally based on its TTL.

Request
POST /auth/revoke Content-Type: application/json x-application-secret: YOUR_SECRET { "refreshToken": "a1b2c3d4e5f6..." }
204 Response
No content
External API (Claims Callback)
POST {claimsUrl}

This endpoint must be implemented by the External API. Auth API calls it during login and refresh to fetch claims that will be embedded in the JWT access token.

The claimsUrl is configured per application in the applications collection. Auth API sends the account info and forwards the x-application-secret header so the External API can verify the caller.
Request (sent by Auth API)
POST http://your-api.com/auth/claims Content-Type: application/json x-application-secret: YOUR_SECRET { "accountId": "a3b1c9d2-...", "type": "user", "refId": "507f1f77bcf86cd799439011" }
200 Example Response
// Return any claims to embed in the JWT { "role": "admin", "firstName": "John", "lastName": "Doe", "permissions": ["read", "write"] }