Authentifizierung

Auth Keys

Bei Multipart-Anfragen zur Erstellung einer Assembly, die mit einem Auth Key authentifiziert werden, fügen Sie ein auth-Objekt in das JSON-codierte Formularfeld params ein. Der kleinste solche params-Wert ist unten dargestellt.

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

Das Feld key verweist auf den Auth Key, der Ihrem Transloadit-Workspace zugeordnet ist und den Sie auf der Seite Zugangsdaten finden. Das obige Beispiel 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 ihrer 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 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 weder eine separate Signatur noch eine separate Ablaufzeit.

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.

Wenn Signature Authentication aktiviert ist, wird das Auth Secret Ihres Workspaces (das Sie neben Ihrem Auth Key auf der Seite Zugangsdaten finden) als Schlüssel für einen HMAC verwendet, der über die exakten Bytes des serialisierten params-Werts berechnet wird. Dieser Wert enthält sowohl einen key (Ihren Auth Key, wie zuvor erwähnt) als auch einen Parameter expires, einen Zeitstempel in der nahen Zukunft, der als Ablaufdatum für die Anfrage dient.

Zum Erstellen von Assemblies mit Transloadit könnte Ihr Backend eine Signatur berechnen, die nur bestimmte Parameter, authentifizierte Benutzer und einen Zeitraum abdeckt, die es als zulässige Nutzung einstuft. Beispielsweise würde es sich weigern, eine Signatur für Benutzer zu erzeugen, die nicht angemeldet sind. Sie könnten hier serverseitig beliebige Geschäftslogik verwenden, um zu entscheiden, ob Sie eine Signatur ausgeben oder nicht. Transloadit kann eine korrekte Signatur für die Payload 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. Klicken Sie auf die Schaltfläche Speichern.

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

So erzeugen Sie Signaturen

Wie sieht das nun konkret aus?

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

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

auth.key in diesem Beispiel ist der Auth Key aus den 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 Payload, die durch unsere Signatur geschützt ist. Wenn jemand es ändern würde, würde Transloadit die Anfrage ablehnen, da die Signatur nicht mehr übereinstimmt. Sie haben eine andere Payload signiert als diejenige, die wir erhalten haben. Wenn die Signatur übereinstimmt, vergleichen wir natürlich das Datum und lehnen die Anfrage gegebenenfalls wie vorgegeben ab. Dadurch wird es für Dritte, die an diese Payload gelangt sind, sehr schwer, Anfragen unbegrenzt zu wiederholen. Denn obwohl unser mit A+ bewertetes HTTPS bereits erheblich dazu beitragen sollte, dies zu verhindern, lässt sich der Browser-Cache möglicherweise leichter ausspähen.

