> ## 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.

> ## Agent Instructions
> ### Authlete versions
> Authlete 3.0 is the current version. Unless the user says they use another version, answer for Authlete 3.0 using the 3.x documentation.
> Documentation for Authlete 2.x (pages under `/v2/` and `/ja/v2/`) is for the legacy version. Refer to it only when the user is on Authlete 2.x.
>
> ### Authlete architecture
> Authlete is a backend engine for OAuth 2.0 and OpenID Connect processing. End users and client applications do not call it directly; the service provider's authorization server and API server call Authlete's APIs. Authlete handles protocol processing and token, client, and service management, while the service provider owns the OAuth/OIDC endpoints and user authentication.
> See [Architecture](https://developers.authlete.com/get-started/introduction-to-authlete/architecture.md).
>
> ### Concepts
> If the user is new to Authlete, read these pages first:
> - [Request and Response](https://developers.authlete.com/get-started/concepts/request-and-response.md): Core API requests pass the client's request parameters as-is, and responses return `resultCode`, `action`, and `responseContent`.
> - [Action Handling](https://developers.authlete.com/get-started/concepts/action-handling.md): Branch on `action`, never on `resultCode`, and map each action to the HTTP response your server returns.
> - [Two-Step API Calls](https://developers.authlete.com/get-started/concepts/two-step-api-calls.md): Actions such as `INTERACTION` are completed with a second call (`/auth/authorization/issue` or `/auth/authorization/fail`) linked by a `ticket`.
> - [Management API Overview](https://developers.authlete.com/get-started/concepts/overview.md): The Management API configures services, manages clients, and operates issued tokens, separately from the protocol flows handled by the Core API.
> - [API Authentication](https://developers.authlete.com/get-started/concepts/authentication.md): Authlete APIs use bearer tokens: a Service Access Token (one service) or an Organization Token (the whole organization).

# Subject

> The identifier of the end-user (subject) that your authorization server passes to Authlete.

## What the subject is

The **subject** is the identifier of the end-user (the resource owner) on whose behalf a code or token is issued. Your authorization server generates the subject and passes it to the Authlete API as the `subject` request parameter.

First, your authorization server passes the subject to Authlete after user authentication, and Authlete binds the subject it receives to the code and tokens it issues (Figure 1).

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant U as End-User
    participant AS as Authorization Server
    participant API as Authlete Core API

    AS <<->> U: User authentication
    AS ->> AS: Identify the end-user and determine the subject
    AS ->> API: Issue Authorization Response (ticket, subject)
    Note over API: Bind the subject to the code and tokens
    API -->> AS: action=LOCATION, responseContent
```

Figure 1: Binding the subject after user authentication

Next, when Authlete issues tokens in exchange for that code, it returns the subject as a value carried in the ID token and the JWT access token (Figure 2).

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant C as Client
    participant AS as Authorization Server
    participant API as Authlete Core API

    C ->> AS: Token request
    AS ->> API: Process Token Request (contents of the token request)
    Note over API: (OIDC)<br/>Return the subject as a value in the ID token
    Note over API: (JWT access token)<br/>Return the subject as a value in the access token
    API -->> AS: action=OK, responseContent
    AS -->> C: Token response
```

Figure 2: Returning the subject inside tokens

When a resource server introspects an access token, Authlete also returns the subject bound to that access token (Figure 3).

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant C as Client
    participant RS as Resource Server
    participant API as Authlete Core API

    C ->> RS: API request
    RS ->> API: Process Introspection Request (access token value)
    Note over API: Return the subject bound to the access token
    API -->> RS: action=OK, subject
    RS -->> C: API response
```

Figure 3: Returning the subject as the result of token introspection

Authlete also uses the bound subject to filter the list of tokens and to control the tokens it issues.

## Relationship to the OAuth/OIDC specifications

Authlete's subject corresponds to `sub` in the following elements of the OAuth/OIDC specifications:

| Element that carries `sub` | Requirements for `sub` | Specification |
| - | - | - |
| ID token | Required. *A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client*. It must not exceed 255 ASCII characters and is case sensitive. | [OpenID Connect Core 1.0, Section 2](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) |
| UserInfo response | Always returned. The client must verify that it exactly matches the `sub` of the ID token; otherwise the client must not use the UserInfo values. | [OpenID Connect Core 1.0, Section 5.3.2](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse) |
| Token introspection response | Optional. Usually a machine-readable identifier of the resource owner who authorized the token. | [RFC 7662, Section 2.2](https://www.rfc-editor.org/rfc/rfc7662#section-2.2) |
| JWT access token | Optional. The principal that the claims in the JWT are statements about, locally unique within the issuer or globally unique. | [RFC 7519, Section 4.1.2](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2) |

[OpenID Connect Core 1.0, Section 5.7](https://openid.net/specs/openid-connect-core-1_0.html#ClaimStability) names `sub` and `iss` together as the only claims a client can rely on as a stable identifier for the end-user, and says that `email`, `phone_number` and `preferred_username` must not be used as one. Because `sub` is never reassigned, a client can store it against the user account it manages and recognize the same user on later logins.

Your authorization server generates an end-user identifier with these properties and passes it to Authlete as the `subject` request parameter. Authlete emits the value it receives as the `sub` of the elements above.

## Division of responsibilities

The subject is divided between your authorization server and Authlete as follows.

### Authorization server

* **Establishes who the end-user is.** Authlete is not involved in this step. The authorization server may authenticate the user itself (a login form, passkeys), rely on an existing session, or accept an authentication result from an external identity provider through federation.
* **Determines the subject that represents that user.** Use a value that satisfies the properties above: something that never changes and is never reused, such as an internal account ID. An e-mail address or a display name does not qualify, because it can change. When authentication is delegated to an external identity provider, map its result to your own account identifier rather than forwarding the provider's identifier as it is: it is unique and stable within that provider, not necessarily within your issuer.
* **Passes the subject to an issuing API (e.g. [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md)).** Any other information about the user that an ID token or UserInfo response should carry is passed as claims. Authlete has no user store and derives nothing from the subject.

### Authlete

* **Checks the format of the subject.** [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md) in Authlete 3.0 checks the following requirements (the other issuing APIs apply the same length limit):

  | Requirement | Detail |
  | - | - |
  | Non-empty | The API fails with `server_error` when the `subject` parameter is missing or empty, because that is a defect in the authorization server, not in the client's request. |
  | At most 255 characters | Longer values fail in the same way. This is the limit OpenID Connect Core places on `sub`. |
  | Printable ASCII only | Other characters fail in the same way. |
* **Binds the subject to the authorization code and tokens it issues.**
* **Returns the subject in tokens and API responses.** Authlete emits it as the `sub` claim of ID tokens, the `sub` of UserInfo responses, the `sub` of JWT access tokens, the `sub` member of standard introspection responses, and the `subject` field of its own introspection API (see the following sections).

## How the subject flows

### Sent by the authorization server

Once it has identified the end-user, your authorization server sends a request containing the subject to an issuing (flow-completing) API:

| API | Flow |
| - | - |
| [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md) | Authorization code, implicit and hybrid flows. Called after authentication and consent. See [Two-Step API Calls](https://developers.authlete.com/get-started/concepts/two-step-api-calls.md). |
| [Issue Token Response](https://developers.authlete.com/api-reference/token-endpoint/issue-token-response.md) | Resource Owner Password Credentials. Called after your authorization server has verified the credentials that [Process Token Request](https://developers.authlete.com/api-reference/token-endpoint/process-token-request.md) handed back with `action=PASSWORD`. |
| [Complete Device Authorization](https://developers.authlete.com/api-reference/device-flow/complete-device-authorization.md) | Device flow. Passes the end-user who approved the authorization request. |
| [Complete Backchannel Authentication](https://developers.authlete.com/api-reference/ciba/complete-backchannel-authentication.md) | CIBA. Passes the user who authenticated on the authentication device. |
| [Create Access Token](https://developers.authlete.com/api-reference/token-operations/create-access-token.md) | Creating an access token directly, outside a protocol flow. Not required for the `CLIENT_CREDENTIALS` grant type, where no end-user is involved. |

### Returned by Authlete

The subject passed to Authlete appears in the following tokens and responses:

* **Access tokens** are bound to the subject, which comes back as the result of token introspection and as a value carried in JWT access tokens.
  * Introspection: [Process Introspection Request](https://developers.authlete.com/api-reference/introspection-endpoint/process-introspection-request.md) returns it as `subject`, and [Process OAuth 2.0 Introspection Request](https://developers.authlete.com/api-reference/introspection-endpoint/process-oauth-20-introspection-request.md) returns it as the RFC 7662 `sub` member, so a resource server can tell whose token it received.
  * [JWT access tokens](https://developers.authlete.com/configuration-reference/tokens-and-claims/using-jwt-based-access-tokens.md): carry it as `sub`. Authlete's JWT access tokens use the claim names of RFC 9068 but do not conform to that profile; see the "JWT Access Token" section of [JWTs in OAuth and OpenID Connect](https://darutk.medium.com/jwts-in-oauth-oidc-19c8029551d5#c63c).
  * A token issued by the client credentials grant has no subject: standard introspection omits `sub`, and a JWT access token carries `"sub": null`.
* **ID tokens** carry the subject as the `sub` claim.
  * [Issue Authorization Response](https://developers.authlete.com/api-reference/authorization-endpoint/issue-authorization-response.md), [Complete Device Authorization](https://developers.authlete.com/api-reference/device-flow/complete-device-authorization.md) and [Complete Backchannel Authentication](https://developers.authlete.com/api-reference/ciba/complete-backchannel-authentication.md) also accept a `sub` request parameter, which sets a value other than the subject (the access token stays bound to the subject). This keeps the actual subject hidden from client applications. See [Adding Claims to ID Token](https://developers.authlete.com/configuration-reference/tokens-and-claims/adding-claims-to-an-id-token.md).
* **UserInfo responses**, like ID tokens, carry the subject as the `sub` claim.
  * Likewise, the `sub` parameter of [Issue UserInfo Response](https://developers.authlete.com/api-reference/userinfo-endpoint/issue-userinfo-response.md) sets a value other than the subject.

> [!WARNING]
>
> The `sub` parameter changes only the ID token and the UserInfo response. The access token stays bound to the subject, so the identifier a resource server sees can differ from the one the client sees. When you pass `sub` to an issuing API, pass the same value to [Issue UserInfo Response](https://developers.authlete.com/api-reference/userinfo-endpoint/issue-userinfo-response.md), so that the UserInfo `sub` matches the ID token as OpenID Connect Core 1.0, Section 5.3.2 requires.

## Working with tokens by subject

Once a subject is bound to a token, the following APIs and settings use the subject to work with that end-user's tokens:

* [Process Introspection Request](https://developers.authlete.com/api-reference/introspection-endpoint/process-introspection-request.md) takes `subject` as an optional parameter. When it is given and does not match the subject bound to the access token, Authlete returns `action=FORBIDDEN`, so a resource server can require that a token belong to a specific user.
* [List Issued Tokens](https://developers.authlete.com/api-reference/token-operations/list-issued-tokens.md) filters issued tokens by subject.
* [Single Access Token Per Subject](https://developers.authlete.com/configuration-reference/tokens-and-claims/enabling-single-access-token-per-subject.md) keeps only the newest access token valid for each subject.

All of these compare the subject exactly, so pass the same identifier for the same end-user every time.

## Handling pairwise subject identifiers

### What pairwise subject identifiers are

OpenID Connect Core defines two [subject identifier types](https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes) for the `sub` claim:

| Type | `sub` value | Purpose |
| - | - | - |
| `public` | The same for every client. | The default. |
| `pairwise` | Different for each client, or for each group of clients that share a **sector** (identified by a `sector_identifier_uri` or a common redirect URI host). | Clients cannot correlate a user by comparing the identifiers they received. |

The specification does not define how a pairwise subject identifier is derived. It does require that the provider calculate a unique `sub` for each sector identifier and that the value not be reversible by any party other than the provider ([Section 8.1](https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg)).

### What Authlete does

Given an identifier that is unique within your authorization server, Authlete derives the per-client `sub` value as follows.

> [!NOTE]
>
> This applies to a client whose subject identifier type is `pairwise`, when no `sub` parameter is given.

1. **Determine the client's sector identifier.** It is the host of the client's `sector_identifier_uri` if one is registered, otherwise the host shared by all of its redirect URIs. If the client has neither a `sector_identifier_uri` nor a single redirect URI host, no sector identifier can be derived, and Authlete uses the subject as `sub` unchanged.
2. **Determine the `sub` value.** Authlete computes a hash from the sector identifier, the service, the subject and other inputs, and uses it as `sub`, encoded in URL-safe Base64 without padding (a 43-character string). The same user therefore always gets the same `sub` at the same client (and at other clients in the same sector), while different clients and different services get different values.

The conversion applies wherever Authlete emits an identifier for the user to the client: the `sub` of ID tokens from every flow (including CIBA, the device flow, ID token reissuance and Native SSO), of UserInfo responses and of logout tokens. The access token, on the other hand, stays bound to the subject your authorization server passed, so introspection's `subject` and a JWT access token's `sub` return that value.

> [!NOTE]
>
> Pairwise subject identifiers are supported by Authlete 2.2 and later.

### Configuration

The subject identifier type is set per client: **Subject Type** (`subjectType`, `PUBLIC` or `PAIRWISE`) in the client settings. For a pairwise client whose redirect URIs span more than one host, also register **Sector Identifier URI** (`sectorIdentifierUri`), or Authlete cannot derive a sector identifier and falls back to the public behavior.

## See Also

* [Request and Response](https://developers.authlete.com/get-started/concepts/request-and-response.md)
* [Two-Step API Calls](https://developers.authlete.com/get-started/concepts/two-step-api-calls.md)
* [Adding Claims to ID Token](https://developers.authlete.com/configuration-reference/tokens-and-claims/adding-claims-to-an-id-token.md)
* [Enabling Single Access Token](https://developers.authlete.com/configuration-reference/tokens-and-claims/enabling-single-access-token-per-subject.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.