API Schemas

AuthX separates its schemas according to the API surface: internal identity-management operations, public identity information, token operations, and JWKS responses.

#1. Identity Create Request

#IdentityCreateRequest

Used by trusted backend consumers to create a new AuthX identity.

email: EmailStr

username: 1..150 characters

password: optional
         minimum 8 characters

sso_provider: optional

sso_id: optional

is_active: default true

is_verified: default false

is_staff: default false

is_superuser: default false

The password field represents the plaintext credential supplied during the creation request. AuthX hashes the password before persistence.

The resulting password hash is never exposed through an API response.

#2. Identity Update Request

#IdentityUpdateRequest

Used to update an existing identity through the internal identity-management API.

All supported fields are optional.

email: optional

username: optional

password: optional

sso_provider: optional

sso_id: optional

is_active: optional

is_verified: optional

is_staff: optional

is_superuser: optional

Only supplied fields are updated.

If password is supplied, AuthX hashes the new password before persisting it.

#3. Identity Response

#IdentityResponse

Used by the internal identity-management API when returning an identity.

id

email

username

sso_provider

sso_id

is_active

is_verified

is_staff

is_superuser

created_at

updated_at

last_login

The response deliberately does not contain:

password
password_hash

Password hashes are never returned to API consumers.

#4. Public Identity Response

#IdentityPublicResponse

The /userinfo endpoint exposes a deliberately smaller identity representation.

sub

email

email_verified

preferred_username

Example:

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

This schema is intentionally different from IdentityResponse.

The public identity API does not expose internal account-management fields such as:

password_hash
is_staff
is_superuser
created_at
updated_at

#5. Token Response

#TokenResponse

Returned when AuthX successfully issues or refreshes tokens.

access_token

refresh_token

token_type

expires_in

Example:

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

The access_token is used for authenticated API access.

The refresh_token is used with the refresh-token endpoint to obtain a new token pair.

#6. JWKS Response

#JWKSResponse

The /jwks endpoint returns the public signing-key set.

keys: list[dict]

The response follows the JSON Web Key Set structure:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "authx-key-1"
    }
  ]
}

Only public key material is exposed through JWKS. AuthX's JWT signing private key is never included in the response.

#7. Schema Security Boundary

The schemas reflect the separation between AuthX's internal and public API surfaces:

                         AuthX
                           │
             ┌─────────────┴─────────────┐
             │                           │
             ▼                           ▼
       Internal API                 Public API
             │                           │
             ▼                           ▼
 IdentityCreateRequest          TokenResponse
 IdentityUpdateRequest          IdentityPublicResponse
 IdentityResponse               JWKSResponse
             │                           │
             ▼                           ▼
     Trusted backends             API consumers

The internal schemas may expose administrative identity attributes because they are used by trusted backend services, while public schemas expose only the information required by consuming applications.