Authentifizierung

Auth Keys

Bei multipart-Anfragen zum Erstellen einer Assembly, die mit einem Auth Key authentifiziert werden, fügen Sie ein auth-Objekt in das JSON-codierte Formularfeld params ein. Der kleinstmögliche solche params-Wert ist unten dargestellt.

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  }
}

Das Feld key verweist auf den Auth Key, der Ihrem Transloadit Workspace zugeordnet ist und auf der Seite Zugangsdaten zu finden ist. Das Obige ist das minimale Authentifizierungsobjekt für eine Assembly-Anfrage, die einen Auth Key verwendet. Andere Endpunkte und Authentifizierungsmethoden können andere Anfrageformate verwenden, wie in der jeweiligen Endpunktdokumentation und weiter unten beschrieben.

Assemblies, die /transloadit/import direkt oder über ein Template verwenden, erfordern entweder ein Bearer-Token oder signierte params mit einem in der Zukunft liegenden Zeitstempel in params.auth.expires. Dies gilt auch dann, wenn Signature Authentication für den Workspace deaktiviert ist. Ein Auth Key allein reicht nicht aus; mit einem Bearer-Token authentifizierte Anfragen benötigen keine separate Signatur und kein separates Ablaufdatum. Die öffentlichen Storage Builtin Templates bilden die Ausnahme: Öffentliche Storage Builtin Templates können unsignierte Anfragen nur dann bedienen, wenn jeder Storage-Import innerhalb eines deklarierten öffentlichen Präfixes bleibt. Dies erlaubt weder unsignierte Assemblies mit beliebigen Steps noch den Zugriff auf private Storage-Pfade.

Signature Authentication

Wir empfehlen, Signature Authentication für Ihr Konto zu aktivieren, insbesondere wenn Sie Transloadit aus einer nicht vertrauenswürdigen Umgebung heraus integrieren (etwa aus dem Browser mit Uppy⁠). Sie können Signature Authentication in Ihren Workspace-Einstellungen aktivieren.

Bei aktivierter Signature Authentication wird das Auth Secret Ihres Workspaces (zu finden neben Ihrem Auth Key auf der Seite Zugangsdaten) als Schlüssel für einen HMAC verwendet, der aus genau dem serialisierten params-Wert erzeugt wird. Dieser Wert enthält sowohl einen key (Ihren wie zuvor erwähnten Auth Key) als auch einen expires-Parameter, einen Zeitstempel in naher Zukunft, der als Ablaufdatum für die Anfrage dient.

Für das Erstellen von Assemblies mit Transloadit könnte Ihr Back-End eine Signatur berechnen, die nur bestimmte Parameter, authentifizierte Nutzer und einen Zeitraum abdeckt, den es als legitime Nutzung ansieht. Beispielsweise würde es sich weigern, eine Signatur für Nutzer zu erzeugen, die nicht angemeldet sind. Sie können hier serverseitig beliebige Geschäftslogik einsetzen, um zu entscheiden, ob Sie eine Signatur ausgeben oder nicht. Transloadit kann für die Nutzdaten eine korrekte Signatur verlangen, wenn sich eine API-Anfrage mit Ihrem Auth Key authentifiziert.

So verlangen Sie Signature Authentication für API-Anfragen, die mit Ihrem Auth Key authentifiziert werden:

1. Öffnen Sie die Workspace-Einstellungen in Ihrem Konto.
2. Aktivieren Sie im Abschnitt API-Einstellungen die Option Korrekte Signature verlangen.
3. Warten Sie, bis die automatische Speicherung abgeschlossen ist.

Gültige Bearer-Tokens umgehen Signaturanforderungen, einschließlich der Einstellungen auf Workspace- und Template-Ebene; die Scopes und Audience-Einschränkungen der Tokens gelten weiterhin. Diese Einstellungen fügen keine Authentifizierung für Capability-basierten Zugriff hinzu, etwa für URLs zum Assembly-Status, zum Abbrechen oder für fortsetzbare Uploads. Halten Sie Assembly IDs und Capability-URLs geheim, und befolgen Sie die Authentifizierungshinweise des jeweiligen Endpunkts.

So erzeugen Sie Signaturen

Wie sieht das Ganze nun aus?