Die Eigenschaft expires muss einen Zeitstempel in der (nahen) Zukunft enthalten. Verwenden Sie für das Datum das ISO-8601-Format (YYYY-MM-DDTHH:mm:ss.sssZ) und stellen Sie sicher, 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. Serialisieren Sie im Frontend das obige JavaScript-Objekt als JSON-String und senden Sie diesen an Ihr Backend.
2. Berechnen Sie im Backend eine RFC-6234-konforme⁠ hexadezimale HMAC-Signatur über den String, mit Ihrem Auth Secret als Schlüssel und dem Algorithmus, der in 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 String signature den Algorithmusnamen in Kleinbuchstaben voran. Der Standardalgorithmus verwendet beispielsweise sha384:<HMAC-signature>. Sie können diesen String an Ihr Frontend senden (sofern Sie die entsprechenden Prüfungen durchgeführt haben, um sicherzustellen, dass es sich um eine echte Anfrage Ihres Frontends handelt).
3. Fügen Sie im Frontend Ihrer Anfrage ein Multipart-POST-Feld signature hinzu, das diesen Wert enthält (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. Wenn die Signaturen voneinander abweichen, antworten unsere Server mit INVALID_SIGNATURE.

Zusammengefasst läuft der Vorgang wie folgt ab:

1. Erzeugen Sie eine JSON-Payload, die als Feld params an Transloadit gesendet werden soll.
2. Berechnen Sie eine Signatur anhand des Inhalts der Payload und verwenden Sie dabei Ihr Auth Secret als Schlüssel.
3. Senden Sie die Anfrage an Transloadit und übergeben Sie die Signatur im Feld signature
4. Transloadit berechnet dieselbe Signatur anhand des Auth Secrets Ihres Kontos und des Inhalts der Payload.
5. Wenn die Signaturen übereinstimmen, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet. Andernfalls wird die Anfrage abgelehnt und ein Fehler mit dem Code INVALID_SIGNATURE zurückgegeben.

So kann Transloadit den Aufrufer authentifizieren und die Integrität von params überprü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 gründlich getestet sind.

Beispielcode für verschiedene Sprachen

Die folgenden Beispiele zeigen, wie Sie Assemblies mit unseren offiziellen SDKs erstellen. Die SDKs übernehmen die gesamte Signaturerzeugung intern und machen die Integration dadurch einfacher und sicherer.

// 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 von Smart CDN aktiviert sein.

Die Erzeugung einer Smart CDN-Signatur muss im Backend erfolgen. Das Verfahren verwendet das Auth Secret, das vertraulich ist und Ihren Benutzern im Frontend nicht offengelegt werden darf.

Eine typische Smart CDN-URL hat die 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 mit den folgenden Schritten erzeugt:

1. Fügen Sie den Abfrageparameter exp hinzu, um einen Zeitpunkt in der Zukunft festzulegen, nach dem die Signatur von Smart CDN nicht mehr akzeptiert wird. Dies ist nützlich, um den Zugriff auf eine Datei zeitlich zu begrenzen. Der Ablaufzeitpunkt wird durch die Anzahl der Millisekunden seit der UNIX-Epoche dargestellt (Mitternacht zu Beginn des 1. Januar 1970, UTC). Obwohl dieser Parameter optional ist, empfehlen wir dringend, immer eine Ablaufzeit festzulegen. Beispielsweise ist eine Signatur mit exp=1722517200000 bis Do., 01 Aug 2024 13:00:00 GMT gültig.
2. Fügen Sie den Abfrageparameter auth_key hinzu, um den Auth Key festzulegen, der zu dem Auth Secret gehört, mit dem die Signatur erstellt wird. Wenn dieser Parameter nicht gesetzt ist, 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 das Setzen des Parameters auth_key können Sie Ihren Auth Key rotieren, ohne Ihre Benutzer zu unterbrechen. Daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel: auth_key=23c96d084c744219a2ce156772ec3211
3. Sortieren Sie die Abfrageparameter aufsteigend nach Schlüssel anhand von UTF-16-Codeeinheiten, entsprechend URLSearchParams.sort(). Die Sortierung sollte stabil sein, d. h., wenn ein Schlüssel mehrfach im Abfragestring vorkommt, sollten die zugehörigen Werte ihre relative Reihenfolge beibehalten. Beispielsweise wird h=100&f=png&f=jpg&auth_key=hello&exp=123 zu auth_key=hello&exp=123&f=png&f=jpg&h=100 sortiert.
4. Erstellen 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 Schrägstrich beginnt. Das Zeichen ? muss weggelassen werden, wenn [sorted-parameters] leer ist.
5. Berechnen Sie eine RFC-6234-konforme⁠ hexadezimale HMAC-Signatur über den zu signierenden String, mit Ihrem Auth Secret als Schlüssel und SHA256 als Hash-Algorithmus. Stellen Sie der hexadezimalen Signatur den Algorithmusnamen in Kleinbuchstaben und einen Doppelpunkt voran, also sha256:. Verwenden Sie für SHA256 beispielsweise sha256:[hmac-signature].
6. Hängen Sie die hexadezimale Signatur mit Präfix unter dem Abfrageparameter sig an die URL an, um die signierte Smart CDN-URL zu erhalten:

   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 bis zum Erreichen des Ablaufdatums an Ihr Frontend gesendet oder dort verwendet werden.

Sicherheit und Cache-Lebensdauer

Signierte Smart CDN-URLs sind nicht nur ein Mechanismus zur Zugriffskontrolle. Ihre Ablaufzeit bestimmt auch, wie lange ein neu erzeugtes Ergebnis zwischenspeicherbar bleiben kann.

• Kürzere exp-Werte verkleinern das Replay-Zeitfenster und verschärfen die Zugriffskontrolle.
• Längere exp-Werte erhöhen die Wiederverwendung des Caches, reduzieren den Arbeitsaufwand am Origin und senken im Allgemeinen die Latenz und das Codierungsvolumen.
• In der Praxis wird die effektive Cache-Lebensdauer einer signierten Smart CDN-Antwort durch die verbleibende Gültigkeitsdauer der Signatur begrenzt.

Die Abwägung ist damit klar:

• Höhere Sicherheitssensibilität: 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 nutzbar bleibt.

Wählen Sie das Ablaufzeitfenster entsprechend der Sensibilität des Inhalts 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. Verwenden Sie für hochsensible Inhalte ein wesentlich 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 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 dessen 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 gemacht.

Installieren Sie das SDK in einem vertrauenswürdigen serverseitigen Node.js-Projekt mit yarn add @transloadit/node. Setzen Sie TRANSLOADIT_KEY und TRANSLOADIT_SECRET und setzen Sie anschließend TRANSLOADIT_URL auf die vollständige HTTPS-URL, die auf der Endpunktseite angegeben ist. Ersetzen Sie dabei alle Pfadparameter durch die Werte Ihrer Ressource. Halten Sie beide Zugangsdaten, die signierte URL und die Antwort geheim. Führen Sie diese Einrichtung niemals in Browsercode aus.

Das SDK signiert params mit sha384, dem Standard für neue Auth Keys, und stellt die Ablaufzeit bereit. 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 diesen als zweites Argument an calcSignature. Platzieren Sie etwaige Endpunktfilter neben der nonce in dem Objekt, das Sie als erstes Argument übergeben. 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))

