Bearer-Token erstellen

Ein Auth Key dient zur Authentifizierung und wird gegen ein Bearer-Token mit festgelegten Berechtigungen ausgetauscht.

Dies ist der Token-Endpunkt für OAuth 2.0. Headless-Clients tauschen ihren Auth Key und ihr Auth Secret mit dem Grant client_credentials gegen ein kurzlebiges Bearer-Token ein. Dies wird direkt von der Transloadit API abgewickelt. MCP-Clients, die eine Verbindung per URL hergestellt haben, lösen den Autorisierungscode aus dem Zustimmungsdialog der Konsole mit dem Grant authorization_code ein (PKCE S256, keine HTTP-Basic-Zugangsdaten) und rotieren das daraus resultierende Refresh-Token mit dem Grant refresh_token.

Bei /token verwenden OAuth-Grant-Fehler für authorization_code und refresh_token den standardmäßigen Antwort-Body mit error und error_description. Bei Ratenbegrenzungen wird RATE_LIMIT_REACHED (429) zurückgegeben, bei unerwarteten internen Fehlern SERVER_500 (500). Fehlerhafte Anfragen, die abgelehnt werden, bevor der Grant identifiziert wurde, können eine HTTP-Basic-Challenge (401) erhalten oder TOKEN_INVALID_REQUEST, wenn Basic-Zugangsdaten angegeben wurden.

Client-Credentials-Tokens werden serverseitig mit Ihrem Auth Key/Auth Secret erstellt. Wenn Sie die Token-Erstellung über eine Benutzeroberfläche anbieten, rufen Sie /token von Ihrem Backend aus auf (niemals direkt aus dem Browser).

Gekündigte Workspaces können keine neuen Bearer-Tokens erstellen. Verwenden Sie für Endpunkte, deren Dokumentation Lesezugriffe nach der Kündigung ausdrücklich erlaubt, stattdessen die Anleitung für signierte Lesezugriffe mit einem vorhandenen aktiven Auth Key. Für die Abrechnung gibt es eine eigene Anleitung für signierte Abrechnungsanfragen.

Anfragen müssen application/x-www-form-urlencoded verwenden; der Grant client_credentials erfordert außerdem HTTP-Basic-Authentifizierung:

Setzen Sie in einer vertrauenswürdigen serverseitigen Shell mit curl und jq die Variablen TRANSLOADIT_KEY und TRANSLOADIT_SECRET auf die Werte Ihres Auth Keys und Ihres Auth Secrets. Halten Sie sowohl die Zugangsdaten als auch das daraus resultierende Token geheim; führen Sie diese Einrichtung niemals in Browsercode aus.

Dieses Beispiel fordert Lese- und Schreibzugriff auf Assemblies an und speichert das zurückgegebene access_token als TRANSLOADIT_TOKEN für nachfolgende Anfragen in derselben Shell. Verwenden Sie für einen anderen Endpunkt stattdessen die dort aufgeführten Scopes; der Auth Key muss diese bereits gewähren. Endpunkte, die über einen Auth Key oder ein Bearer-Token authentifiziert werden, enthalten in ihren Anfragebeispielen die entsprechende Token-Einrichtung.

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

Für die folgenden grant_type-Werte ist HTTP-Basic-Authentifizierung mit Ihrem Auth Key und Ihrem Auth Secret erforderlich: client_credentials. Andere unterstützte Werte benötigen keine Kontozugangsdaten. Senden Sie für diese Anfragen keinen Authorization-Header; der für den jeweiligen Grant spezifische Nachweis ist weiterhin erforderlich.

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

Die folgenden Felder dürfen höchstens einmal gesendet werden: aud, client_assertion, client_assertion_type, client_id, code, code_verifier, grant_type, redirect_uri, refresh_token, resource, scope.

Verwendung des Tokens

Übergeben Sie das Token bei API-Anfragen als Authorization: Bearer <access_token>. Wenn eine Anfrage mit einem gültigen Bearer-Token authentifiziert wird, betrachtet API2 Signature Authentication als erfüllt und überspringt die Signaturvalidierung. Signature Authentication wird nur bei Anfragen mit Auth Key/Auth Secret durchgesetzt. Scope-Prüfungen gelten weiterhin. Die standardmäßige Zielgruppe api2 wird von regulären API2-Endpunkten akzeptiert und ist standardmäßig 21.600 Sekunden lang gültig. Die Zielgruppe mcp wird vom MCP-Server akzeptiert, der sie mit Dienstzugangsdaten an API2 weiterleitet; sie wird von regulären API2-Endpunkten abgelehnt, wenn sie direkt vorgelegt wird, und ist standardmäßig 604.800 Sekunden lang gültig. Betrachten Sie den Wert expires_in in der Antwort als maßgeblich.