Das typische params-Feld beim Erstellen einer Assembly ohne Signature Authentication sieht wie folgt aus:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  },
  "steps": {
    // …
  }
}

Der auth.key in diesem Beispiel ist der Auth Key aus API-Zugangsdaten in Ihrem Konto.

Um diese Anfrage zu signieren, muss zusätzlich das Feld auth.expires hinzugefügt werden. Dadurch wird es Teil unserer Nutzdaten, die durch unsere Signatur geschützt sind. Würde jemand es ändern, würde Transloadit die Anfrage ablehnen, da die Signatur nicht mehr übereinstimmt. Sie haben dann andere Nutzdaten signiert als die, die wir erhalten haben. Stimmt die Signatur überein, vergleichen wir selbstverständlich das Datum und lehnen wie angewiesen ab. Auf diese Weise lassen sich Anfragen von Dritten, die in den Besitz dieser Nutzdaten gelangt sind, nur sehr schwer unbegrenzt wiederholen. Denn auch wenn unser mit A+ bewertetes HTTPS dies bereits weitgehend verhindern sollte, könnte der Browser-Cache leichter auszuspähen sein.

Die Eigenschaft expires muss einen Zeitstempel in der (nahen) Zukunft enthalten. Verwenden Sie für das Datum das Format ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) und achten Sie darauf, dass UTC als Zeitzone verwendet wird. Zum Beispiel:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211",
    "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP"
  },
  "steps": {
    // …
  }
}

So berechnen Sie die Signatur für diese Anfrage:

1. Wandeln Sie in Ihrem Front-End das obige JavaScript-Objekt in einen JSON-String um und senden Sie ihn an Ihr Back-End.
2. Berechnen Sie in Ihrem Back-End eine RFC 6234-konforme⁠ HMAC-Hex-Signatur über den String, mit Ihrem Auth Secret als Schlüssel und dem Algorithmus, der im signature_algo Ihres Auth Keys konfiguriert ist. Neue Auth Keys verwenden standardmäßig sha384. Ältere Auth Keys ohne konfigurierten Algorithmus akzeptieren sha384, sha256 oder sha1. Stellen Sie dem signature-String den Namen des Algorithmus in Kleinbuchstaben voran. Beim Standardalgorithmus lautet er zum Beispiel sha384:<HMAC-signature>. Sie können diesen String an Ihr Front-End senden (sofern Sie die entsprechenden Prüfungen vorgenommen haben, um sicherzustellen, dass es sich um eine echte Anfrage Ihres Front-Ends handelt).
3. Fügen Sie in Ihrem Front-End Ihrer Anfrage ein multipart-POST-Feld signature mit diesem Wert hinzu (z. B. mit einem versteckten Feld in einem HTML-Formular).

Die vollständige Anfrage sollte ungefähr wie folgt aussehen:

{
  "params": {
    "auth": {
      "key": "23c96d084c744219a2ce156772ec3211",
      "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP",
    },
    "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
    "steps": {
      // …
    },
  },
  "signature": "sha384:YOUR_SIGNATURE",
}

Sobald Transloadit die Anfrage erhalten hat, erzeugen auch wir nach demselben Verfahren eine Signatur und vergleichen die beiden Signaturen. Unterscheiden sich die Signaturen, antworten unsere Server mit INVALID_SIGNATURE.

Zusammengefasst läuft der Prozess wie folgt ab:

1. Erzeugen Sie JSON-Nutzdaten, die als Feld params an Transloadit gesendet werden.
2. Berechnen Sie anhand des Inhalts der Nutzdaten eine Signatur, mit Ihrem Auth Secret als Schlüssel.
3. Senden Sie die Anfrage an Transloadit, wobei die Signatur im Feld signature übergeben wird
4. Transloadit berechnet dieselbe Signatur mit dem Auth Secret Ihres Kontos und dem Inhalt der Nutzdaten.
5. Stimmen die Signaturen überein, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet. Andernfalls wird die Anfrage abgelehnt, und es wird ein Fehler mit dem Code INVALID_SIGNATURE zurückgegeben.

So kann Transloadit den Aufrufer authentifizieren und die Integrität von params prüfen, da Dritte ohne Zugriff auf Ihr Auth Secret keine passende Signatur berechnen könnten. TLS authentifiziert Transloadit gegenüber Ihrem Client und schützt die Verbindung. Das Signieren von Webhooks ist ein separater Ablauf für Anfragen, die Transloadit an Ihre Server sendet.

