---
since: 1.2.1
---

# DjangoPlay ↔ AuthX Integration Architecture

This document describes how **DjangoPlay** integrates with **AuthX** for identity, authentication, and SSO.

DjangoPlay remains the application platform and domain owner, while AuthX acts as the centralized identity service.

---

## 1. Integration Overview

DjangoPlay and AuthX are separate applications with clearly defined responsibilities.

DjangoPlay owns application-level user data, domain relationships, authorization, and business workflows.

AuthX owns identity and authentication concerns such as credentials, authentication state, SSO identity linkage, and token handling.

```mermaid
flowchart LR

    USER["Users / Clients"]

    subgraph DJANGO["DjangoPlay"]
        UI["Web UI / API"]
        AUTHFLOW["Authentication Flows"]
        SYNC["Identity Synchronization"]
        CLIENT["AuthXClient"]
        LOCAL["Local UserIdentity Mirror"]
        POLICY["Application Authorization"]
    end

    subgraph AUTHX["AuthX"]
        API["Identity / Authentication API"]
        SERVICE["Identity Service"]
        DB["AuthX PostgreSQL"]
    end

    USER --> UI
    UI --> AUTHFLOW
    AUTHFLOW --> CLIENT
    CLIENT -->|"HTTP + X-Service-Token"| API

    API --> SERVICE
    SERVICE --> DB

    API -->|"Identity response"| SYNC
    SYNC --> LOCAL

    LOCAL --> POLICY

    classDef client fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef django fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef data fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class USER client
    class UI,AUTHFLOW,SYNC,CLIENT,LOCAL,POLICY django
    class API,SERVICE authx
    class DB data
```

### Architectural principle

> **AuthX is the identity authority; DjangoPlay maintains a local application-level mirror of the identity.**

The local mirror exists so that DjangoPlay can maintain application relationships, permissions, profiles, and domain-specific data without making AuthX the owner of the Django application's domain model.

---

## 2. Responsibility Boundary

The integration is intentionally divided into two responsibility domains.

### DjangoPlay owns

- User-facing application flows
- Application-specific user and profile data
- Local `UserIdentity` representation
- Application relationships and foreign keys
- Groups and application permissions
- Policy-based authorization
- Domain workflows
- Integration with AuthX through `AuthXClient`

### AuthX owns

- Identity records
- Authentication credentials
- Password hashing
- Authentication workflows
- SSO identity linkage
- Identity state
- JWT/token operations
- Authoritative identity information

This separation prevents authentication concerns from becoming distributed throughout the DjangoPlay application.

---

## 3. Identity Architecture

The identity relationship can be represented as:

```mermaid
flowchart TD

    USER["User"]

    subgraph DJANGO["DjangoPlay"]
        FLOW["Signup / Login / SSO Flow"]
        CLIENT["AuthXClient"]
        MIRROR["UserIdentity<br/><small>Local application mirror</small>"]
        DATA["Application Data<br/><small>Profiles • Relationships • Permissions</small>"]
    end

    subgraph AUTHX["AuthX"]
        IDENTITY["Authoritative Identity"]
        CREDENTIALS["Credentials / Authentication"]
        SSO["SSO Identity Linkage"]
        AUTHDB["AuthX PostgreSQL"]
    end

    USER --> FLOW
    FLOW --> CLIENT
    CLIENT --> IDENTITY

    IDENTITY --> CREDENTIALS
    IDENTITY --> SSO
    IDENTITY --> AUTHDB

    IDENTITY -->|"Identity data"| MIRROR
    MIRROR --> DATA

    classDef user fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef django fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef db fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class USER user
    class FLOW,CLIENT,MIRROR,DATA django
    class IDENTITY,CREDENTIALS,SSO authx
    class AUTHDB db
```

The important distinction is:

```text
AuthX
    ↓
Authoritative identity

DjangoPlay
    ↓
Local identity mirror + application data
```

---

## 4. DjangoPlay Integration Components

The DjangoPlay side of the integration is centered around the AuthX client and identity synchronization services.

The general structure is:

```text
Authentication Flow
       │
       ▼
AuthX Integration Service
       │
       ▼
AuthXClient
       │
       ▼
AuthX HTTP API
```

The synchronization layer is responsible for keeping the local `UserIdentity` representation aligned with the authoritative AuthX identity.

Typical operations include:

- Create identity
- Update identity
- Retrieve identity
- Lookup identity by email
- Synchronize identity information
- Maintain the local identity mirror

---

## 5. AuthX Client

DjangoPlay communicates with AuthX through an HTTP client abstraction rather than making raw HTTP calls throughout the application.

Conceptually:

```mermaid
flowchart LR

    FLOW["DjangoPlay Authentication Flow"]
    SERVICE["Identity Sync / Auth Service"]
    CLIENT["AuthXClient"]
    HTTP["HTTP Request"]
    AUTHX["AuthX API"]

    FLOW --> SERVICE
    SERVICE --> CLIENT
    CLIENT --> HTTP
    HTTP -->|"X-Service-Token"| AUTHX

    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef transport fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class FLOW,SERVICE,CLIENT app
    class HTTP transport
    class AUTHX authx
```

