> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Authlete acts as the backend engine for OAuth 2.0 and OpenID Connect processing. It is not directly accessed by the end user or the client application. Instead, it is called by the service provider’s own systems, mainly the Authorization Server and API Server.

## Overall Architecture

```mermaid placement="top-right" theme={null}

%%{init: {
  'themeVariables': {
    'fontSize': '24px',
    'nodeTextMargin': 40
  },
  'flowchart': {
    'nodeSpacing': 40,
    'rankSpacing': 40,
    'padding': 5
  }
}}%%

  graph LR

  subgraph user[End User]
    direction TB
    ro[Resource<br/>Owner]
    ua[User<br/>Agent]
    ro --> ua
  end

  subgraph app[Client Application]
    direction TB
    client[OAuth Client /<br/>OIDC RP]
  end

  subgraph provider[Service Provider]
    direction TB

    subgraph auth[Authentication Server]
      direction TB
      user_authn[User<br/>Authentication]
      user_db[User<br/>Database]
      user_authn --> user_db
    end

    subgraph as[Authorization Server]
      direction TB
      oauth_ep[OAuth/OIDC<br/>Endpoints]
      authz_decision[Authorization<br/>Decision]
    end

    subgraph api[API Server]
      direction TB
      rs[Resource<br/>Server]
    end
  end

  subgraph authlete[Authlete]
    direction TB
    protocol_processing[Protocol<br/>Processing]
    token_management[Token<br/>Management]
    client_management[Client<br/>Management]
    service_management[Service<br/>Management]
  end

  %% User interaction with client
  ua --> client

  %% User authentication / consent
  ua -- Login / Consent --> user_authn

  %% Authorization request via User Agent
  ua -- Authorization Request --> oauth_ep

  %% Direct client-to-AS communication
  client -- Token<br/>Request --> oauth_ep

  %% Authorization server internal processing
  oauth_ep --> authz_decision
  oauth_ep --> authlete

  %% API access
  client -- API<br/>Request --> rs
  rs --> authlete

```

The diagram has four main areas:

| Area               | Role                                                                                                       |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| End User           | The actual user and their browser or user agent                                                            |
| Client Application | The OAuth Client / OIDC Relying Party, e.g., a web or mobile application                                   |
| Service Provider   | The system that manages the Authorization Server, Authentication Server, and API Server                    |
| Authlete           | Backend service for OAuth/OIDC protocol logic, token management, client management, and service management |

***

## What Authlete Is Responsible For

Inside Authlete, the diagram shows four main responsibilities.

### Protocol Processing

Authlete handles the OAuth 2.0 and OpenID Connect protocol logic. For example, it helps process authorization requests, token requests, introspection requests, revocation requests, and other OAuth/OIDC-related operations.

### Token Management

Authlete manages tokens such as:

* Authorization codes
* Access tokens
* Refresh tokens
* ID tokens, in OpenID Connect scenarios

The Authorization Server exposes the endpoint to the client, but Authlete can handle much of the token-related logic behind the scenes.

### Client Management

Authlete manages OAuth/OIDC client information, such as:

* Client IDs and credentials (e.g., client secrets, JWKs)
* Redirect URIs
* Allowed grant types
* Allowed scopes

### Service Management

Authlete also manages service-level settings, such as:

* Issuer information
* Supported OAuth/OIDC flows
* Supported scopes
* Signing algorithms
* Service configuration

## What the Service Provider Still Owns

Even when using Authlete, the Service Provider still runs several important components.

### Authorization Server

The Service Provider owns the OAuth/OIDC endpoints, such as:

* Authorization endpoint
* Token endpoint
* Revocation endpoint
* Introspection endpoint (for Resource Servers)
* UserInfo endpoint (for OpenID Connect Relying Parties)
* Well-known configuration endpoint

However, these endpoints call Authlete to perform the actual OAuth/OIDC processing.

### Authentication Server

The Service Provider owns user authentication.

That means the following remain outside Authlete:

* Login screens
* User authentication logic
* User database

Authlete does not directly authenticate the user. Instead, it works with the result of authentication performed by the Service Provider.

### API Server

The API Server contains the Resource Server.

When the Client Application sends an API request with an access token, the Resource Server may call Authlete to validate or introspect the token.

# Typical Request Flow

A typical flow from the diagram is:

1. The End User uses a User Agent, such as a browser.
2. The User Agent interacts with the Client Application.
3. The Client Application sends an authorization request to the Authorization Server via the User Agent.
4. **The Authorization Server calls Authlete to process the request.**
5. The user is redirected or guided to login and consent.
6. The Authentication Server verifies the user using the User Database.
7. The Authorization Server makes the authorization decision.
8. **The Authorization Server calls Authlete to create an authorization response that includes an authorization code.**
9. The Authorization Server sends the authorization response back to the Client Application via the User Agent.
10. The Client Application calls the Authorization Server to exchange the authorization code for an access token at the token endpoint.
11. **The Authorization Server calls Authlete to process the token request.**
12. The Authorization Server sends the token response back to the Client Application.
13. The Client Application uses the token to call the API Server.
14. **The Resource Server may call Authlete to validate the token.**
15. The API Server responds to the Client Application.

```mermaid placement="top-right" theme={null}
  sequenceDiagram

    box End User
      participant EndUser as End User
      participant UserAgent as User Agent
    end
    box Client Application
      participant ClientApp as Client<br />Application
    end
    box Service Provider
      participant AuthzServer as Authorization<br />Server
      participant UserAuthn as Authentication<br />Server
      participant APIServer as Resource<br />Server
    end
    box Authlete
      participant Authlete as Authlete
    end

    EndUser->>UserAgent: Use browser
    UserAgent->>ClientApp: Interact with app

    ClientApp-->>UserAgent: Authorization request
    UserAgent->>AuthzServer: Authorization request
    
    AuthzServer->>Authlete: Send authorization request content
    Authlete-->>AuthzServer: "ticket" and other data (e.g., client info, requested scopes, etc.)
    
    AuthzServer->>UserAuthn: Process user<br />authentication
    UserAuthn<<->>UserAgent: Verify user
    UserAuthn->>UserAuthn: Verify user credentials
    UserAuthn-->>AuthzServer: Authentication<br />result
    AuthzServer->>AuthzServer: Make authorization decision
    AuthzServer->>Authlete: Send "ticket" and other data (e.g., subject identifier, claims, etc.)
    Authlete-->>AuthzServer: Authorization response data
    AuthzServer-->>UserAgent: Send authorization response
    UserAgent->>ClientApp: Send authorization<br />response
    ClientApp->>AuthzServer: Token request
    AuthzServer->>Authlete: Send token request content
    Authlete-->>AuthzServer: Token response data
    AuthzServer-->>ClientApp: Send token response
    ClientApp->>APIServer: API request with token
    APIServer->>Authlete: Token introspection<br />(optional)
    Authlete-->>APIServer: Token introspection<br />result (optional)
    APIServer-->>ClientApp: API response
    ClientApp-->>UserAgent: Response
```