Token exchange reference

The token exchange endpoint trades a subject token from your identity provider for a short-lived Reducto access token. It implements OAuth 2.0 Token Exchange (RFC 8693). For concepts and setup, see Workload identity federation. The Reducto Python and Node.js SDKs call this endpoint for you. Call it directly when you use another language or want to manage the access token yourself.

Endpoint

POST https://platform.reducto.ai/oauth/token

Use the host of your region: platform.reducto.ai (US), eu.platform.reducto.ai (EU) or au.platform.reducto.ai (AU). The endpoint accepts application/json or application/x-www-form-urlencoded bodies. It needs no Authorization header.

import os

import httpx

response = httpx.post(
    "https://platform.reducto.ai/oauth/token",
    json={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "subject_token": os.environ["SUBJECT_TOKEN"],
        "identity_provider_id": os.environ["REDUCTO_IDENTITY_PROVIDER_ID"],
    },
)
response.raise_for_status()
token = response.json()
print(token["expires_at"])

const response = await fetch("https://platform.reducto.ai/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
    subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
    subject_token: process.env.SUBJECT_TOKEN,
    identity_provider_id: process.env.REDUCTO_IDENTITY_PROVIDER_ID,
  }),
});
if (!response.ok) {
  throw new Error(`Token exchange failed: ${await response.text()}`);
}
const token = await response.json();
console.log(token.expires_at);

curl -X POST "https://platform.reducto.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
  --data-urlencode "subject_token=$SUBJECT_TOKEN" \
  --data-urlencode "identity_provider_id=$REDUCTO_IDENTITY_PROVIDER_ID"

Request fields

Field	Required	Description
`grant_type`	Yes	Must be `urn:ietf:params:oauth:grant-type:token-exchange`.
`subject_token_type`	Yes	`urn:ietf:params:oauth:token-type:jwt` or `urn:ietf:params:oauth:token-type:id_token`. Reducto verifies both types the same way. Use `id_token` for OIDC ID tokens, such as Google metadata server tokens, and `jwt` for everything else.
`subject_token`	Yes	The OIDC JWT or SPIFFE JWT-SVID from your identity provider.
`identity_provider_id`	Yes	The ID of the Reducto identity provider, `wip_` followed by 24 characters.

Reducto ignores scope, resource, audience and requested_token_type if you send them. Access is decided by the matching mapping only.

Response

A successful exchange returns HTTP 200:

{
  "access_token": "rdat_eyJhbGciOiJIUzI1NiIsImtpZCI6InYxIiwidHlwIjoiSldUIn0.eyJvcmdfaWQiOiJvcmdfN...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": 1793329845
}

Field	Type	Description
`access_token`	String	The Reducto access token. Send it as `Authorization: Bearer <access_token>`. Treat it as opaque: the `rdat_` prefix is stable, the rest can change.
`issued_token_type`	String	Always `urn:ietf:params:oauth:token-type:access_token`.
`token_type`	String	Always `Bearer`.
`expires_in`	Integer	Lifetime in seconds, counted from issue. Time spent in transit uses part of it.
`expires_at`	Integer	Expiry as a Unix timestamp in seconds (UTC).

The response has no refresh token. To renew, exchange a fresh subject token before expires_at.

Access token lifetime

The access token expires at the earliest of:

The matching mapping’s token_lifetime_seconds (60 to 3600, default 3600).
3600 seconds after issue.
The subject token’s exp.

A subject token that expires in 5 minutes gives an access token that expires in 5 minutes or less.

Subject token validation

Reducto verifies the subject token before it evaluates mappings. The token must:

Be a compact JWT of at most 16 KiB.
Have a kid header and an alg header of RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512 or EdDSA. Reducto rejects none and the HS* family.
Have a valid signature from a key in the provider’s key source, matched by kid.
Have an iss claim equal to the provider issuer. A trailing slash on either side is ignored. Everything else, including scheme and path, must match.
Have an aud claim that equals, or is a list that contains, the provider audience.
Have sub, exp and iat claims.
Be within its validity window. Reducto allows 30 seconds of clock skew on exp and iat.
Have been issued less than 24 hours ago (iat), even if exp is later.