Nachfolgend finden Sie einige Beispiele dafür, wie Sie eine POST-Anfrage zum Erstellen einer Assembly ausführen. Wir empfehlen dringend, eines unserer SDKs zu verwenden, die die Signaturerzeugung automatisch übernehmen und gut getestet sind.

Beispielcode für verschiedene Sprachen

Die folgenden Beispiele zeigen das Erstellen von Assemblies mit unseren offiziellen SDKs. Die SDKs übernehmen die gesamte Signaturerzeugung intern, was die Integration einfacher und sicherer macht.

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const response = await transloadit.createAssembly({
  params: {
    template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
    // your other params like notify_url, fields, etc.
  },
  waitForCompletion: true,
})

console.log(response)

const { signature, params } = transloadit.calcSignature({
  template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})

console.log(signature, params)

curl --fail-with-body -sS --location 'https://api2.transloadit.com/assemblies' \
  --form 'params={"auth":{"key":"23c96d084c744219a2ce156772ec3211","expires":"YOUR_FUTURE_ISO_8601_TIMESTAMP"},"template_id":"9cf67cbba601e37ee10c442b037e0"}' \
  --form 'signature=sha384:YOUR_SIGNATURE' \
  --form 'files=@/path/to/your/file.jpg'

Signierte Smart CDN URLs

Zum Signieren einer Smart CDN URL wird ein ähnliches Verfahren wie bei regulären API-Signaturen verwendet. Ein HMAC-Digest wird über einen String berechnet, der aus der Smart CDN URL abgeleitet wird, mit dem Auth Secret als Schlüssel. Damit die Signatur gültig ist, muss der verwendete Auth Key für die Nutzung mit Smart CDN aktiviert sein.

Die Erzeugung einer Smart CDN Signatur muss im Back-End erfolgen. Das Verfahren verwendet das Auth Secret, das vertraulich ist und Ihren Nutzern im Front-End nicht offengelegt werden darf.

Eine typische Smart CDN URL hat folgende Struktur:

https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]

• [your-workspace] ist der Name Ihres Transloadit Workspaces
• [template-name] ist der Name Ihres Templates
• [file-path] ist der Pfad zu der Datei, die Sie transformieren möchten
• [parameters] sind die gewünschten Transformationsparameter (z. B. h=100)

Eine signierte Smart CDN URL wird in folgenden Schritten erzeugt:

1. Fügen Sie den Query-Parameter exp hinzu, um einen Zeitpunkt in der Zukunft festzulegen, nach dem die Signatur vom Smart CDN nicht mehr akzeptiert wird. Dies ist nützlich, um den Zugriff auf eine Datei zeitlich zu begrenzen. Der Ablaufzeitpunkt wird als Anzahl der Millisekunden seit der UNIX-Epoche (Mitternacht zu Beginn des 1. Januar 1970, UTC) angegeben. Dieser Parameter ist zwar optional, wir empfehlen jedoch dringend, immer eine Ablaufzeit festzulegen. Eine Signatur mit exp=1722517200000 ist zum Beispiel bis Thu, 01 Aug 2024 13:00:00 GMT gültig.
2. Fügen Sie den Query-Parameter auth_key hinzu, um den Auth Key festzulegen, der zu dem Auth Secret gehört, mit dem die Signatur erstellt wird. Ist dieser Parameter nicht gesetzt, geht die API von Transloadit davon aus, dass das älteste für Smart CDN aktivierte Auth Key-Paar für die Signatur verwendet wurde. Durch Setzen des Parameters auth_key können Sie Ihren Auth Key rotieren, ohne Ihre Nutzer zu unterbrechen, daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel: auth_key=23c96d084c744219a2ce156772ec3211
3. Sortieren Sie die Query-Parameter nach Schlüssel in aufsteigender Reihenfolge anhand von UTF-16-Codeeinheiten, entsprechend URLSearchParams.sort(). Die Sortierung sollte stabil sein, d. h. wenn ein Schlüssel mehrfach im Query-String vorkommt, sollten die zugehörigen Werte ihre relative Reihenfolge beibehalten. Zum Beispiel wird h=100&f=png&f=jpg&auth_key=hello&exp=123 sortiert zu auth_key=hello&exp=123&f=png&f=jpg&h=100.
4. Bilden Sie den zu signierenden String, indem Sie die Werte verketten:

   [your-workspace]/[template-name]/[file-path]?[sorted-parameters]
   

   Die Werte für [your-workspace], [template-name] und [file-path] müssen URL-codiert sein, damit sie nur URL-sichere Zeichen enthalten. Beachten Sie, dass der String nicht mit einem führenden Schrägstrich beginnt. Das Zeichen ? muss weggelassen werden, wenn [sorted-parameters] leer ist.
