AuthX exposes an OpenID Connect–oriented API surface for authentication, token issuance, token refresh, identity discovery, and local JWT verification.

The OIDC endpoints form the public authentication boundary of AuthX.

Trusted backend identity-management operations are exposed separately through the Internal Identity API and are not part of this interface.

1. OIDC Architecture

flowchart TD

    CLIENT["Client Application<br/><small>Web / Backend Consumer</small>"]

    DISCOVERY["OIDC Discovery<br/><small>/.well-known/openid-configuration</small>"]

    TOKEN["Token Endpoint<br/><small>/token</small>"]

    REFRESH["Refresh Endpoint<br/><small>/token/refresh</small>"]

    USERINFO["UserInfo Endpoint<br/><small>/userinfo</small>"]

    JWKS["JWKS Endpoint<br/><small>/jwks</small>"]

    AUTHX["AuthX<br/><small>Identity & Token Service</small>"]

    DB[("PostgreSQL<br/><small>Identity Store</small>")]

    KEY["RSA Signing Key<br/><small>RS256</small>"]

    CLIENT --> DISCOVERY
    CLIENT --> TOKEN
    CLIENT --> REFRESH
    CLIENT --> USERINFO
    CLIENT --> JWKS

    DISCOVERY --> AUTHX
    TOKEN --> AUTHX
    REFRESH --> AUTHX
    USERINFO --> AUTHX
    JWKS --> KEY

    AUTHX --> DB
    AUTHX --> KEY

    classDef client fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a
    classDef endpoint fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef auth fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c
    classDef db fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef key fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class CLIENT client
    class DISCOVERY,TOKEN,REFRESH,USERINFO,JWKS endpoint
    class AUTHX auth
    class DB db
    class KEY key
