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

                         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

3. OIDC Discovery

#Endpoint

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:

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:

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

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:

                    AuthX
                      │
              RSA Private Key
                      │
                      ▼
                Sign JWT
                      │
                      ▼
              Access / Refresh JWT
                      │
                      ▼
              Consumer Application
                      │
                      │ GET /jwks
                      ▼
                RSA Public Key
                      │
                      ▼
                Verify JWT

Current key metadata includes:

kty = RSA
use = sig
alg = RS256
kid = authx-key-1

The private signing key remains exclusively under AuthX's control.

5. Token API

#Endpoint

POST /token
Content-Type: application/json

The token endpoint authenticates an identity and issues an access-token / refresh-token pair.

#Password grant request

{
  "grant_type": "password",
  "email": "user@example.com",
  "password": "..."
}

#Successful response

{
  "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:

HTTP 401 Unauthorized

6. Refresh Token API

#Endpoint

POST /token/refresh
Content-Type: application/json

#Request

{
  "refresh_token": "..."
}

AuthX implements refresh-token rotation.

The high-level flow is:

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

GET /userinfo
Authorization: Bearer <access-token>

The endpoint returns information about the identity represented by the supplied access token.

Example response:

{
  "sub": "<identity-uuid>",
  "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

GET /health

The health endpoint does not require authentication.

Example logical response:

{
  "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:

DjangoPlay
    │
    │ server-to-server
    ▼
AuthX /internal/*

Available operations include:

All internal endpoints require server-to-server authentication using:

X-Service-Token: <INTERNAL_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

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.

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.