5. Berechnen Sie eine RFC 6234-konforme⁠ HMAC-Hex-Signatur über den zu signierenden String, mit Ihrem Auth Secret als Schlüssel und SHA256 als Hash-Algorithmus. Stellen Sie der Hex-Signatur den Namen des Algorithmus in Kleinbuchstaben und einen Doppelpunkt voran, also sha256:. Für SHA256 verwenden Sie zum Beispiel sha256:[hmac-signature].
6. Hängen Sie die mit Präfix versehene Hex-Signatur im Query-Parameter sig an die URL an. So erhalten Sie die signierte Smart CDN URL:

   https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature]
   

   Die Werte für [your-workspace], [template-name] und [file-path] müssen URL-codiert sein, damit sie nur URL-sichere Zeichen enthalten. Diese signierte URL kann dann an Ihr Front-End gesendet oder dort verwendet werden, bis das Ablaufdatum erreicht ist.

Sicherheit und Cache-Lebensdauer

Signierte Smart CDN URLs sind nicht nur ein Mechanismus zur Zugriffskontrolle. Ihr Ablauf bestimmt auch, wie lange ein frisch erzeugtes Ergebnis zwischengespeichert werden darf.

• Kürzere exp-Werte verkleinern das Replay-Zeitfenster und verschärfen die Zugriffskontrolle.
• Längere exp-Werte erhöhen die Wiederverwendung des Caches, verringern die Arbeit am Ursprungsserver und senken im Allgemeinen Latenz und Encoding-Volumen.
• In der Praxis ist die effektive Cache-Lebensdauer einer signierten Smart CDN Antwort durch die verbleibende Lebensdauer der Signatur begrenzt.

Der Zielkonflikt ist also einfach:

• Höhere Sicherheitsempfindlichkeit: Verwenden Sie ein kürzeres exp, was auch eine kürzere effektive Cache-TTL bedeutet.
• Mehr Wiederverwendung des Caches und geringere Kosten: Verwenden Sie ein längeres exp, was auch bedeutet, dass die URL länger verwendbar bleibt.

Wählen Sie das Ablaufzeitfenster entsprechend der Sensibilität der Inhalte und dem gewünschten Maß an Wiederverwendung des Caches. Für viele Anwendungsfälle mit Bildern und Vorschauen bietet ein moderates Ablaufzeitfenster ein gutes Gleichgewicht. Für hochsensible Inhalte verwenden Sie ein deutlich kürzeres.

Beispielcode

Nachfolgend finden Sie Beispiele in verschiedenen Sprachen zum Erzeugen signierter Smart CDN URLs mit unseren SDKs.

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

const transloadit = new Transloadit({
  authKey: 'YOUR_TRANSLOADIT_KEY',
  authSecret: 'YOUR_TRANSLOADIT_SECRET',
})

const url = transloadit.getSignedSmartCDNUrl({
  workspace: 'YOUR_WORKSPACE',
  template: 'YOUR_TEMPLATE',
  input: 'image.png',
  urlParams: { height: 100, width: 100 },
})

console.log(url)

Lesezugriff nach der Kündigung

Gekündigte Workspaces können keine neuen Bearer-Tokens erstellen. Endpunkte, die den Zugriff nach der Kündigung ausdrücklich erlauben, verlinken auf diese Anleitung. Verwenden Sie einen vorhandenen aktiven Auth Key und das zugehörige Auth Secret; der Schlüssel muss weiterhin die für den Endpunkt aufgeführten Scopes gewähren. Dadurch wird weder der Schreibzugriff wiederhergestellt, noch werden andere Endpunkte nach der Kündigung verfügbar.

