Skip to content
Cofide Cofide

Credex Exchange Types

This guide covers the token exchanges Credex supports and how a workload requests each one. Credex acts as a policy-backed credential broker to bridge OAuth and SPIFFE systems across one or more trust domains.

Once you understand the exchange you need, see Exchange Policies for how to author the policies that permit it.

Credex exposes two endpoints for performing exchanges: POST /token for OAuth AS token exchanges (RFC 8693) and POST / for SPIFFE token exchanges. The full set of endpoints, including the OIDC and OAuth metadata endpoints, is listed in the Reference.

Credex is a flexible security token service which can be used for various purposes.

The type of token exchange performed is determined by request parameters in a given exchange request, such as which tokens the client presents and which it omits.

Broadly speaking, the use cases for Credex can be broken down into four different exchange types based on their semantics and intended use cases:

  • Impersonation exchanges
  • Delegation exchanges
  • OAuth Bridge exchanges
  • OIDC to SPIFFE exchanges

Impersonation

Section titled “Impersonation”

An RFC 8693-compliant request where the client presents a subject token and no actor token, and receives an access token that carries only the subject’s identity.

This is appropriate when the calling workload is genuinely the principal: there is no separate user or upstream identity to preserve.

sequenceDiagram
    participant W as Workload
    participant C as Credex
    participant S as Downstream service

    W->>C: POST /token (client_assertion, subject_token, audience, scope)
    C->>C: Validate client and subject token
    C->>C: Evaluate policy and grant scopes
    C-->>W: access_token { sub: workload }
    W->>S: Authorization: Bearer access_token
    S->>S: sub = workload

In this scenario, the workload presents its own JWT-SVID as both client_assertion and subject_token. For example:

POST /token
Content-Type: application/x-www-form-urlencoded


grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe
&client_assertion=<JWT-SVID, aud=https://credex.example.com/token>
&subject_token=<JWT-SVID, aud=https://credex.example.com/token>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt_spiffe
&audience=https://api.example.com
&scope=data:read

and the response would include a token with a sub claim but no act claim:

{
  "iss": "https://credex.example.com",
  "sub": "spiffe://example.com/<workload-identifier>",
  "aud": "https://api.example.com",
  "exp": 1796000600,
  "iat": 1796000000
}

The resulting token would then be used to authenticate to https://api.example.com, assuming the API is configured to trust Credex-issued tokens.

Delegation

Section titled “Delegation”

Similar to the impersonation request, except that the client presents both a subject token (the principal on whose behalf the exchange is happening) and an actor token (the workload performing the action). The issued access token preserves both identities: the subject in sub and the actor in a nested act claim.

sequenceDiagram
    participant A as Agent workload
    participant C as Credex
    participant S as Downstream service

    A->>C: POST /token (subject_token, actor_token, client_assertion, audience, scope)
    C->>C: Validate subject and actor tokens
    C->>C: Evaluate delegation policy
    C-->>A: access_token { sub: user, act: { sub: agent } }
    A->>S: Authorization: Bearer access_token
    S->>S: sub = user, act.sub = agent

In the above diagram, the Agent workload holds the subject token (user OIDC token or upstream AS access token) and its own JWT-SVID (used as both client_assertion and actor_token)

Delegation is the right choice whenever the calling workload is acting on behalf of someone else, for example an agent acting on behalf of a user, or a service-bus consumer acting on behalf of a publisher. Downstream services can inspect both claims to apply identity-aware audit logging and authorization decisions.

If the subject token itself already carries an act claim (e.g. it was issued by Credex in a previous delegation hop), Credex nests the previous actor inside the new actor claim, preserving the entire chain.

In this scenario, the agent workload presents the subject token (e.g. a user OIDC token) as subject_token and its own JWT-SVID as both client_assertion and actor_token. For example:

POST /token
Content-Type: application/x-www-form-urlencoded


grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe
&client_assertion=<JWT-SVID for agent, aud=https://credex.example.com/token>
&subject_token=<OIDC ID token from trusted IdP>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt
&actor_token=<JWT-SVID for agent, aud=https://credex.example.com/token>
&actor_token_type=urn:ietf:params:oauth:token-type:jwt_spiffe
&audience=https://api.example.com
&scope=data:read

and the response would include a token with both a sub claim (the delegated subject) and an act claim (the agent):

{
  "iss": "https://credex.example.com",
  "sub": "user-12345",
  "act": {
    "sub": "spiffe://example.com/<agent-identifier>"
  },
  "aud": "https://api.example.com",
  "exp": 1796000600,
  "iat": 1796000000
}

The resulting token would then be used to authenticate to https://api.example.com, which can use both sub and act.sub for authorization decisions and audit logging.

OAuth Bridge exchange

Section titled “OAuth Bridge exchange”

An OAuth Bridge exchange is a standard RFC 8693 token exchange request that Credex fulfils by obtaining a token from a downstream OAuth authorization server and returning it to the caller, rather than minting a token itself. Credex acts as an identity bridge between the caller’s trust domain and the downstream authorization server. For the use case this exchange addresses, see Federating to a legacy OAuth authorization server on the Use Cases page.

