Create a bearer token

Exchanges Auth Key credentials for a scoped bearer token.

This is the OAuth 2.0 token endpoint. Headless clients exchange their Auth Key and Auth Secret for a short-lived Bearer token with the client_credentials grant, handled directly by the Transloadit API. MCP clients that connected by URL redeem the authorization code from the Console consent screen with the authorization_code grant (PKCE S256, no HTTP Basic credentials) and rotate the resulting refresh token with the refresh_token grant.

At /token, OAuth grant errors for authorization_code and refresh_token use the standard error and error_description body. Rate limits return RATE_LIMIT_REACHED (429), and unexpected internal failures return SERVER_500 (500). Malformed requests rejected before the grant is identified can receive an HTTP Basic challenge (401), or TOKEN_INVALID_REQUEST if Basic credentials were supplied.

Client-credentials tokens are minted server-side using your Auth Key/Secret. If you expose token creation via a UI, call /token from your backend (never directly from the browser).

Canceled Workspaces cannot create new bearer tokens. For endpoints whose documentation explicitly allows reads after cancellation, use the signed read recipe with an existing active Auth Key instead. Billing has its own signed billing recipe.

Requests must use application/x-www-form-urlencoded; the client_credentials grant also needs HTTP Basic Auth:

In a trusted server-side shell with curl and jq, set TRANSLOADIT_KEY and TRANSLOADIT_SECRET to your Auth Key and Auth Secret. Keep both credentials and the resulting token secret; never run this setup in browser code.

This example requests Assembly read/write access and saves the returned access_token as TRANSLOADIT_TOKEN for subsequent requests in the same shell. For another endpoint, use its listed scopes instead; the Auth Key must already grant them. Endpoints authenticated by an Auth Key or bearer token include the appropriate token setup in their request examples.

if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
  --request POST \
  --url 'https://api2.transloadit.com/token' \
  --user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'aud=api2' \
  --data-urlencode 'scope=assemblies:read assemblies:write')"; then
  printf '%s\n' "$TOKEN_RESPONSE" >&2
  exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
  jq -er '.access_token | strings | select(length > 0)')" || exit 1

HTTP Basic authentication with your Auth Key and secret is required for the following grant_type values: client_credentials. Other supported values do not need account credentials. Do not send an Authorization header for those requests; their grant-specific proof is still required.

Content type: application/x-www-form-urlencoded

The following fields may be sent at most once: aud, client_assertion, client_assertion_type, client_id, code, code_verifier, grant_type, redirect_uri, refresh_token, resource, scope.

Using the token

Pass the token as Authorization: Bearer <access_token> on API requests. When a request is authenticated with a valid Bearer token, API2 treats Signature Authentication as satisfied and skips signature validation. Signature Authentication is enforced only for key/secret requests. Scope checks still apply. The default api2 audience is accepted by regular API2 endpoints and is valid for 21,600 seconds by default. The mcp audience is accepted by the MCP server, which relays it to API2 with a service credential; it is rejected by regular API2 endpoints when presented directly, and valid for 604,800 seconds by default. Treat the response’s expires_in value as authoritative.