This provides a single integration boundary for:

- Base URL configuration
- Service authentication
- HTTP communication
- Request handling
- AuthX API interaction

This also prevents AuthX-specific HTTP details from leaking into domain applications.

---

## 6. DjangoPlay → AuthX Communication

DjangoPlay communicates with AuthX over HTTP.

The internal AuthX API is protected using a service-to-service authentication header:

```http
X-Service-Token: <AUTHX_SERVICE_TOKEN>
```

The high-level communication path is:

```text
DjangoPlay
    │
    │ HTTPS / HTTP
    │ X-Service-Token
    ▼
AuthX Internal API
    │
    ▼
Identity Service
    │
    ▼
AuthX Database
```

In local development, AuthX may run on a local service endpoint such as:

```text
http://localhost:8100
```

The actual endpoint is environment-specific and is supplied through DjangoPlay configuration.

---

## 7. Service Authentication

DjangoPlay authenticates itself to AuthX as a trusted internal service.

```mermaid
sequenceDiagram

    participant DP as DjangoPlay
    participant AX as AuthX

    DP->>AX: HTTP request
    DP->>AX: X-Service-Token
    AX->>AX: Validate service token

    alt Token valid
        AX->>DP: Process request
    else Token invalid
        AX->>DP: Reject request
    end
```

The service token is a shared secret between the two services.

It must be treated as infrastructure credential material and must not be exposed to browsers or client-side code.

---

## 8. Identity Creation Flow

When DjangoPlay needs to create a new identity, AuthX creates the authoritative identity first.

```mermaid
sequenceDiagram

    participant U as User
    participant DP as DjangoPlay
    participant SYNC as Identity Sync Service
    participant CLIENT as AuthXClient
    participant AX as AuthX
    participant DB as AuthX PostgreSQL
    participant MIRROR as DjangoPlay UserIdentity

    U->>DP: Signup
    DP->>SYNC: Create identity
    SYNC->>CLIENT: create_identity()
    CLIENT->>AX: POST identity request
    AX->>DB: Create authoritative identity
    DB-->>AX: Identity created
    AX-->>CLIENT: Identity response
    CLIENT-->>SYNC: Identity data
    SYNC->>MIRROR: Synchronize local identity
    MIRROR-->>DP: Local identity available
```

### Design rule

The order is intentional:

```text
Create authoritative AuthX identity
             ↓
Receive identity information
             ↓
Synchronize DjangoPlay mirror
```

DjangoPlay should not create an independent authentication identity that competes with AuthX.

---

## 9. Identity Update Flow

Updates follow the same authority model.

```mermaid
sequenceDiagram

    participant DP as DjangoPlay
    participant SYNC as Identity Sync
    participant CLIENT as AuthXClient
    participant AX as AuthX
    participant DB as AuthX PostgreSQL
    participant MIRROR as UserIdentity

    DP->>SYNC: Update identity
    SYNC->>CLIENT: update_identity()
    CLIENT->>AX: PUT identity request
    AX->>DB: Update authoritative identity
    DB-->>AX: Updated identity
    AX-->>CLIENT: Identity response
    CLIENT-->>SYNC: Updated identity
    SYNC->>MIRROR: Synchronize local mirror
```

This keeps AuthX as the authoritative source while allowing DjangoPlay to maintain its local representation.

---

## 10. Identity Lookup

DjangoPlay can retrieve identity information from AuthX when required.

Typical operations include:

```text
Get identity by ID
Get identity by email
Create identity
Update identity
```

Conceptually:

```mermaid
flowchart LR

    DP["DjangoPlay"]
    CLIENT["AuthXClient"]

    GETID["Get by identity ID"]
    GETEMAIL["Get by email"]
    CREATE["Create identity"]
    UPDATE["Update identity"]

    AX["AuthX Identity API"]

    DP --> CLIENT

    CLIENT --> GETID
    CLIENT --> GETEMAIL
    CLIENT --> CREATE
    CLIENT --> UPDATE

    GETID --> AX
    GETEMAIL --> AX
    CREATE --> AX
    UPDATE --> AX

    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef operation fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class DP,CLIENT app
    class GETID,GETEMAIL,CREATE,UPDATE operation
    class AX authx
```

---

## 11. Local `UserIdentity` Mirror

DjangoPlay maintains a local identity representation because the Django application needs to associate identity with its own domain model.

The local representation can provide application access to information such as:

```text
authx_id
username
email
sso_provider
sso_id
is_active
is_verified
is_staff
is_superuser
```

The exact fields are determined by the current DjangoPlay implementation.

The architectural distinction is:

| Data | Authority |
|---|---|
| Authentication identity | AuthX |
| Password credentials | AuthX |
| SSO identity linkage | AuthX |
| Application profile data | DjangoPlay |
| Application relationships | DjangoPlay |
| Application permissions | DjangoPlay |
| Domain-specific data | DjangoPlay |

The mirror is therefore **not a second authentication authority**.

---

## 12. Authentication and Authorization Boundary

Authentication and authorization are separate concerns.