The request looks like any other impersonation or delegation exchange. Credex routes it to a downstream authorization server when the matching policy carries an outbound OAuth configuration (see OAuth Bridge exchange on the Exchange Policies page).

This lets a workload present its own identity and receive a token minted by the downstream authorization server, without ever holding a long-lived client credential for that server.

The caller’s identity does not have to be a SPIFFE SVID. The bridge works with any identity Credex accepts for client authentication: a JWT-SVID presented with the jwt-spiffe client assertion type, or an external JWT or OIDC ID token from a trusted issuer presented with the jwt-bearer client assertion type. This means workloads running outside a SPIFFE trust domain, such as those authenticating with a cloud provider or IdP-issued token, can use the bridge on the same terms as SPIFFE-attested workloads. See OAuth AS Token Types for the full set of accepted token types.

In more detail:

  • Credex authenticates to the downstream server as the workload, not as itself. It presents the workload’s identity as the OAuth client, signing a short-lived JWT Bearer client assertion on the workload’s behalf.
  • There is no client secret to store, mount, or rotate. The workload’s only durable credential remains its own identity.

This follows the “Authorization Server Acting as Client” pattern in Appendix B.2 of the IETF OAuth Identity and Authorization Chaining Across Domains draft, in which the authorization server performs the downstream exchange so the caller makes a single request rather than juggling tokens across two hops. Credex adapts the pattern: where B.2 has the authorization server present an RFC 7523 JWT bearer authorization grant, Credex currently supports a client_credentials grant, since some authorization servers do not support the JWT bearer grant.

Because Credex authenticates as the workload rather than as itself, the workload must be registered as an OAuth client at the downstream authorization server before the exchange can succeed. That client registration must:

  • Identify the client by the workload’s identity, which is the sub of the client assertion Credex signs. This is the caller’s own identifier, its SPIFFE ID or the sub of its external JWT, or the policy’s outbound_identity where that is set.
  • Use JWT bearer client authentication (called private_key_jwt in OIDC), with its jwks_uri set to Credex’s /keys endpoint so the downstream server can verify the signed client assertion against Credex’s published keys.
  • Permit the client_credentials grant.
  • Accept the audience of the client assertion, which is the authorization server’s token endpoint URL by default, or the exchange policy’s oauth_as.audiences values if those are set.
  • Be authorized for the scopes and audience the exchange requests. Credex forwards the granted scope and audience to the downstream token endpoint when they are present, so the client must be permitted to obtain them.
sequenceDiagram
    participant W as Workload
    participant C as Credex
    participant D as External OAuth AS
    participant S as External service

    W->>C: POST /token<br/>client_assertion=JWT-SVID or external JWT<br/>subject_token, audience, scope
    C->>C: Validate identity and evaluate policy
    note over C,D: Policy carries outbound OAuth config,<br/>so Credex bridges downstream
    C->>D: client_credentials<br/>(short-lived signed JWT client assertion)
    D->>D: Verify assertion via Credex /keys
    D-->>C: access_token<br/>(minted by the external AS)
    C-->>W: access_token returned verbatim
    W->>S: Authorization: Bearer access_token

The workload’s request to Credex is an ordinary token exchange. The following example uses a JWT-SVID, but a workload outside a SPIFFE trust domain would instead send client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer with its external JWT, and a matching subject_token_type such as urn:ietf:params:oauth:token-type:jwt:

POST /token
Content-Type: application/x-www-form-urlencoded


grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-spiffe
&client_assertion=<JWT-SVID, aud=https://credex.example.com/token>
&subject_token=<JWT-SVID, aud=https://credex.example.com/token>
&subject_token_type=urn:ietf:params:oauth:token-type:jwt_spiffe
&audience=downstream-service
&scope=read

Credex performs a client_credentials exchange against the downstream authorization server and returns the issued token to the caller verbatim. The format and claims of the returned token are determined by the downstream authorization server, not by Credex.

To configure which requests are bridged and to which downstream authorization server, see OAuth Bridge exchange on the Exchange Policies page.

OIDC to SPIFFE (Preview)

Section titled “OIDC to SPIFFE (Preview)”

An OIDC to SPIFFE exchange involves sending a request containing an OIDC ID token signed by a trusted issuer and receiving a JWT-SVID signed by the SPIRE server in response.

This allows non-SPIFFE-native workloads or those running in an environment where SPIFFE Workload API access is not available (e.g. ‘serverless’ workloads such as GitHub Actions or AWS Lambda functions) to obtain SVIDs which are trusted by other SPIFFE-native systems.

An OIDC to SPIFFE exchange requires Credex’s SPIFFE Token Exchange subsystem to be enabled (see Deployment).

The exchange request format is

POST /
Content-Type: application/json


{
  "InboundToken": "<OIDC JWT string>"
}

and the response format is

{
  "status": "ok",
  "token": "<JWT-SVID string>"
}

This functionality is under active development; the request and response formats may change in the near future.

OIDC to SPIFFE exchanges are gated differently from the RFC 8693 exchanges above: see OIDC to SPIFFE on the Exchange Policies page.

© 2026 Cofide Limited. All rights reserved.