---
since: 1.1.1
---

# **API Schemas**

This document describes the request and response schemas exposed by AuthX.

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.

```text
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.

```text
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.

```text
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:

```text
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.

```text
sub

email

email_verified

preferred_username
```

Example:

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

```text
password_hash
is_staff
is_superuser
created_at
updated_at
```

---

## **5. Token Response**

### `TokenResponse`

Returned when AuthX successfully issues or refreshes tokens.

```text
access_token

refresh_token

token_type

expires_in
```

Example:

```json
{
  "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.

```text
keys: list[dict]
```

The response follows the JSON Web Key Set structure:

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

```text
                         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.