Installieren Sie in einem vertrauenswürdigen serverseitigen Node.js-Projekt das SDK mit yarn add @transloadit/node. Setzen Sie TRANSLOADIT_KEY und TRANSLOADIT_SECRET und anschließend TRANSLOADIT_URL auf die vollständige HTTPS-URL, die auf der Seite des Endpunkts angezeigt wird, wobei Sie alle Pfadparameter durch die Werte Ihrer Ressourcen ersetzen. Halten Sie beide Zugangsdaten, die signierte URL und die Antwort geheim. Führen Sie dieses Setup niemals in Browser-Code aus.

Das SDK signiert params mit sha384, dem Standard für neue Auth Keys, und setzt das Ablaufdatum. Das Beispiel fügt eine neue Nonce hinzu, um die Wiederverwendung von Signaturen zu vermeiden. Wenn Ihr Schlüssel einen anderen Signaturalgorithmus verwendet, übergeben Sie ihn als zweites Argument an calcSignature. Legen Sie etwaige Endpunktfilter in dem Objekt ab, das als erstes Argument übergeben wird, neben der Nonce. Das SDK ruft für diese Anleitung /token nicht auf.

Speichern Sie dies als read-api.mjs und führen Sie node read-api.mjs aus:

import { randomUUID } from 'node:crypto'

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_URL } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_URL) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_URL')
}
const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})
const { params, signature } = transloadit.calcSignature({ nonce: randomUUID() })
const url = new URL(TRANSLOADIT_URL)
url.searchParams.set('params', params)
url.searchParams.set('signature', signature)
const response = await fetch(url, { redirect: 'error' })
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const result = await response.json()
if (result.error) throw new Error(result.error)
console.log(JSON.stringify(result, null, 2))

MCP-Client per URL verbinden

Agent-Clients wie ChatGPT, Codex, Claude.ai, Claude Desktop, Claude Code und Cursor verbinden sich mit dem gehosteten MCP-Server unter https://api2.transloadit.com/mcp allein über diese URL. Die Transloadit API ist dafür ein Autorisierungsserver nach OAuth 2.1: Der Client ermittelt die Endpunkte, identifiziert sich, leitet Sie zur Console weiter, damit Sie sich anmelden und zustimmen, und erhält schließlich ein kurzlebiges Bearer-Token für die Audience mcp sowie ein Refresh-Token. Kein Auth Secret verlässt jemals Ihr Konto.

1. Endpunktermittlung. Der MCP-Server beantwortet nicht authentifizierte Anfragen mit 401 und einem Header WWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". Dieses RFC 9728⁠-Dokument nennt https://api2.transloadit.com als Autorisierungsserver, dessen RFC 8414⁠-Metadaten unter https://api2.transloadit.com/.well-known/oauth-authorization-server die unten aufgeführten Endpunkte auflisten.
2. Client-Identifikation. Legen Sie entweder ein Client ID Metadata Document⁠ vor: eine HTTPS-URL, die die client_id ist und JSON mit derselben client_id, einem client_name und den redirect_uris ausliefert. Oder registrieren Sie den Client einmalig über RFC 7591⁠ Dynamic Client Registration unter https://api2.transloadit.com/oauth/register; Clients senden entweder nur ihre client_id (token_endpoint_auth_method: "none") oder authentifizieren sich mit private_key_jwt und einer jwks_uri, und die Antwort enthält eine opake client_id. Redirect-URIs müssen HTTPS-URLs sein, die exakt abgeglichen werden, oder Loopback-URLs http://localhost / http://127.0.0.1, die auf jedem Port akzeptiert werden. Token-Anfragen authentifizieren den Client mit none oder private_key_jwt, je nachdem, was sein Dokument auflistet (in token_endpoint_auth_methods_supported oder andernfalls als token_endpoint_auth_method) oder seine Registrierung angibt. Die erste Token-Anfrage bindet den Grant an die von ihr verwendete Methode: Sobald eine Anfrage für einen Grant eine RFC 7523⁠-client_assertion enthält, muss auch jede spätere Token- und Widerrufsanfrage dafür eine enthalten. Diese Assertion ist ein JWT, das (mit RS256 oder ES256) mit einem Schlüssel aus der jwks_uri des Clients signiert ist, mit der Client-ID als iss und sub. Ihr aud ist eine konfigurierte Token-Endpunkt-URL oder deren Origin (ohne abschließenden Schrägstrich) für dieses Deployment. Sie hat ein exp innerhalb von fünf Minuten und eine jti, die pro Client und Region einmal akzeptiert wird, solange die Assertion gültig bleibt. Verwenden Sie für jede Anfrage eine neue jti.
3. Zustimmung. Der Client öffnet https://transloadit.com/c/oauth/authorize mit response_type=code, seiner client_id, redirect_uri, einer PKCE-code_challenge (nur S256), optional scope und state sowie resource=https://api2.transloadit.com/mcp. Sie melden sich an, wählen einen Workspace aus und stimmen zu; die Console leitet den Browser mit code, Ihrem state und iss=https://api2.transloadit.com zurück. Der Code ist an den Client, die Redirect-URI, die Challenge und den Workspace gebunden und läuft nach 120 Sekunden ab.
4. Tokens. Der Client sendet per POST grant_type=authorization_code mit code, code_verifier, client_id und redirect_uri an https://api2.transloadit.com/token und erhält ein access_token (standardmäßig 604.800 Sekunden, also 7 Tage, gültig), dessen scope und ein refresh_token. Ein POST von grant_type=refresh_token mit refresh_token und client_id liefert ein neues Paar und setzt das vorgelegte Refresh-Token außer Kraft; Refresh-Tokens sind 30 Tage gültig, und die Wiederverwendung eines außer Kraft gesetzten Tokens widerruft die gesamte Token-Linie.
5. Widerruf. Senden Sie per POST token (ein Access- oder Refresh-Token) an https://api2.transloadit.com/oauth/revoke gemäß RFC 7009⁠, oder widerrufen Sie die Verbindung in der Console.

