For the complete documentation index, see llms.txt. This page is also available as Markdown.

Access Tokens

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

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

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-compliant JWT access tokens, signed by the Platform Management service.

If your deployment requires Solid-OIDC protocol compliance for interoperability with other Solid servers, ESS also supports authentication via the Solid OIDC Broker. This is an advanced configuration not needed for standard enterprise deployments.

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, 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:

https://platform.{ESS Domain}

Authorization Server Metadata

The Platform Management service publishes OAuth 2.0 Authorization Server Metadata (RFC 8414). 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

Field
Description

issuer

The issuer of ESS Access Tokens

token_endpoint

jwks_uri

response_types_supported

Always empty. ESS has no authorization endpoint: tokens are issued only by the token endpoint.

grant_types_supported

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

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

Token Exchange Flow

  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.

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.

scope

No

See Token Endpoint. Must be one of 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

Client Credentials with CIMD

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 (CIMD), and do not need an account at your Identity Provider.

This is the authentication flow recommended by the Model Context Protocol for machine clients, and it is how an AI agent obtains a token for the MCP Service.

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.

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

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 and the agent binding.

Client Credentials Flow

  1. The client discovers the token endpoint from the 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.

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

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:

  1. Create the account with POST /admin/provision.

  2. Bind the client ID with PUT /admin/provision/{accountId}/identity, using a mapping of type cimd whose issuer and subject are both the client ID.

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.

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, 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 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. Must be one of INRUPT_PLATFORM_OAUTH_CLIENT_AUDIENCES, for example https://mcp.example.com.

scope

No

See Token Endpoint. Must be one of 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 is issued.

For example:

Scopes

The following scopes can be issued to CIMD clients. They control which MCP Service 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) 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; for token exchange, all the configured scopes, or no scope claim if none are configured.

Error Responses

Error responses use the OAuth 2.0 error format (RFC 6749):

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

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

INRUPT_PLATFORM_TOKEN_EXCHANGE_TTL

Default: 300 (5 minutes)

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

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.

If you deploy the Solid interoperability services, add the WebID Service to the list:

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.

INRUPT_PLATFORM_TOKEN_EXCHANGE_SCOPES_SUPPORTED

Optional. A comma-separated list of scopes to advertise in the scopes_supported field of the authorization server metadata, in addition to the scopes available to CIMD clients. Does not change which scopes can be issued.

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 if it is deployed.

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.

INRUPT_PLATFORM_TOKEN_EXCHANGE_IDPS_{NAME}_JWKS_URL

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

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.

Multiple IdPs

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

New IdPs can be added post-deployment without system redeployment.

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.

Relationship to trusted Identity Provider configuration

This setting is separate from the 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.

Client Credentials Configuration

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.

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.

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

Changed in version 3.5.1. In ESS 3.5.0, the default is mcp:storage:read.

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

KAFKA_BOOTSTRAP_SERVERS

Default: localhost:9092

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

Additional Information

Last updated