`

The main OIDC flow is:

text

Client
   │
   ├── Discovery ───────────────► AuthX
   │
   ├── Credentials ─────────────► /token
   │                              │
   │                              ▼
   │                         Access Token
   │                         Refresh Token
   │
   ├── Refresh Token ───────────► /token/refresh
   │                              │
   │                              ▼
   │                         New Token Pair
   │
   ├── Access Token ────────────► /userinfo
   │
   └── JWKS ────────────────────► /jwks
                                  │
                                  ▼
                             Public Key

2. Discovery

The OIDC discovery endpoint is:

http

GET /.well-known/openid-configuration

The discovery document describes the AuthX OIDC configuration and exposes the locations and capabilities required by compatible consumers.

The response contains information including:

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

2.1 Current Advertised Capabilities

The current implementation advertises:

text

response_types_supported
    ["token"]

subject_types_supported
    ["public"]

scopes_supported
    ["openid", "email", "profile"]

grant_types_supported
    ["password", "refresh_token"]

These values describe the currently supported authentication/token interface.

Consumers should use the discovery document as the authoritative source for the endpoint locations and advertised capabilities of a deployed AuthX instance.

3. Issuer

The discovery document exposes the configured AuthX issuer:

text

issuer

The issuer identifies the AuthX deployment that issues JWTs.

JWT consumers should validate the issuer claim against their configured expected AuthX issuer.

The issuer is configured through:

text

JWT_ISSUER

Production deployments should use an HTTPS issuer.

Example:

text

JWT_ISSUER=https://auth.example.com

The issuer must be an HTTP(S) URL without a query string or fragment.

4. JWKS

AuthX exposes its public signing keys through:

http

GET /jwks

The endpoint returns a JSON Web Key Set containing the public RSA key used to verify AuthX-signed JWTs.

The private signing key is never exposed through this endpoint.

flowchart LR

    AUTHX["AuthX"]

    PRIVATE["RSA Private Key<br/><small>Signing only</small>"]

    JWT["Signed JWT<br/><small>RS256</small>"]

    JWKS["/jwks<br/><small>Public JWK Set</small>"]

    PUBLIC["RSA Public Key"]

    CONSUMER["JWT Consumer"]

    AUTHX --> PRIVATE
    PRIVATE -->|"sign"| JWT

    AUTHX --> JWKS
    JWKS --> PUBLIC
    PUBLIC --> CONSUMER

    JWT -->|"verify signature"| CONSUMER

    classDef auth fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c
    classDef key fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef token fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef consumer fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a

    class AUTHX auth
    class PRIVATE,PUBLIC,JWKS key
    class JWT token
    class CONSUMER consumer

Consumers can cache the JWKS and perform JWT signature verification locally.

4.1 Current Key Metadata

The current signing key metadata includes:

text

kty = RSA

use = sig

alg = RS256

kid = authx-key-1

The kid allows consumers to select the appropriate public key when multiple keys are present in a JWKS document.

5. Token Endpoint

The token endpoint is:

http

POST /token
Content-Type: application/json

The current implementation supports the password grant.

5.1 Password Grant

Request:

json

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

AuthX validates the supplied credentials against the authoritative identity store.

A successful authentication produces an access token and refresh token.

Example response:

json

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

5.2 Authentication Flow

sequenceDiagram

    participant C as Client
    participant A as AuthX
    participant DB as PostgreSQL

    C->>A: POST /token
    A->>DB: Resolve identity
    DB-->>A: Identity + credential state
    A->>A: Validate credentials
    A->>A: Create access JWT
    A->>A: Create refresh JWT
    A->>DB: Persist refresh-token state
    A-->>C: Access + refresh tokens

The access token is intended for authenticated API operations.

The refresh token is associated with server-side refresh-token state so that AuthX can perform rotation and revocation.

6. Invalid Credentials

Invalid authentication credentials result in:

text

HTTP 401 Unauthorized

The client must not interpret an authentication failure as an internal service failure.

7. Access Tokens

AuthX issues signed JWT access tokens.

The access token is:

text

JWT
+
RS256 signature

The JWT contains identity and token metadata required by consumers.

Current access-token claims include:

text

sub

iss

aud

iat

exp

jti

type = access

email

username

is_verified

is_staff

is_superuser

The access token is intended to be validated by the consuming application.

Consumers should validate at minimum:

text

Signature
Issuer
Audience
Expiration
Token type

where applicable to the consuming application's authentication policy.

8. Refresh Tokens

Refresh tokens are issued together with access tokens.

A refresh request is sent to:

http

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

Request:

json

{
  "refresh_token": "..."
}

The refresh token contains:

text

sub

iss

aud

iat

exp

jti

type = refresh

9. Refresh Token Rotation

AuthX uses refresh-token rotation.

When a valid refresh token is presented:

text

Existing refresh token
        │
        ▼
Validate token
        │
        ▼
Revoke presented token
        │
        ▼
Issue new access token
        │
        ▼
Issue new refresh token

The presented refresh token is marked revoked before the replacement token pair is issued.

This makes refresh tokens stateful from the server's perspective even though the token itself is a JWT.

9.1 Refresh Flow

sequenceDiagram

    participant C as Client
    participant A as AuthX
    participant DB as PostgreSQL

    C->>A: POST /token/refresh
    A->>A: Validate refresh JWT
    A->>DB: Check JTI / revocation state
    DB-->>A: Refresh token state
    A->>DB: Revoke presented token
    A->>A: Create new access JWT
    A->>A: Create new refresh JWT
    A->>DB: Persist new refresh-token state
    A-->>C: New access + refresh tokens

A previously rotated refresh token must not be reused as a valid refresh credential.

10. UserInfo

The UserInfo endpoint is:

http

GET /userinfo
Authorization: Bearer <access-token>

The endpoint requires a valid AuthX access token.

Example response:

json

{
  "sub": "<identity-uuid>",
  "email": "user@example.com",
  "email_verified": true,
  "preferred_username": "user"
}

The sub value identifies the AuthX identity.

Consumers should use sub as the stable identity identifier rather than treating email as the primary immutable identity key.

11. UserInfo Request Flow

sequenceDiagram

    participant C as Client
    participant A as AuthX

    C->>A: GET /userinfo
    Note over C,A: Authorization: Bearer <access-token>
    A->>A: Validate JWT
    A->>A: Resolve identity
    A-->>C: UserInfo response

12. Endpoint Summary

Endpoint	Method	Purpose
`/.well-known/openid-configuration`	`GET`	OIDC discovery
`/jwks`	`GET`	Public JWT verification keys
`/token`	`POST`	Obtain access/refresh tokens
`/token/refresh`	`POST`	Rotate refresh token and issue new token pair
`/userinfo`	`GET`	Retrieve authenticated identity information

13. Public OIDC vs Internal API

AuthX separates public authentication operations from trusted backend identity management.

text

                    AuthX
                      │
          ┌───────────┴───────────┐
          │                       │
          ▼                       ▼
     Public OIDC              Internal API
          │                       │
          │                       │ X-Service-Token
          ▼                       ▼
       Clients             Trusted Backends
          │                       │
          ▼                       ▼
    Token / UserInfo       Identity Management
    Discovery / JWKS       Create / Read / Update

The public OIDC surface is intended for authentication and token consumption.

The Internal Identity API is intended for trusted backend applications such as DjangoPlay.

14. JWT Verification by Consumers

A consumer does not need access to the AuthX private signing key.

The recommended model is:

text

AuthX
  │
  ├── Private RSA key
  │       │
  │       └── signs JWT
  │
  └── /jwks
          │
          └── exposes public key
                    │
                    ▼
              JWT Consumer
                    │
                    └── verifies signature

A Django consumer such as DjangoPlay can therefore validate AuthX JWTs without making AuthX part of every authenticated API request.

15. Security Considerations

The following principles apply to the OIDC API:

AuthX retains the JWT signing private key.
Consumers receive only public verification keys.
Consumers should validate issuer and audience.
Access tokens should be treated as bearer credentials.
Refresh tokens must be protected as sensitive credentials.
Refresh-token rotation and revocation state are maintained by AuthX.
Credentials supplied to /token must only be transmitted over HTTPS in production.
The Internal Identity API must not be confused with the public OIDC API.

16. Summary

The AuthX OIDC API provides the public authentication and token interface for the identity platform.

Its current capabilities are:

Capability	Implementation
Discovery	`/.well-known/openid-configuration`
Token issuance	`/token`
Grant	`password`
Token refresh	`/token/refresh`
Refresh rotation	Enabled
User information	`/userinfo`
Public key distribution	`/jwks`
JWT algorithm	RS256
Key type	RSA
Subject type	Public
Scopes	`openid`, `email`, `profile`
Identity authority	AuthX

The architectural boundary is straightforward:

AuthX authenticates identities and issues signed tokens; consumers verify those tokens using AuthX's published public keys.

AuthX — OIDC API

#1. OIDC Architecture

2. Discovery

#2.1 Current Advertised Capabilities

3. Issuer

4. JWKS

#4.1 Current Key Metadata

5. Token Endpoint

#5.1 Password Grant

#5.2 Authentication Flow

6. Invalid Credentials

7. Access Tokens

8. Refresh Tokens

9. Refresh Token Rotation

#9.1 Refresh Flow

10. UserInfo

11. UserInfo Request Flow

12. Endpoint Summary

13. Public OIDC vs Internal API

14. JWT Verification by Consumers

15. Security Considerations

16. Summary

1. OIDC Architecture

2.1 Current Advertised Capabilities

4.1 Current Key Metadata

5.1 Password Grant

5.2 Authentication Flow

9.1 Refresh Flow