Der resource-Indikator (RFC 8707⁠) entscheidet, wofür das Token bestimmt ist. resource=https://api2.transloadit.com/mcp (der Standard, wenn er weggelassen wird) erstellt ein mcp-Token, das höchstens die sicheren MCP-Scopes (assemblies:write, assemblies:read, templates:read) trägt, eingeschränkt auf das, was der Auth Key des Workspaces gewährt, und das nur der MCP-Server akzeptiert. resource=https://api2.transloadit.com (mit oder ohne abschließenden Schrägstrich) erstellt ein api2-Token für Anwendungen, die die REST API direkt aufrufen, etwa Vercel Connect⁠-Integrationen: Es trägt die angeforderten Scopes, eingeschränkt auf die Scopes des Auth Keys, oder alles, was der Schlüssel gewährt, wenn scope weggelassen wird, mit der Ausnahme, dass ein Grant niemals die Verwaltung von Auth Keys oder Template-Zugangsdaten umfasst (auth_keys:*, template_credentials:* oder die globalen read/write, die diese implizieren), sodass es keine dauerhaften Zugangsdaten erstellen oder offenlegen kann. Jede andere resource wird mit invalid_target beantwortet.

OAuth-Protokollfehler bei Client-Registrierung, Autorisierung und Widerruf verwenden den Standard-Body mit error und error_description; Rate Limits können RATE_LIMIT_REACHED zurückgeben.

Bei /token verwenden OAuth-Grant-Fehler für authorization_code und refresh_token den Standard-Body mit error und error_description. Rate Limits geben RATE_LIMIT_REACHED (429) zurück, und unerwartete interne Fehler geben SERVER_500 (500) zurück. Fehlerhafte Anfragen, die abgelehnt werden, bevor der Grant identifiziert ist, können eine HTTP-Basic-Challenge (401) erhalten oder TOKEN_INVALID_REQUEST, falls Basic-Zugangsdaten mitgesendet wurden.

Bearer-Tokens (Client Credentials)

CI-Jobs, Server und andere Headless-Clients, die über einen Auth Key und ein Auth Secret verfügen, tauschen diese gegen ein kurzlebiges Bearer-Token ein, und zwar mit dem client_credentials-Grant von OAuth 2.0, der direkt von der Transloadit API verarbeitet wird. Verwenden Sie dies, wenn kein Browser für die Zustimmung zur Verfügung steht; interaktive MCP-Clients sollten sich wie oben beschrieben per URL verbinden. Die vollständige Endpunktreferenz finden Sie in der /token-API-Dokumentation.

Das Token verwenden

