Credex Reference

This page is a lookup reference for the Credex HTTP API surface, the token types Credex accepts, and the audience (aud) requirements for each token in an exchange request. For how to request an exchange, see Exchange Types; for how exchanges are gated, see Exchange Policies.

HTTP API

The Credex HTTP API surface is summarized in the following table:

Method	Path	Description
POST	/	SPIFFE Token Exchange
POST	/token	OAuth AS token exchange (RFC 8693)
GET	/.well-known/openid-configuration	OIDC provider metadata
GET	/.well-known/oauth-authorization-server	OAuth AS metadata (RFC 8414)
GET	/keys	JWKS for verifying issued tokens
GET	/health	Liveness/readiness probe

OAuth AS Token Types

The Credex OAuth Token Exchange subsystem accepts various token types for each request parameter.

The client_assertion_type parameter must be one of:

• urn:ietf:params:oauth:client-assertion-type:jwt-spiffe - SPIFFE client authentication
• urn:ietf:params:oauth:client-assertion-type:jwt-bearer - RFC 7523

Note

The SPIFFE client-assertion-type uses a hyphen to match the current SPIFFE client authentication draft specification, whereas the token-type parameters below use an underscore to match IETF naming conventions.

The subject_token_type must be one of:

• urn:ietf:params:oauth:token-type:jwt - a JWT from an external trusted issuer, similar to an RFC 7523 JWT Bearer Authorization Grant.
• urn:ietf:params:oauth:token-type:jwt_spiffe - a SPIFFE JWT-SVID.
• urn:ietf:params:oauth:token-type:access_token - an OAuth access token previously issued by Credex.
• urn:ietf:params:oauth:token-type:id_token - an OIDC ID token from an external trusted issuer.

The actor_token_type must be one of:

• urn:ietf:params:oauth:token-type:jwt_spiffe - a SPIFFE JWT-SVID.
• urn:ietf:params:oauth:token-type:access_token - an OAuth access token previously issued by Credex.

RFC 8693 also supports an optional requested_token_type parameter; however, Credex currently only supports a value of urn:ietf:params:oauth:token-type:access_token if the parameter is included (though this may change in future).

Similarly, the issued_token_type field in the response will be set to urn:ietf:params:oauth:token-type:access_token in all responses.

Token Audience Requirements

The required aud claim varies depending on the role a token plays in the exchange request. The URN prefixes have been removed from the following tables for brevity.

Client assertion

The audience requirement for the client_assertion depends on its type:

client_assertion_type	Required aud
jwt-spiffe (JWT-SVID)	Credex token endpoint URL
jwt-bearer (external JWT)	Credex token endpoint URL, or one of the allowed audiences configured for the issuer via TRUSTED_ISSUER_ALLOWED_AUDIENCES_n

For jwt-bearer, Credex follows the audience requirements in RFC 7523 for JWT bearer client authentication which state that the audience must identify the authorization server (i.e. Credex). Since some OAuth AS implementations do not allow requesting a specific audience, the TRUSTED_ISSUER_ALLOWED_AUDIENCES_n configuration may be used as a workaround for accepting audiences other than the Credex token endpoint URL.

Subject token

The audience requirement for the subject_token depends on its type:

subject_token_type	Required aud
access_token (Credex-issued)	Any
jwt (external JWT)	Credex token endpoint URL, or one of the allowed audiences configured for the issuer via TRUSTED_ISSUER_ALLOWED_AUDIENCES_n
id_token (OIDC ID token)	Credex token endpoint URL, or the subject_audience policy field
jwt_spiffe (JWT-SVID)	Any

The distinction between jwt and id_token is subtle. For jwt, Credex follows the audience requirements in RFC 7523 for JWT bearer authorization grants: the audience must identify the authorization server. The per-trusted issuer allowed audiences configuration allows for accepting audiences other than the AS token endpoint URL.

For id_token, Credex follows the audience requirements in the OpenID Connect Core 1.0 specification: the audience identifies the Relying Party that requested the ID token from the issuer (typically an IdP). This is likely to vary for each client, so a policy-driven approach is used.

Note that for clients using an ID token both as a subject ID token and JWT bearer client assertion, both TRUSTED_ISSUER_ALLOWED_AUDIENCES_n and subject_audience will need to be set if the audience is not the AS token endpoint URL.

Actor token

Actor tokens must always be bound to the Credex token endpoint:

actor_token_type	Required aud
access_token (AS-issued)	Credex token endpoint URL
jwt_spiffe (JWT-SVID)	Credex token endpoint URL