Einen 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 OAuth-2.1-Autorisierungsserver: Der Client ermittelt die Endpunkte, identifiziert sich, leitet Sie zur Anmeldung und Zustimmung an die Konsole weiter und erhält schließlich ein kurzlebiges Bearer-Token für die Audience mcp sowie ein Refresh-Token. Zu keinem Zeitpunkt verlässt ein Auth Secret Ihr Konto.

1. Ermittlung. 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 folgenden Endpunkte auflisten.
2. Client-Identifizierung. Stellen Sie entweder ein Client ID Metadata Document⁠ bereit: 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 sich einmalig über die dynamische Client-Registrierung nach RFC 7591⁠ 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 entweder HTTPS-URLs sein, die exakt abgeglichen werden, oder Loopback-URLs mit http://localhost / http://127.0.0.1, bei denen jeder Port akzeptiert wird. Token-Anfragen authentifizieren den Client mit none oder private_key_jwt, je nachdem, was sein Dokument aufführt (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 verwendete Methode: Sobald eine Anfrage für einen Grant eine client_assertion nach RFC 7523⁠ enthält, muss auch jede spätere Token- und Widerrufsanfrage dafür eine solche enthalten. Diese Assertion ist ein JWT, das mit einem Schlüssel aus der jwks_uri des Clients signiert ist (RS256 oder ES256), 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 diese Bereitstellung. Sie hat ein exp innerhalb von fünf Minuten und eine jti, die einmal pro Client und Region 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 Konsole 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 grant_type=authorization_code mit code, code_verifier, client_id und redirect_uri per POST 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 mit grant_type=refresh_token, refresh_token und client_id gibt ein neues Paar zurück und setzt das übermittelte Refresh-Token außer Kraft; Refresh-Tokens sind 30 Tage gültig, und die Wiederverwendung eines außer Kraft gesetzten Tokens widerruft die gesamte Abstammungskette.
5. Widerruf. Senden Sie token (ein Zugriffs- oder Refresh-Token) gemäß RFC 7009⁠ per POST an https://api2.transloadit.com/oauth/revoke oder widerrufen Sie die Verbindung in der Konsole.

