Créer un jeton porteur

Échange les informations d’authentification d’une Auth Key contre un jeton porteur à portée définie.

Il s’agit du point de terminaison de jetons OAuth 2.0. Les clients sans interface graphique échangent leur Auth Key et leur Auth Secret contre un jeton porteur de courte durée avec le type d’octroi client_credentials, pris en charge directement par l’API Transloadit. Les clients MCP qui se sont connectés par URL échangent le code d’autorisation provenant de l’écran de consentement de la Console avec le type d’octroi authorization_code (PKCE S256, sans informations d’identification HTTP Basic) et effectuent la rotation du jeton de rafraîchissement obtenu avec le type d’octroi refresh_token.

Sur /token, les erreurs d’octroi OAuth pour authorization_code et refresh_token utilisent le corps standard contenant error et error_description. Les limites de débit renvoient RATE_LIMIT_REACHED (429), et les défaillances internes inattendues renvoient SERVER_500 (500). Les requêtes mal formées rejetées avant l’identification du type d’octroi peuvent recevoir une demande d’authentification HTTP Basic (401), ou TOKEN_INVALID_REQUEST si des informations d’identification Basic ont été fournies.

Les jetons obtenus avec les informations d’identification du client sont générés côté serveur à l’aide de votre Auth Key et de votre Auth Secret. Si vous exposez la création de jetons via une interface utilisateur, appelez /token depuis votre backend (jamais directement depuis le navigateur).

Les Workspaces résiliés ne peuvent pas créer de nouveaux jetons porteurs. Pour les points de terminaison dont la documentation autorise explicitement les lectures après résiliation, utilisez plutôt la procédure de lecture signée avec une Auth Key active existante. La facturation dispose de sa propre procédure de facturation signée.

Les requêtes doivent utiliser application/x-www-form-urlencoded ; le type d’octroi client_credentials nécessite également l’authentification HTTP Basic :

Dans un shell de confiance côté serveur disposant de curl et de jq, définissez TRANSLOADIT_KEY et TRANSLOADIT_SECRET avec les valeurs de votre Auth Key et de votre Auth Secret. Gardez secrets les deux informations d’identification et le jeton obtenu ; ne procédez jamais à cette configuration dans du code de navigateur.

Cet exemple demande un accès en lecture et en écriture aux Assemblies et enregistre la valeur access_token renvoyée dans TRANSLOADIT_TOKEN pour les requêtes suivantes dans le même shell. Pour un autre point de terminaison, utilisez plutôt les portées qui y sont indiquées ; l’Auth Key doit déjà les accorder. Les points de terminaison authentifiés par une Auth Key ou un jeton porteur incluent la configuration de jeton appropriée dans leurs exemples de requêtes.

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

L’authentification HTTP Basic avec votre Auth Key et votre secret est requise pour les valeurs suivantes de grant_type : client_credentials. Les autres valeurs prises en charge ne nécessitent pas d’informations d’identification de compte. N’envoyez pas d’en-tête Authorization pour ces requêtes ; la preuve spécifique à leur autorisation reste requise.

Type de contenu : application/x-www-form-urlencoded

Les champs suivants peuvent être envoyés au maximum une fois : aud, client_assertion, client_assertion_type, client_id, code, code_verifier, grant_type, redirect_uri, refresh_token, resource, scope.

Utiliser le jeton

Passez le jeton sous la forme Authorization: Bearer <access_token> dans les requêtes API. Lorsqu’une requête est authentifiée avec un jeton porteur valide, API2 considère l’exigence de Signature Authentication comme satisfaite et ignore la validation de la signature. Signature Authentication n’est exigée que pour les requêtes avec clé/secret. Les vérifications de portée continuent de s’appliquer. L’audience par défaut api2 est acceptée par les points de terminaison API2 ordinaires et est valide pendant 21 600 secondes par défaut. L’audience mcp est acceptée par le serveur MCP, qui la relaie à API2 avec des informations d’identification de service ; elle est rejetée par les points de terminaison API2 ordinaires lorsqu’elle est présentée directement, et est valide pendant 604 800 secondes par défaut. Considérez la valeur expires_in de la réponse comme faisant autorité.