Reducto does not reject a subject token that it has seen before. You can exchange the same token more than once while it is valid, for example when a token file has not rotated yet. After verification, Reducto runs the provider’s attribute transformations, then evaluates every enabled mapping of the provider. Exactly one mapping must match. See Mapping resolution.

Errors

A failed exchange returns HTTP 400, or HTTP 503 for temporarily_unavailable, with an RFC 6749 error body:

{
  "error": "invalid_grant",
  "error_description": "The subject token claims are invalid or expired."
}

`error`	Cause
`invalid_request`	A required field is missing, the body is not valid JSON or form data, the body is larger than 64 KiB, or `subject_token_type` is not one of the two supported values.
`unsupported_grant_type`	`grant_type` is not `urn:ietf:params:oauth:grant-type:token-exchange`.
`invalid_grant`	The provider, the subject token or the mapping failed. `error_description` names the stage.
`temporarily_unavailable`	HTTP 503. Token exchange is not available in this region right now, or Reducto could not reach your provider’s discovery document or JWKS (a timeout, a connection failure or an HTTP 5xx from your provider). Retry with backoff.

invalid_grant covers these stages:

Stage	`error_description`	Typical causes
Malformed	`The subject token is not a valid JWT.`	The token is not a JWT, is larger than 16 KiB, has no `kid`, or uses an unsupported `alg`.
Provider	`The identity provider is unknown or disabled.`	The provider ID is unknown in this region, or the provider is disabled.
Keys	`The signing key for the subject token could not be resolved.`	Your provider’s discovery document or JWKS returned an error other than HTTP 5xx (for example HTTP 404) or is not valid, or no key matches the token `kid`.
Signature	`The subject token signature is invalid.`	The token was not signed by the key with its `kid`.
Claims	`The subject token claims are invalid or expired.`	`iss` or `aud` does not match, a required claim is missing, or the token is expired, not yet valid, or older than 24 hours.
Transform	`An attribute transformation failed for the subject token.`	A transformation claim path does not exist in the token, or its value is not a string, an integer or a boolean.
Mapping	`The subject token does not match exactly one enabled mapping.`	No enabled mapping matches, or more than one matches.

error_description does not include your issuer, audience or mapping values. Admins can see the full reason for each failure in Studio under the exchange history. Match on the error field in code; the wording of error_description can change.

Rate limits

Reducto limits POST /oauth/token per client IP address at the API edge. The default limit is 300 requests in 5 minutes. A request over the limit returns HTTP 429 from the edge. The body of this response does not use the {error, error_description} format, so check the status code.

Cache the access token and use it until shortly before expires_at. Do not exchange a token for each API request.
Share one client, or one cached token, between the threads and workers of a process. The SDKs do this for each client.
Workloads that share one outbound IP address, such as pods behind a NAT gateway, share the limit.
After a 429, retry with exponential backoff.

The limit applies only to the token endpoint. A 429 from POST /oauth/token means that you are over this limit. It is not one of the infrastructure 429s described in Rate limits.

Authorization behavior

An access token authenticates as your organization, the same way an API key does. It works on every endpoint that accepts an API key, with the same rate limits, billing checks and organization settings. Usage from an access token is attributed to the mapping that issued it. An access token works only in the region that issued it. Reducto checks the provider and mapping behind every access token. If you disable or delete either one, its access tokens fail with HTTP 401 within 60 seconds. Requests made with an expired or revoked access token return HTTP 401. The SDKs handle this by exchanging once more and retrying the request.

Limitations

Only JWT subject tokens are supported: OIDC JWTs and SPIFFE JWT-SVIDs. X.509 certificates, SPIFFE X.509-SVIDs and AWS SigV4 credentials are not supported.
A mapping grants full organization access. Mappings cannot narrow access to some endpoints.
Identity providers and mappings are managed in Studio. There is no public management API yet.
Each organization can have 50 identity providers, and each provider 50 mappings.

Get Started

Developer Tools

Core Functions

Workflows and Pipelines

Configurations

Reference

Components

Enterprise Resources

Security and privacy

On-premise Resources