Der Indikator resource (RFC 8707⁠) bestimmt, wofür das Token vorgesehen ist. resource=https://api2.transloadit.com/mcp (der Standard bei Auslassung) erstellt ein mcp-Token, das höchstens die sicheren MCP-Scopes (assemblies:write, assemblies:read, templates:read) enthält, eingeschränkt auf die Berechtigungen, die 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 enthält die angeforderten Scopes, eingeschränkt auf die Scopes des Auth Keys, oder alles, was der Schlüssel gewährt, wenn scope weggelassen wird. Ein Grant enthält jedoch niemals Berechtigungen zur Verwaltung von Auth Keys oder Template-Zugangsdaten (auth_keys:*, template_credentials:* oder die globalen Scopes read/write, die diese einschließen), sodass er keine dauerhaften Zugangsdaten erstellen oder offenlegen kann. Jeder andere resource-Wert führt zur Antwort invalid_target.

OAuth-Protokollfehler bei der Client-Registrierung, Autorisierung und beim Widerruf verwenden den standardmäßigen Antwort-Body mit error und error_description; Ratenbegrenzungen können RATE_LIMIT_REACHED zurückgeben.

Bei /token verwenden OAuth-Grant-Fehler für authorization_code und refresh_token den standardmäßigen Antwort-Body mit error und error_description. Ratenbegrenzungen geben RATE_LIMIT_REACHED (429) zurück, und unerwartete interne Fehler geben SERVER_500 (500) zurück. Fehlerhaft formatierte Anfragen, die abgelehnt werden, bevor der Grant identifiziert wird, können eine HTTP-Basic-Challenge (401) erhalten oder TOKEN_INVALID_REQUEST, wenn Basic-Zugangsdaten übermittelt wurden.

Bearer-Tokens (Client-Zugangsdaten)

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

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 Signaturprüfung. Signature Authentication wird nur bei Anfragen mit Schlüssel und Secret erzwungen. Scope- und Audience-Prüfungen gelten weiterhin. Die Audience mcp wird vom MCP-Server akzeptiert, der das Token mit Dienst-Zugangsdaten an API2 weiterleitet; bei direkter Übermittlung an reguläre API2-Endpunkte wird es abgelehnt. Sie können auth.key in params weglassen, aber die params-Hülle ist weiterhin für Endpunkte erforderlich, die sie erwarten.

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"}'

Automatische MCP-Authentifizierung 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 für jeden MCP-Server-Eintrag separat aktiviert werden:

{
  "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 unter /mcp/ verwenden.
• Die URL darf weder Zugangsdaten noch einen Abfragestring noch ein 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äufig gestellte Fragen

Fügt Transloadit seinen Anfragen Signaturen bei?

Transloadit signiert Webhook-Anfragen, damit Ihr Server ihre Authentizität überprüfen kann. Das Signieren von Webhooks ist vom HMAC getrennt, der an Transloadit gesendete API-Anfragen authentifiziert.

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

Abgesehen vom oben beschriebenen Server-zu-Server-Token-Austausch 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 Backend aus aufgerufen werden. Bei signierten Anfragen verbleibt das Secret in Ihrem Backend und wird als HMAC-Schlüssel verwendet. Dadurch wird verhindert, dass ein böswilliger Akteur eine signierte Anfrage abfängt und Anfragen an Ihr Konto fälscht. Bewahren Sie Ihr Auth Secret sicher auf, indem Sie ein System zur Verwaltung von Secrets Ihrer Wahl verwenden. Beispiele sind: Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ und Kubernetes Secrets⁠. Es gibt jedoch viele weitere, die je nach gewählter Backend-Plattform geeignet sein könnten.

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

Sie können die Reihenfolge der Schlüssel im Body beliebig wählen. Wichtig ist jedoch, dass die gewählte Reihenfolge mit der Reihenfolge bei der 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.