```mermaid
flowchart LR

    USER["User"]

    AUTH["Authentication"]
    AX["AuthX"]

    IDENTITY["Authenticated Identity"]

    POLICY["DjangoPlay Policy / Authorization"]
    ACCESS["Allow / Deny"]

    USER --> AUTH
    AUTH --> AX
    AX --> IDENTITY
    IDENTITY --> POLICY
    POLICY --> ACCESS

    classDef user fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef auth fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef policy fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef result fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class USER user
    class AUTH,AX,IDENTITY auth
    class POLICY policy
    class ACCESS result
```

### AuthX

Answers:

> **Who is this user?**

### DjangoPlay

Answers:

> **What is this user allowed to do in this application?**

This distinction is fundamental to the integration architecture.

---

## 13. Secrets and Configuration

DjangoPlay and AuthX maintain their own service configuration.

DjangoPlay contains the configuration required to communicate with AuthX, while AuthX maintains its own service-side credentials and database configuration.

Conceptually:

```text
DjangoPlay configuration
    │
    ├── AUTHX_BASE_URL
    ├── AUTHX_SERVICE_TOKEN
    └── AUTHX_TIMEOUT


AuthX configuration
    │
    ├── AUTHX_SERVICE_TOKEN
    ├── AUTHX database configuration
    └── AuthX cryptographic configuration
```

AuthX-specific secrets should remain under AuthX's own configuration boundary.

Secrets must never be committed to source control or exposed to client-side applications.

---

## 14. Environment Separation

The integration supports environment-specific AuthX configuration.

```mermaid
flowchart TD

    ENV["DjangoPlay Environment"]

    DEV["Development"]
    STAGING["Staging"]
    PROD["Production"]

    DEVAX["Development AuthX"]
    STAGEAX["Staging AuthX"]
    PRODAX["Production AuthX"]

    ENV --> DEV
    ENV --> STAGING
    ENV --> PROD

    DEV --> DEVAX
    STAGING --> STAGEAX
    PROD --> PRODAX

    classDef env fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91

    class ENV,DEV,STAGING,PROD env
    class DEVAX,STAGEAX,PRODAX authx
```

The AuthX base URL and service credentials are supplied through the configuration for the active environment.

This prevents development configuration from being coupled to production infrastructure.

---

## 15. Failure Boundary

Because AuthX is a separate service, DjangoPlay treats communication with AuthX as an external service boundary.

```mermaid
flowchart LR

    DP["DjangoPlay"]

    CLIENT["AuthXClient"]

    NETWORK["HTTP / Network"]

    AX["AuthX"]

    DB["AuthX PostgreSQL"]

    DP --> CLIENT
    CLIENT --> NETWORK
    NETWORK --> AX
    AX --> DB

    FAIL["Integration Failure"]

    NETWORK -.-> FAIL
    AX -.-> FAIL
    DB -.-> FAIL

    classDef app fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef transport fill:#f5f3ed,stroke:#777,stroke-width:1px,color:#444
    classDef authx fill:#eeeeff,stroke:#5a55c9,stroke-width:2px,color:#403b91
    classDef failure fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class DP,CLIENT app
    class NETWORK transport
    class AX,DB authx
    class FAIL failure
```

Failures can occur at several boundaries:

- Network connectivity
- AuthX availability
- Service authentication
- Request validation
- Identity operations
- AuthX database operations

The integration layer provides a controlled boundary for handling these failures rather than allowing AuthX-specific exceptions and HTTP behavior to spread throughout the application.

---

## 16. Integration Design Principles

The DjangoPlay ↔ AuthX integration follows these principles:

| Principle | Description |
|---|---|
| Identity Authority | AuthX owns authoritative identity information |
| Local Mirror | DjangoPlay maintains a local identity representation |
| Service Boundary | Communication occurs through `AuthXClient` |
| Service Authentication | Internal calls use `X-Service-Token` |
| Separation of Concerns | Authentication and application authorization remain separate |
| Application Ownership | DjangoPlay owns application/domain data |
| Credential Isolation | AuthX credentials remain within the AuthX boundary |
| Environment Isolation | AuthX configuration varies by environment |
| Centralized Integration | AuthX communication is not scattered across apps |
| Explicit Synchronization | Identity changes are synchronized into DjangoPlay |

---

## 17. Integration Summary

The overall relationship can be summarized as:

```text
                    USER
                     │
                     ▼
              DJANGOPLAY
                     │
          Authentication Flow
                     │
                     ▼
                AuthXClient
                     │
             HTTP + Service Token
                     │
                     ▼
                  AUTHX
                     │
              Identity Service
                     │
                     ▼
             AuthX PostgreSQL
```

Alongside the authoritative AuthX identity, DjangoPlay maintains:

```text
AuthX Identity
      │
      ▼
DjangoPlay UserIdentity
      │
      ├── Application relationships
      ├── Profiles
      ├── Permissions
      └── Domain data
```

The resulting architecture keeps **identity centralized in AuthX while application ownership remains within DjangoPlay**.

For detailed implementation documentation, refer to the DjangoPlay authentication architecture and the AuthX service documentation.