An OIDC client (using the token exchange mechanism) enables applications to exchange an existing access token for a new one, without requiring the customer to re-authenticate. This client type is used in scenarios where a token needs to be modified, for example, to change scopes, audiences, or claims, or to support delegation and impersonation flows.

Capabilities

Clients using the token exchange mechanism support the following scenarios:

• Scope changes: Request a new token with a reduced or modified set of scopes.
• Audience changes: Obtain a token targeted at a different resource server.
• Claim mapping: Modify or enrich token claims during exchange.
• Delegation: Use the act claim to act on behalf of another customer or entity.
• Impersonation: Use the may_act claim to impersonate another customer, with the appropriate authorization.

Sample use cases

• Scope reduction for downstream services: An application receives an access token with broad scopes from Strivacity during customer login. When calling a downstream microservice, it only needs read-only access. Token exchange allows you to narrow that scope to only the needed one when the token is exchanged for a new one. This improves security by minimizing over-scoped tokens shared across internal services.
• Token for audience change between APIs: A frontend app authenticates a customer and receives a token with an audience of api.frontend.strivacity.com. To call a partner API (api.partner.com), it needs a token scoped for that audience. Token exchange enables secure multi-audience access while preventing token misuse across unintended APIs.
• Delegated access with act-as claim: A customer support portal allows support agents to act on behalf of end users to troubleshoot issues. Token exchange supports secure delegation patterns with full auditability and separation of roles.

Configuration

You can configure this client in the Admin Console under Applications → select application → Clients → select client.

OIDC clients (using the token exchange mechanism) include the following configuration tabs:

• General
• OAuth2/OIDC
• Token exchange

After saving the client, the following tabs become available:

• Claim mapping
• Logs

General

Use the General tab to define basic client properties.

• Name: name displayed in the client list in the Admin Console.
• Description: optional description visible only in the Admin Console.
• Enabled: enables or disables the client. Disabled clients cannot be used for token exchange.
• Application domain: defines which domain is used for this client. By default, the instance domain is used.

OAuth2/OIDC

The OAuth2/OIDC tab contains the OpenID Connect configuration for the client. These settings define how the client authenticates with Strivacity and how tokens are issued.

For a complete description of OAuth2/OIDC configuration options, see OAuth2/OIDC properties setup.

Token exchange

The Token exchange tab defines how token exchange requests are validated and how new tokens are issued.

Allowed exchange

Determines which type of token exchange is permitted:

• Impersonation (may_act claim): The client fully impersonates another customer, making requests as that customer.
• Delegation (act claim): The client acts on behalf of another customer while retaining its own identity in the token chain.

Use case example: Enable delegation for a support application, while restricting impersonation to internal tools.

Allowed authorization servers

Defines which authorization servers are trusted when validating incoming tokens.

Subject tokens

Configure the properties of accepted subject tokens (the tokens to be exchanged):

• Token type: determines what type of token is accepted.
  • Supported token types:
    • urn:ietf:params:oauth:token-type:access_token
    • urn:ietf:params:oauth:token-type:jwt
    • urn:ietf:params:oauth:token-type:id_token
• Issuer: the authorization server that issued the token.
• JWKS URI: the endpoint used to validate the token signature.

Use Add subject token to allow multiple authorization servers.

Settings

Allowed audiences

Defines which aud (audience) values are allowed in the exchanged token. This is critical in audience change scenarios, where tokens are reissued for use with different downstream APIs or services.

Use Add audience to specify one or more allowed audiences.

Use case example: A frontend app can exchange a token for one with an audience of orders-api.strivacity.com, but not admin-api.strivacity.com.

Allowed resources

Specifies which resource identifiers (resource parameter) are valid targets for exchanged tokens. This setting acts as an additional constraint for resource-specific access and complements the audience setting. Useful when APIs support multiple logical resource partitions under the same audience.

Use Add resource to specify allowed resources.

Use case example: Allow tokens to be scoped only to orders and inventory resources, not billing.

Scopes

Controls how scopes are applied to the exchanged token:

• Pass through only: scopes from the original token are preserved.
• Allow the following scopes: restricts the exchanged token to a predefined set of scopes.

Use case example: A service exchanges a token but is only allowed to request read:users, even if the original token has broader scopes like write:users.

Subject token account ID mapping

Defines how the subject token is mapped to a customer account in Strivacity.

Use this field to specify which claim or identifier from the subject token should be used to resolve the customer account.

Claim mapping

The Claim mapping tab becomes available after the client is saved. Use this tab to define a JavaScript function that customizes the token issued during token exchange.

The function can:

• Add custom claims to the issued access token
• Override the requested scopes
• Reject token issuance with a custom error

The function receives the following arguments:

• request_body: request body of the token exchange request.
• requested_scopes: list of requested scopes. If scope passthrough is used and no scopes are requested, this contains the scopes from the subject token.
• account: subject customer account.

Return a ClaimMapping object to continue issuing the token. Throw DenyRequest to reject token issuance.

Code example:

module.exports = async function ({ request_body, requested_scopes, account }) {
  return new ClaimMapping({ custom: "data" });
}; 

Use case example:

Use the sub claim from the input token to:

1. Look up the customer’s department in your HR system.
2. Add department and manager_id claims to the output token.
3. Rename email_verified to is_email_verified.

Logs

The Logs tab provides access to token exchange activity for the client. Use this tab to monitor and troubleshoot token exchange requests.

Columns

The log table includes the following columns:

• Date: date and time of the token exchange event.
• Log level counts: number of log entries by level for the given time.

Filters

Use the available filters to narrow down log results:

• Date: filter logs by a specific time range.
• Account ID: filter logs for a specific customer account.
• Account event ID: filter logs by event identifier.
• Log level: filter logs by log severity or type.