> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/ess/services/service-platform-management/access-tokens.md).

# Access Tokens

{% hint style="success" %}
Added in version 3.0.0
{% endhint %}

The Platform Management service issues the ESS Access Tokens that clients use to call ESS services. It hosts a single OAuth 2.0 token endpoint that supports two ways of obtaining a token:

| Grant                                                         | Use it for                                                                                                                       | How the client authenticates                                                                 |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Token Exchange](#token-exchange)                             | Users who sign in with your Identity Provider (IdP), and applications acting on their behalf                                     | The client exchanges a token from a trusted external IdP                                     |
| [Client Credentials with CIMD](#client-credentials-with-cimd) | Applications that act on their own behalf, such as AI agents, integration scripts, and partner services. Added in version 3.5.0. | The client signs an assertion with a key published in its Client ID Metadata Document (CIMD) |

Both grants issue [RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068)-compliant JWT access tokens, signed by the Platform Management service.

{% hint style="info" %}
If your deployment requires Solid-OIDC protocol compliance for interoperability with other Solid servers, ESS also supports authentication via the [Solid OIDC Broker](https://docs.inrupt.com/ess/services/advanced-configuration/service-oidc.md). This is an advanced configuration not needed for standard enterprise deployments.
{% endhint %}

## Benefits

* **Simplified Integration**: Developers integrate against existing enterprise identity systems rather than building parallel authentication infrastructure
* **Multiple IdP Support**: A single IdP is recommended, but multiple IdPs can be configured if needed; new IdPs can be added or modified post-deployment without system redeployment
* **AI Agent Support**: AI agents and other machine clients authenticate with a Client ID Metadata Document, as recommended by the [Model Context Protocol](https://modelcontextprotocol.io/), without an account at your IdP
* **Enhanced Security**: Short-lived access tokens, with a default time-to-live of 5 minutes

## Base URL

The token endpoint runs on the Platform Management service:

```none
https://platform.{ESS Domain}
```

## Authorization Server Metadata

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

The Platform Management service publishes [OAuth 2.0 Authorization Server Metadata (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414). Clients, including MCP clients, can use it to discover the token endpoint and the grant types, authentication methods, and scopes that ESS supports.

| Field    | Value                                                                      |
| -------- | -------------------------------------------------------------------------- |
| Endpoint | **`https://platform.{ESS Domain}/.well-known/oauth-authorization-server`** |
| Method   | **`GET`**                                                                  |

### Example Response

```json
{
  "issuer": "https://platform.example.com",
  "token_endpoint": "https://platform.example.com/access/token",
  "jwks_uri": "https://platform.example.com/jwks",
  "response_types_supported": [],
  "grant_types_supported": [
    "urn:ietf:params:oauth:grant-type:token-exchange",
    "client_credentials"
  ],
  "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
  "token_endpoint_auth_signing_alg_values_supported": ["ES256", "PS256", "RS256"],
  "scopes_supported": [
    "mcp:access-request:write",
    "mcp:access-request:read",
    "mcp:access-grant:read",
    "mcp:storage:read"
  ],
  "client_id_metadata_document_supported": true
}
```

| Field                                                  | Description                                                                                                                  |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **`issuer`**                                           | The issuer of ESS Access Tokens                                                                                              |
| **`token_endpoint`**                                   | The [token endpoint](#token-endpoint) URL                                                                                    |
| **`jwks_uri`**                                         | The [JWKS endpoint](#jwks-endpoint) URL                                                                                      |
| **`response_types_supported`**                         | Always empty. ESS has no authorization endpoint: tokens are issued only by the token endpoint.                               |
| **`grant_types_supported`**                            | [Token exchange](#token-exchange), and [`client_credentials`](#client-credentials-with-cimd)                                 |
| **`token_endpoint_auth_methods_supported`**            | **`none`** for token exchange, where the subject token is the credential, and **`private_key_jwt`** for `client_credentials` |
| **`token_endpoint_auth_signing_alg_values_supported`** | The signing algorithms accepted for `private_key_jwt` client assertions                                                      |
| **`scopes_supported`**                                 | All scopes ESS can issue, across both grant types                                                                            |
| **`client_id_metadata_document_supported`**            | **`true`**: ESS supports [Client ID Metadata Document](#client-credentials-with-cimd) clients                                |

## Token Endpoint

Both grants use the same endpoint:

| Field        | Value                                            |
| ------------ | ------------------------------------------------ |
| Endpoint     | **`https://platform.{ESS Domain}/access/token`** |
| Method       | **`POST`**                                       |
| Content-Type | **`application/x-www-form-urlencoded`**          |

The **`grant_type`** parameter selects the grant. Both grants accept the following optional parameters:

| Parameter      | Required | Description                                                                                                                                                                                                                                                                                                          |
| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`resource`** | No       | The URL of the ESS service the token is for, as an [RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707) resource indicator, for example `https://storage.example.com`. May be repeated. Each value must be one of the audiences configured for the grant. If not provided, the token is issued for all of them. |
| **`scope`**    | No       | Space-delimited list of requested scopes. Each value must be one of the scopes configured for the grant. For what is issued when **`scope`** is not provided, see each grant's request parameters.                                                                                                                   |

The audiences and scopes configured for each grant are described in [Configuration](#configuration).

## Token Exchange

The token exchange grant enables ESS to trust external Identity Providers directly, mapping their identifiers to internal ESS identifiers. Clients authenticate with their existing OIDC-compliant IdP (for example, Okta, Azure AD, or Ping Identity) and exchange the resulting token for an ESS Access Token, with no need for the Solid OIDC Broker as an intermediary.

The grant implements [RFC 8693 (OAuth 2.0 Token Exchange)](https://datatracker.ietf.org/doc/html/rfc8693).

### Token Exchange Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant I as Identity Provider
    participant P as Platform Management
    participant S as ESS Service

    C->>I: 1. Authenticate
    I-->>C: 2. ID token
    C->>P: 3. Token request with the ID token
    P-->>C: 4. ESS Access Token
    C->>S: 5. Request with the ESS Access Token
```

1. Client authenticates with the external Identity Provider
2. IdP returns an ID token
3. Client sends the ID token to the Platform Management service's token endpoint
4. The endpoint validates the ID token, maps the identity to ESS internal identifiers, and returns an ESS Access Token
5. Client uses the ESS Access Token to interact with ESS services

The external identity is mapped to an ESS account using the account's [identity mappings](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md#set-identity-mappings).

### Token Exchange Request Parameters

| Parameter                | Required | Description                                                                                                                                                                                   |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`grant_type`**         | Yes      | Must be **`urn:ietf:params:oauth:grant-type:token-exchange`**                                                                                                                                 |
| **`subject_token`**      | Yes      | The token from the external Identity Provider                                                                                                                                                 |
| **`subject_token_type`** | Yes      | The type of the subject token. One of **`urn:ietf:params:oauth:token-type:id_token`**, **`urn:ietf:params:oauth:token-type:access_token`**, or **`urn:ietf:params:oauth:token-type:jwt`**.    |
| **`resource`**           | No       | See [Token Endpoint](#token-endpoint). Must be one of [**`INRUPT_PLATFORM_TOKEN_EXCHANGE_AUDIENCES`**](#inrupt_platform_token_exchange_audiences).                                            |
| **`scope`**              | No       | See [Token Endpoint](#token-endpoint). Must be one of [**`INRUPT_PLATFORM_TOKEN_EXCHANGE_SCOPE`**](#inrupt_platform_token_exchange_scope). If not provided, all configured scopes are issued. |
| **`audience`**           | No       | **Deprecated:** use **`resource`** instead. Target audience for the issued token. Ignored if **`resource`** is provided.                                                                      |

### Token Exchange Example

```http
POST /access/token HTTP/1.1
Host: platform.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<idp-token>
&subject_token_type=urn:ietf:params:oauth:token-type:id_token
&resource=https%3A%2F%2Fstorage.example.com
```

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 300
}
```

## Client Credentials with CIMD

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

Applications that act on their own behalf, such as AI agents, integration scripts, and partner services, can obtain ESS Access Tokens with the OAuth 2.0 **`client_credentials`** grant. They identify themselves using a [Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD), and do not need an account at your Identity Provider.

This is the authentication flow recommended by the [Model Context Protocol](https://modelcontextprotocol.io/) for machine clients, and it is how an AI agent obtains a token for the [MCP Service](https://docs.inrupt.com/ess/services/service-mcp.md).

A CIMD client is identified by an HTTPS URL that it controls. The URL is the client's **client ID**, and it resolves to a JSON document that publishes the client's public keys. To obtain a token, the client signs a short-lived JWT with its private key and presents it to the token endpoint. ESS fetches the client's document, verifies the signature, and issues an ESS Access Token for the agent account that the client is bound to.

ESS does not keep a registry of CIMD clients. Instead, two operator-controlled steps admit a client:

1. **The client's host is on the allow list.** ESS only fetches documents from hosts that an operator has approved. A client ID on any other host is rejected without being fetched. See [Manage the CIMD Client Domain Allow List](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/manage-cimd-client-domains.md).
2. **The client ID is bound to an agent account.** An operator provisions an agent account and binds the client ID to it using the [Platform Management API](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md#set-identity-mappings). Every token issued to the client identifies that agent.

Because each client acts as its own ESS agent, it accesses other users' data in the same way as any other agent: by requesting access and being granted it with an [Access Grant](https://docs.inrupt.com/ess/services/service-access-grant.md).

{% hint style="info" %}
**Security**

ESS authenticates a CIMD client by verifying an assertion signed with the client's key, but does not review what the client's software does. A client can only do what its agent account can: use the scopes in its token, and access data that users have shared with it through Access Grants. Operators control which clients are admitted with the [domain allow list](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/manage-cimd-client-domains.md) and the [agent binding](#step-3-bind-the-client-id-to-an-agent-account).
{% endhint %}

### Client Credentials Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant P as Platform Management
    participant H as Client's CIMD host
    participant S as ESS Service

    C->>P: 1. Get authorization server metadata
    C->>P: 2. Token request with a signed client assertion
    P->>H: 3. Fetch the CIMD document
    H-->>P: CIMD document
    P-->>C: 4. ESS Access Token
    C->>S: 5. Request with the ESS Access Token
```

1. The client discovers the token endpoint from the [authorization server metadata](#authorization-server-metadata).
2. The client sends a token request containing a signed client assertion.
3. ESS checks that the client ID's domain is allowed, then fetches the client's CIMD document (or uses a cached copy) and verifies the assertion's signature against the keys in it.
4. ESS finds the agent account bound to the client ID, confirms the account is active, and returns an ESS Access Token.
5. The client uses the ESS Access Token to call ESS services, such as the MCP Service.

Setting up a CIMD client takes five steps. An ESS operator does steps 2 and 3; the client's developer does the rest.

### Step 1: Publish the Client ID Metadata Document

Host a JSON document at the URL you will use as your client ID. The document must be served over HTTPS, and must not redirect.

```json
{
  "client_id": "https://agent.example.com/client.json",
  "client_name": "Example Agent",
  "token_endpoint_auth_method": "private_key_jwt",
  "grant_types": ["client_credentials"],
  "scope": "mcp:access-request:write mcp:access-request:read mcp:access-grant:read mcp:storage:read",
  "jwks": {
    "keys": [
      {
        "kty": "EC",
        "crv": "P-256",
        "kid": "agent-key-1",
        "use": "sig",
        "alg": "ES256",
        "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
        "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
      }
    ]
  }
}
```

| Field           | Required                    | Description                                                                                                                           |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **`client_id`** | Yes                         | Must exactly match the URL the document is served from.                                                                               |
| **`jwks`**      | One of `jwks` or `jwks_uri` | The client's public signing keys, as a JSON Web Key Set. Only asymmetric signing keys are used.                                       |
| **`jwks_uri`**  | One of `jwks` or `jwks_uri` | URL of a JSON Web Key Set containing the client's public signing keys. Must be on an allowed domain.                                  |
| **`scope`**     | No                          | Space-delimited list of the most scopes the client will request. If present, ESS rejects token requests for scopes outside this list. |

Other fields, such as **`client_name`**, are permitted and ignored.

The document must not exceed 5 KB. ESS caches the document according to its `Cache-Control` or `Expires` headers (one hour if neither is present, and at most 24 hours). To rotate keys, add the new key to the document before signing with it: if an assertion's `kid` is not in the cached document, ESS fetches the document again.

#### Client ID Format

The client ID must be an HTTPS URL in normalized form:

* The scheme and host must be lowercase, and the scheme must be **`https`**.
* The URL must include a path (for example, `/client.json`).
* The URL must not contain a query string, fragment, user information, percent-encoding, `.` or `..` path segments, or the default port `:443`.
* The host must not end with a trailing dot.

### Step 2: Allow the Client's Domain

An operator adds the host of the client ID (and of the `jwks_uri`, if used) to [**`INRUPT_PLATFORM_OAUTH_CLIENT_DOMAIN_ALLOW_LIST`**](#inrupt_platform_oauth_client_domain_allow_list). The allow list is empty by default, so no CIMD client can authenticate until an operator configures it.

For the matching rules, an example, and recommendations on approving changes, see [Manage the CIMD Client Domain Allow List](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/manage-cimd-client-domains.md).

### Step 3: Bind the Client ID to an Agent Account

An operator provisions an agent account for the client and binds the client ID to it, using the [Platform Management API](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md):

1. Create the account with [`POST /admin/provision`](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md#create-provisioning-account).
2. Bind the client ID with [`PUT /admin/provision/{accountId}/identity`](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md#set-identity-mappings), using a mapping of type **`cimd`** whose `issuer` and `subject` are both the client ID.
3. Activate the account with [`PUT /admin/provision/{accountId}/activate`](https://docs.inrupt.com/ess/services/service-platform-management/platform-management-api.md#activate-provisioning-account).

Identity mappings can only be set while the account is in the **setup** state. A client ID can be bound to only one account. The client can obtain tokens only once the account is active.

{% hint style="warning" %}
After the account is activated, its binding cannot be changed or removed, and the account cannot be deactivated. To revoke a client, either remove its host from the [domain allow list](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/manage-cimd-client-domains.md#remove-a-host), which revokes every client on that host, or purge its agent account with the [Purger Service](https://docs.inrupt.com/ess/services/service-platform-management/purger-service.md), which deletes the account and its data.
{% endhint %}

### Step 4: Create the Client Assertion

The client assertion is a JWT, signed with one of the client's private keys, with the following claims:

| Claim     | Required | Description                                                                                                                                                        |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`iss`** | Yes      | The client ID.                                                                                                                                                     |
| **`sub`** | Yes      | The client ID. Must equal **`iss`**.                                                                                                                               |
| **`aud`** | Yes      | The ESS token issuer: the **`issuer`** value from the [authorization server metadata](#authorization-server-metadata), for example `https://platform.example.com`. |
| **`exp`** | Yes      | Expiration time. Must be no more than 5 minutes in the future.                                                                                                     |
| **`jti`** | Yes      | A unique identifier. Each assertion can be used only once.                                                                                                         |
| **`iat`** | No       | Issued-at time.                                                                                                                                                    |

The JWT header must include the **`kid`** of the signing key. The signing algorithm must be one of those listed in the metadata's **`token_endpoint_auth_signing_alg_values_supported`** (by default, **`ES256`**, **`PS256`**, and **`RS256`**).

### Step 5: Request an ESS Access Token

Send the client assertion to the [token endpoint](#token-endpoint) with the following parameters:

| Parameter                   | Required | Description                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`grant_type`**            | Yes      | Must be **`client_credentials`**.                                                                                                                                                                                                                                                                                                             |
| **`client_id`**             | Yes      | The client ID.                                                                                                                                                                                                                                                                                                                                |
| **`client_assertion_type`** | Yes      | Must be **`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`**.                                                                                                                                                                                                                                                                         |
| **`client_assertion`**      | Yes      | The signed client assertion.                                                                                                                                                                                                                                                                                                                  |
| **`resource`**              | No       | See [Token Endpoint](#token-endpoint). Must be one of [**`INRUPT_PLATFORM_OAUTH_CLIENT_AUDIENCES`**](#inrupt_platform_oauth_client_audiences), for example `https://mcp.example.com`.                                                                                                                                                         |
| **`scope`**                 | No       | See [Token Endpoint](#token-endpoint). Must be one of [**`INRUPT_PLATFORM_OAUTH_CLIENT_SCOPE`**](#inrupt_platform_oauth_client_scope) and, if the client's document declares a **`scope`**, within that list too. If not provided, [**`INRUPT_PLATFORM_OAUTH_CLIENT_DEFAULT_SCOPE`**](#inrupt_platform_oauth_client_default_scope) is issued. |

For example:

```http
POST /access/token HTTP/1.1
Host: platform.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=https%3A%2F%2Fagent.example.com%2Fclient.json
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6ImFnZW50LWtleS0xIn0...
&resource=https%3A%2F%2Fmcp.example.com
&scope=mcp%3Aaccess-request%3Awrite%20mcp%3Astorage%3Aread
```

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 300
}
```

### Scopes

The following scopes can be issued to CIMD clients. They control which [MCP Service](https://docs.inrupt.com/ess/services/service-mcp.md) tools the client can use.

| Scope                          | Description                         |
| ------------------------------ | ----------------------------------- |
| **`mcp:access-request:write`** | Create Access Requests              |
| **`mcp:access-request:read`**  | Check the status of Access Requests |
| **`mcp:access-grant:read`**    | Check for matching Access Grants    |
| **`mcp:storage:read`**         | Read resources                      |

Request only the scopes the client needs. For example, a client that only creates Access Requests and tracks their status needs **`mcp:access-request:write`** and **`mcp:access-request:read`**, and not **`mcp:storage:read`**. A request for a scope that is not permitted fails with **`invalid_scope`**: ESS does not reduce the request to the permitted scopes.

Scopes are enforced by the MCP Service. Other ESS services do not check the **`scope`** claim.

## ESS Access Token

The ESS Access Token is a JWT ([RFC 9068](https://datatracker.ietf.org/doc/html/rfc9068)) containing:

| Claim           | Description                                                                                                                                                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`iss`**       | The Platform Management service URL                                                                                                                                                                                                                                                                  |
| **`sub`**       | The ESS agent identifier (mapped from the external identity)                                                                                                                                                                                                                                         |
| **`aud`**       | The requested resource(s), or all audiences configured for the grant if none was requested                                                                                                                                                                                                           |
| **`client_id`** | The ESS client identifier: mapped from the external `azp` or `client_id` claim (token exchange), or derived from the client ID (client credentials). The same input always produces the same value.                                                                                                  |
| **`jti`**       | Unique token identifier                                                                                                                                                                                                                                                                              |
| **`exp`**       | Expiration time                                                                                                                                                                                                                                                                                      |
| **`iat`**       | Issued-at time                                                                                                                                                                                                                                                                                       |
| **`scope`**     | The requested scopes. If the request does not include **`scope`**: for client credentials, the [default scope](#inrupt_platform_oauth_client_default_scope); for token exchange, all the [configured scopes](#inrupt_platform_token_exchange_scope), or no **`scope`** claim if none are configured. |

## Error Responses

Error responses use the [OAuth 2.0 error format (RFC 6749)](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2):

```json
{
  "error": "<error_code>",
  "error_description": "<human-readable description>"
}
```

| Status    | Error Code                   | Condition                                                                                          |
| --------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| **`400`** | **`invalid_request`**        | A required parameter is missing, or a parameter value is not supported                             |
| **`400`** | **`unsupported_grant_type`** | The **`grant_type`** parameter is not a supported grant type                                       |
| **`400`** | **`invalid_target`**         | A requested **`resource`** is not a configured audience                                            |
| **`400`** | **`invalid_scope`**          | A requested scope is not configured, or is outside the scopes declared in a CIMD client's document |
| **`401`** | **`invalid_token`**          | Token exchange: the subject token is invalid, expired, or from an untrusted IdP                    |
| **`401`** | **`invalid_client`**         | Client credentials: client authentication failed                                                   |
| **`500`** | **`server_error`**           | An unexpected internal error occurred                                                              |

## JWKS Endpoint

The Platform Management service exposes a JSON Web Key Set (JWKS) endpoint that returns the public key used to verify ESS Access Tokens.

| Field    | Value                                    |
| -------- | ---------------------------------------- |
| Endpoint | **`https://platform.{ESS Domain}/jwks`** |
| Method   | **`GET`**                                |

ESS services and clients can use this endpoint to obtain the public key for verifying the signature of ESS Access Tokens.

## Security

### Short-Lived Tokens

ESS Access Tokens have a default time-to-live (TTL) of 5 minutes (300 seconds). This limits the window of exposure if a token is compromised.

### Token Refresh

The token endpoint does not issue refresh tokens. When an ESS Access Token expires, clients must obtain a new one. Use the `expires_in` value from the token response to know when the token will expire.

For token exchange:

1. **Obtain a new IdP token**: Re-authenticate with your Identity Provider. If your IdP issued a refresh token, you can use it to obtain a new ID token without requiring user interaction.
2. **Exchange again**: Send the new IdP token to the token endpoint to obtain a fresh ESS Access Token.

For client credentials, send a new token request with a new client assertion.

### Audit Trail

Binding a client ID to an account generates an **`account-updated`** event that includes the identity mapping.

## Configuration

As part of the [installation process](https://docs.inrupt.com/ess/installation.md), Inrupt provides base Kustomize manifests that require deployment-specific configuration inputs.

### Shared Configuration

These settings apply to both grants.

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_ISSUER**

The issuer URL for ESS Access Tokens. Used as the **`iss`** claim in issued tokens. Typically set to the Platform Management service URL.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_ISSUER=https://platform.{ESS Domain}
```

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_SIGNING\_KEY\_LOCATION**

Path to the private key in JWK format used for signing ESS Access Tokens. The key must be an EC P-256 key (ES256 algorithm).

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_SIGNING_KEY_LOCATION=/opt/platform/platform-signing-key.json
```

{% hint style="warning" %}
**Warning**

The signing key is used to sign ESS Access Tokens. Safeguard your signing key and store it securely. Do not commit signing keys to version control.
{% endhint %}

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_TTL**

Default: **`300`** (5 minutes)

Time-to-live in seconds for issued ESS Access Tokens.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_TTL=300
```

### Token Exchange Configuration

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_AUDIENCES**

Required. A comma-separated list of ESS service URLs that can accept tokens issued by token exchange. A token exchange request can only request a **`resource`** from this list. Used as the **`aud`** claim when no **`resource`** is requested.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_AUDIENCES=https://storage.{ESS Domain},https://provision.{ESS Domain},https://vc.{ESS Domain},https://notification.{ESS Domain},https://mcp.{ESS Domain},https://authorization.{ESS Domain},https://purger.{ESS Domain}
```

If you deploy the [Solid interoperability services](https://docs.inrupt.com/ess/services/advanced-configuration.md), add the WebID Service to the list:

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_AUDIENCES=...,https://purger.{ESS Domain},https://id.{ESS Domain}
```

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_SCOPE**

Optional. A comma-separated list of the scopes that can be issued by token exchange. A request can only request a **`scope`** from this list, and a request that does not include **`scope`** is issued all of them. If not set, the scope claim is omitted and any request that includes **`scope`** is rejected.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_SCOPE=mcp:access-request:write,mcp:access-request:read,mcp:access-grant:read,mcp:storage:read
```

{% hint style="warning" %}
Tokens without scopes cannot call any [MCP Service](https://docs.inrupt.com/ess/services/service-mcp.md) tool. If applications use token exchange to obtain tokens for the MCP Service, set this to the `mcp:*` scopes they need.
{% endhint %}

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_SCOPES\_SUPPORTED**

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

Optional. A comma-separated list of scopes to advertise in the **`scopes_supported`** field of the [authorization server metadata](#authorization-server-metadata), in addition to the scopes available to [CIMD clients](#inrupt_platform_oauth_client_scope). Does not change which scopes can be issued.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_SCOPES_SUPPORTED=mcp:access-request:write,mcp:access-request:read,mcp:access-grant:read,mcp:storage:read
```

### Trusted Identity Provider Configuration

Each trusted Identity Provider is configured with a unique name and its own issuer and JWKS URL. Only tokens from configured IdPs are accepted for exchange. Configure an entry here for every issuer you want ESS to integrate with, including the [Solid OIDC Broker](https://docs.inrupt.com/ess/services/advanced-configuration/service-oidc.md) if it is deployed.

{% hint style="warning" %}
If the Solid OIDC Broker is deployed, trust **the Broker's** issuer URL here rather than that of the enterprise Identity Provider it brokers. The Broker is an Identity Provider in its own right, and it is the issuer of the tokens ESS receives. Configuring the upstream IdP instead causes those tokens to be rejected. See [Advanced Configuration](https://docs.inrupt.com/ess/services/advanced-configuration.md#platform-management).
{% endhint %}

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_IDPS\_{NAME}\_ISSUER**

The issuer URL for the trusted Identity Provider. Must match the **`iss`** claim in the IdP's tokens.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_KEYCLOAK_ISSUER=https://idp.example.com/realms/ess
```

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_IDPS\_{NAME}\_JWKS\_URL**

The JWKS URL for fetching the Identity Provider's public keys, used to validate incoming tokens.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_KEYCLOAK_JWKS_URL=https://idp.example.com/realms/ess/protocol/openid-connect/certs
```

#### **INRUPT\_PLATFORM\_TOKEN\_EXCHANGE\_IDPS\_{NAME}\_EXPECTED\_AUDIENCE**

Required. The expected **`aud`** claim in tokens from this IdP. Tokens that do not contain a matching audience claim are rejected.

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_KEYCLOAK_EXPECTED_AUDIENCE=https://platform.example.com
```

{% hint style="info" %}
**Multiple IdPs**

To configure multiple Identity Providers, use a different name for each. For example:

```bash
INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_OKTA_ISSUER=https://dev-123456.okta.com/oauth2/default
INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_OKTA_JWKS_URL=https://dev-123456.okta.com/oauth2/default/v1/keys

INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_AZUREAD_ISSUER=https://login.microsoftonline.com/{tenant}/v2.0
INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_AZUREAD_JWKS_URL=https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys
```

New IdPs can be added post-deployment without system redeployment.
{% endhint %}

{% hint style="warning" %}
**Important**

Only add trusted Identity Providers. Each IdP should be verified and vetted before being configured.
{% endhint %}

#### **INRUPT\_JWT\_ISSUER\_ALLOW\_LIST**

A comma-separated list of issuer URLs accepted by the Solid JWT authentication layer. This setting applies only to deployments that support Solid JWT authentication.

```bash
INRUPT_JWT_ISSUER_ALLOW_LIST=https://idp.example.com/realms/ess
```

{% hint style="info" %}
**Relationship to trusted Identity Provider configuration**

This setting is separate from the [trusted Identity Provider configuration](#trusted-identity-provider-configuration) above, and the two act at different points in a request:

* `INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_{NAME}_*` governs which issuers the Platform Management service will exchange tokens for. Configure it for every issuer you integrate with, including a native IdP.
* `INRUPT_JWT_ISSUER_ALLOW_LIST` applies earlier, in the Solid JWT authentication layer carried over from releases before ESS 3.0.0.

Validating a Solid JWT requires ESS to retrieve the presenting agent's WebID and confirm it lists the token's issuer as trusted. When `INRUPT_JWT_ISSUER_ALLOW_LIST` is set, tokens from issuers outside the list are rejected before that retrieval happens. Setting it is recommended wherever Solid JWT authentication is in use: it limits the work an unauthenticated client can force ESS to perform by presenting fabricated tokens, mitigating denial-of-service attempts against the Solid JWT authentication path.
{% endhint %}

### Client Credentials Configuration

{% hint style="success" %}
Added in version 3.5.0
{% endhint %}

#### **INRUPT\_PLATFORM\_OAUTH\_CLIENT\_DOMAIN\_ALLOW\_LIST**

Default: *none*

A comma-separated list of hosts that CIMD documents and JSON Web Key Sets can be fetched from. Hosts are matched exactly. If not set, no CIMD client can authenticate. See [Manage the CIMD Client Domain Allow List](https://docs.inrupt.com/ess/installation/customize-configurations/customization-security/manage-cimd-client-domains.md).

```bash
INRUPT_PLATFORM_OAUTH_CLIENT_DOMAIN_ALLOW_LIST=agent.example.com,clients.partner.example
```

#### **INRUPT\_PLATFORM\_OAUTH\_CLIENT\_AUDIENCES**

Default: *none*

A comma-separated list of ESS service URLs that tokens issued to CIMD clients can be used with. A client credentials request can only request a **`resource`** from this list. Used as the **`aud`** claim when no **`resource`** is requested. If not set, no token can be issued with the `client_credentials` grant.

```bash
INRUPT_PLATFORM_OAUTH_CLIENT_AUDIENCES=https://mcp.{ESS Domain}
```

#### **INRUPT\_PLATFORM\_OAUTH\_CLIENT\_SCOPE**

Default: **`mcp:access-request:write,mcp:access-request:read,mcp:access-grant:read,mcp:storage:read`**

A comma-separated list of the scopes that can be issued to CIMD clients. Requests for any other scope are rejected.

#### **INRUPT\_PLATFORM\_OAUTH\_CLIENT\_DEFAULT\_SCOPE**

Default: **`mcp:access-request:write`**

{% hint style="info" %}
Changed in version 3.5.1. In ESS 3.5.0, the default is **`mcp:storage:read`**.
{% endhint %}

A comma-separated list of the scopes granted when a client credentials request does not include a **`scope`** parameter. These scopes must also be allowed by [**`INRUPT_PLATFORM_OAUTH_CLIENT_SCOPE`**](#inrupt_platform_oauth_client_scope) and by the client's document.

#### **INRUPT\_PLATFORM\_OAUTH\_CLIENT\_ASSERTION\_SIGNING\_ALGORITHMS**

Default: **`RS256,PS256,ES256`**

A comma-separated list of the signing algorithms accepted for client assertions. Only asymmetric algorithms are permitted: **`RS256`**, **`RS384`**, **`RS512`**, **`PS256`**, **`PS384`**, **`PS512`**, **`ES256`**, **`ES384`**, and **`ES512`**.

#### **INRUPT\_PLATFORM\_OAUTH\_CLIENT\_MAX\_ASSERTION\_TTL\_SECONDS**

Default: **`300`**

The maximum time, in seconds, that a client assertion's **`exp`** can be in the future.

### Kafka Configuration

{% hint style="info" %}
**Tip**

See also [ESS' Kafka Configuration](https://docs.inrupt.com/ess/services/appendix/appendix-kafka-configuration.md)
{% endhint %}

#### **KAFKA\_BOOTSTRAP\_SERVERS**

Default: **`localhost:9092`**

Comma-delimited list of Kafka broker servers for audit event publishing.

## Additional Information

* [OAuth 2.0 Token Exchange (RFC 8693)](https://datatracker.ietf.org/doc/html/rfc8693)
* [OAuth 2.0 Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
* [JWT Profile for OAuth 2.0 Client Authentication (RFC 7523)](https://datatracker.ietf.org/doc/html/rfc7523)
* [OAuth 2.0 Authorization Server Metadata (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414)
* [Resource Indicators for OAuth 2.0 (RFC 8707)](https://datatracker.ietf.org/doc/html/rfc8707)
* [JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)](https://datatracker.ietf.org/doc/html/rfc9068)
* [Model Context Protocol Authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
* [OpenID Connect](https://openid.net/connect/)
