--- since: 1.1.1 --- # **API Documentation** AuthX exposes two API surfaces: 1. **Public OIDC-compatible authentication APIs** — used by clients and consuming applications for authentication, token issuance, token refresh, user information, discovery, and public-key retrieval. 2. **Internal identity-management APIs** — used by trusted backend applications such as DjangoPlay for managing identities. --- ## **1. API Surface Overview** ```text AuthX API │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ Public OIDC APIs Internal APIs │ │ ┌──────┼──────┐ X-Service-Token │ │ │ │ ▼ ▼ ▼ ▼ Discovery Token Userinfo Identity Management JWKS Refresh Health ``` The public API surface does **not** require the internal service token. The `/internal/*` surface is protected separately and is intended only for trusted server-to-server communication. --- # **2. Public API Endpoints** | Method | Path | Purpose | Authentication | | ------ | ----------------------------------- | ------------------------------------------- | ----------------------------- | | `GET` | `/.well-known/openid-configuration` | OIDC discovery metadata | None | | `GET` | `/jwks` | Retrieve public JWT signing keys | None | | `POST` | `/token` | Authenticate and issue tokens | Credentials in request body | | `POST` | `/token/refresh` | Rotate refresh token and issue new tokens | Refresh token in request body | | `GET` | `/userinfo` | Retrieve authenticated identity information | Bearer access token | | `GET` | `/health` | Service health check | None | --- # **3. OIDC Discovery** ### Endpoint ```http GET /.well-known/openid-configuration ``` The discovery endpoint exposes the AuthX OIDC configuration so consuming applications can discover the relevant endpoints and supported authentication capabilities. The response includes metadata such as: ```text issuer token_endpoint userinfo_endpoint jwks_uri response_types_supported subject_types_supported id_token_signing_alg_values_supported scopes_supported grant_types_supported ``` The current implementation advertises: ```text response_types_supported = ["token"] subject_types_supported = ["public"] scopes_supported = ["openid", "email", "profile"] grant_types_supported = ["password", "refresh_token"] ``` The configured issuer is also exposed through the discovery document and is used when validating JWT issuer claims. --- # **4. JWKS** ### Endpoint ```http GET /jwks ``` AuthX exposes its RSA public signing key as a **JSON Web Key Set (JWKS)**. Consumers use this endpoint to obtain the public key required to verify JWT signatures without receiving the private signing key. Conceptually: ```text AuthX │ RSA Private Key │ ▼ Sign JWT │ ▼ Access / Refresh JWT │ ▼ Consumer Application │ │ GET /jwks ▼ RSA Public Key │ ▼ Verify JWT ``` Current key metadata includes: ```text kty = RSA use = sig alg = RS256 kid = authx-key-1 ``` The private signing key remains exclusively under AuthX's control. --- # **5. Token API** ### Endpoint ```http POST /token Content-Type: application/json ``` The token endpoint authenticates an identity and issues an access-token / refresh-token pair. ### Password grant request ```json { "grant_type": "password", "email": "user@example.com", "password": "..." } ``` ### Successful response ```json { "access_token": "...", "refresh_token": "...", "token_type": "Bearer", "expires_in": 3600 } ``` The access token is a signed JWT. The refresh token is also issued as a JWT but is associated with server-side refresh-token state so that it can be revoked and rotated. ### Invalid credentials Invalid authentication credentials result in: ```text HTTP 401 Unauthorized ``` --- # **6. Refresh Token API** ### Endpoint ```http POST /token/refresh Content-Type: application/json ``` ### Request ```json { "refresh_token": "..." } ``` AuthX implements **refresh-token rotation**. The high-level flow is: ```text Client │ │ refresh_token ▼ AuthX │ ├── Validate JWT │ ├── Check refresh-token state │ ├── Revoke presented token │ └── Issue new token pair │ ▼ New access_token + refresh_token ``` The presented refresh token is marked revoked before the replacement access/refresh pair is issued. This prevents a successfully used refresh token from remaining reusable indefinitely. --- # **7. Userinfo API** ### Endpoint ```http GET /userinfo Authorization: Bearer ``` The endpoint returns information about the identity represented by the supplied access token. Example response: ```json { "sub": "", "email": "user@example.com", "email_verified": true, "preferred_username": "user" } ``` The `sub` value identifies the AuthX identity. The endpoint requires a valid bearer access token. --- # **8. Health API** ### Endpoint ```http GET /health ``` The health endpoint does not require authentication. Example logical response: ```json { "status": "ok", "service": "authx" } ``` It is intended for service-level health checks and operational monitoring. --- # **9. Internal Identity API** AuthX also exposes an internal identity-management API for trusted backend consumers. Typical consumers include: ```text DjangoPlay │ │ server-to-server ▼ AuthX /internal/* ``` Available operations include: | Method | Path | Purpose | | -------- | --------------------------------------- | ---------------------------------------- | | `POST` | `/internal/identities` | Create identity | | `GET` | `/internal/identities/{id}` | Retrieve identity by UUID | | `GET` | `/internal/identities/by-email/{email}` | Retrieve identity by email | | `GET` | `/internal/identities/by-sso/lookup` | Retrieve identity by SSO provider and ID | | `PATCH` | `/internal/identities/{id}` | Update identity | | `DELETE` | `/internal/identities/{id}` | Soft-delete identity | All internal endpoints require server-to-server authentication using: ```http X-Service-Token: ``` The service token must remain confidential and must never be exposed to: * Web browsers * Mobile clients * Frontend JavaScript * Public API consumers * Other untrusted clients --- # **10. Complete Endpoint Map** ```text AuthX │ ├── Public API │ │ │ ├── GET /.well-known/openid-configuration │ │ └── OIDC discovery │ │ │ ├── GET /jwks │ │ └── JWT public keys │ │ │ ├── POST /token │ │ └── Authentication / token issuance │ │ │ ├── POST /token/refresh │ │ └── Refresh-token rotation │ │ │ ├── GET /userinfo │ │ └── Current identity information │ │ │ └── GET /health │ └── Health check │ └── Internal API │ └── /internal/identities/* │ ├── POST /internal/identities ├── GET /internal/identities/{id} ├── GET /internal/identities/by-email/{email} ├── GET /internal/identities/by-sso/lookup ├── PATCH /internal/identities/{id} └── DELETE /internal/identities/{id} ``` --- # **11. API Security Model** The two API surfaces have deliberately different trust models. | API Surface | Intended Consumer | Authentication | | ---------------- | -------------------------------- | ------------------------------------------------ | | Public OIDC APIs | Clients / consuming applications | Credentials or Bearer JWT, depending on endpoint | | JWKS | JWT consumers | Public endpoint | | Health | Infrastructure / monitoring | None | | Internal APIs | Trusted backend services | `X-Service-Token` | This separation is important: **possession of a valid user access token does not replace the internal service credential required for identity-management operations.** --- # **12. API Documentation** AuthX's API is documented through its OpenAPI interface. For the running service, the API documentation should be treated as the authoritative interface reference for: * Request schemas * Response schemas * HTTP status codes * Endpoint parameters * Authentication requirements * Generated OpenAPI definitions This document provides the architectural API overview; it is not intended to replace the generated API specification.