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:
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.
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.
Endpoint
https://platform.{ESS Domain}/.well-known/oauth-authorization-server
Method
GET
Example Response
issuer
The issuer of ESS Access Tokens
token_endpoint
The token endpoint URL
jwks_uri
The 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_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:
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:
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
Client authenticates with the external Identity Provider
IdP returns an ID token
Client sends the ID token to the Platform Management service's token endpoint
The endpoint validates the ID token, maps the identity to ESS internal identifiers, and returns an ESS Access Token
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
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:
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.
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.
Client Credentials Flow
The client discovers the token endpoint from the authorization server metadata.
The client sends a token request containing a signed client assertion.
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.
ESS finds the agent account bound to the client ID, confirms the account is active, and returns an ESS Access Token.
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.
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:
Create the account with
POST /admin/provision.Bind the client ID with
PUT /admin/provision/{accountId}/identity, using a mapping of typecimdwhoseissuerandsubjectare both the client ID.Activate the account with
PUT /admin/provision/{accountId}/activate.
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:
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:
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.
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:
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):
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.
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:
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.
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.
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.
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
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