Übergeben Sie das Token bei API-Anfragen als Authorization: Bearer <access_token>. Wenn eine Anfrage mit einem gültigen Bearer-Token authentifiziert ist, betrachtet API2 Signature Authentication als erfüllt und überspringt die Signaturprüfung. Signature Authentication wird nur bei Anfragen mit Key/Secret erzwungen. Prüfungen von Scope und Audience gelten weiterhin. Tokens mit der Audience mcp werden vom MCP-Server akzeptiert, der sie mit Dienst-Zugangsdaten an API2 weiterleitet; werden sie direkt regulären API2-Endpunkten vorgelegt, werden sie abgelehnt. Sie können auth.key in params weglassen, aber der params-Umschlag ist für Endpunkte, die ihn erwarten, weiterhin erforderlich.

curl --fail-with-body -sS --request POST \
  --url 'https://api2.transloadit.com/assemblies' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'params={"template_id":"YOUR_TEMPLATE_ID"}'

MCP-Auto-Auth für /ai/chat

Wenn Ihre /ai/chat-Steps einen von Transloadit gehosteten MCP-Server aufrufen, kann API2 automatisch ein kurzlebiges Bearer-Token erstellen und einfügen (Auto-Auth). Dies muss pro MCP-Server-Eintrag aktiviert werden (Opt-in):

{
  "mcp_servers": [
    {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "auth": "transloadit"
    }
  ]
}

Verhalten:

• Wenn auth: "transloadit" gesetzt ist und kein Authorization-Header vorhanden ist, erstellt API2 ein Token und fügt Authorization: Bearer <token> ein.
• Wenn Authorization bereits in mcp_servers[].headers angegeben ist, bleibt es unverändert.
• Auto-Auth funktioniert nur über HTTPS für von Transloadit verwaltete Apex-Hosts und Subdomains: transloadit.com, *.transloadit.com, transloadit.dev, *.transloadit.dev, transloadit.website, *.transloadit.website, transloadit.work, *.transloadit.work.
• Die URL muss Port 443 und exakt den Pfad /mcp oder einen Unterpfad unterhalb von /mcp/ verwenden.
• Die URL darf keine Zugangsdaten, keinen Query-String und kein Fragment enthalten.
• Der Auth Key muss mindestens einen dieser sicheren MCP-Scopes gewähren: assemblies:write, assemblies:read, templates:read.
• Das erstellte Token wird auf die Schnittmenge dieser sicheren MCP-Scopes und der Scopes des Auth Keys eingeschränkt; es erhält niemals einen Scope, den der Auth Key nicht gewährt.

Häufige Fragen

Fügt Transloadit seinen Anfragen Signaturen bei?

Transloadit signiert Webhook-Anfragen, damit Ihr Server ihre Echtheit prüfen kann. Das Signieren von Webhooks ist getrennt von dem HMAC, der an Transloadit gesendete API-Anfragen authentifiziert.

Warum kann ich mein Auth Secret nicht als Bearer-Token verwenden?

Abgesehen vom oben beschriebenen Token-Austausch zwischen Servern darf Ihr Auth Secret niemals an einen Client übertragen oder in API-Anfrageparameter aufgenommen werden. POST /token sendet es als HTTP-Basic-Passwort über HTTPS und darf nur von Ihrem Back-End aus aufgerufen werden. Bei signierten Anfragen bleibt das Secret in Ihrem Back-End und wird als HMAC-Schlüssel verwendet. Dies verhindert, dass ein Angreifer eine signierte Anfrage abfängt und Anfragen an Ihr Konto fälscht. Schützen Sie Ihr Auth Secret mit einem Secret-Management-System Ihrer Wahl. Beispiele sind: Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ und Kubernetes Secrets⁠, es gibt aber noch viele weitere, die je nach gewählter Back-End-Plattform geeignet sein könnten.

In welcher Reihenfolge müssen die Schlüssel im Body stehen?

Die Reihenfolge der Schlüssel im Body können Sie frei wählen. Wichtig ist jedoch, dass die gewählte Reihenfolge mit Ihrer Signaturerzeugung übereinstimmt. Der erzeugte Hash hängt vom Inhalt des JSON ab, und eine andere Reihenfolge erzeugt einen anderen Hash, sodass Ihre Anfrage abgelehnt wird.