Authentifizierung
Auth Keys
Für Multipart-Anfragen zur Erstellung einer Assembly, die mit einem Auth Key authentifiziert werden, fügen Sie ein auth-Objekt
in das als JSON codierte Formularfeld params ein. Der kleinstmögliche solche params-Wert ist unten dargestellt.
{
"auth": {
"key": "23c96d084c744219a2ce156772ec3211"
}
}
Das Feld key bezieht sich auf den Auth Key, der Ihrem Transloadit Workspace zugeordnet ist und den Sie
auf der Seite Zugangsdaten finden. Das obige Objekt ist das minimale Authentifizierungsobjekt für
eine Assembly-Anfrage, die einen Auth Key verwendet. Andere Endpunkte und Authentifizierungsmethoden können
abweichende 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 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 keinen separaten Ablaufzeitpunkt.
Öffentliche Storage Builtin Templates bilden die Ausnahme: Sie können unsignierte Anfragen nur dann bedienen,
wenn jeder Storage-Import innerhalb eines deklarierten öffentlichen Präfixes bleibt. Dies autorisiert 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.
Wir empfehlen dringend, Signature Authentication zu aktivieren, wenn Sie mit unserer API arbeiten, insbesondere in nicht vertrauenswürdigen Umgebungen, in denen Benutzer möglicherweise auf Ihren Auth Key zugreifen können.
Ist Signature Authentication aktiviert, 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 exakte Serialisierung des params-Werts berechnet wird. Dieser Wert enthält sowohl einen key (Ihren
Auth Key, wie bereits erwähnt) als auch einen expires-Parameter, einen Zeitstempel in naher
Zukunft, der als Ablaufdatum der Anfrage dient.
Für das Erstellen von Assemblies mit Transloadit könnte Ihr Back-End eine Signatur berechnen, die nur bestimmte Parameter, authentifizierte Benutzer und einen Zeitraum abdeckt, den es als legitime Nutzung ansieht. Beispielsweise würde es sich weigern, eine Signatur für Benutzer zu erzeugen, die nicht angemeldet sind. Sie können hier beliebige Geschäftslogik auf der Serverseite einsetzen, um zu entscheiden, ob Sie eine Signatur ausgeben oder nicht. Transloadit kann eine korrekte Signatur für die Nutzlast 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:
- Öffnen Sie die Workspace-Einstellungen in Ihrem Konto.
- Aktivieren Sie im Abschnitt API-Einstellungen die Option Korrekte Signature verlangen.
- Warten Sie, bis das automatische Speichern abgeschlossen ist.
Gültige Bearer-Tokens umgehen Signaturanforderungen, einschließlich der Einstellungen für Workspace und Template; Token-Scopes und Audience-Beschränkungen gelten weiterhin. Diese Einstellungen fügen keine Authentifizierung für Capability-basierten Zugriff hinzu, etwa für URLs für den Assembly Status, den Abbruch oder fortsetzbare Uploads. Halten Sie Assembly IDs und Capability-URLs geheim und befolgen Sie die Authentifizierungshinweise des jeweiligen Endpunkts.
Die meisten SDKs für das Back-End verwenden automatisch Signature Authentication, wenn Sie Ihr Auth Secret angeben. Vielleicht ist diese Einführung also schon alles, was Sie wissen müssen. Wenn Sie Transloadit jedoch in nicht vertrauenswürdige Umgebungen integrieren, etwa in Browser (Uppy!), sollten Sie weiterlesen, um zu erfahren, wie Ihr Back-End diesen Signaturen bereitstellen kann.
So generieren Sie Signaturen
Wie sieht das Ganze also 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 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
Nutzlast, die durch unsere Signatur geschützt ist. Würde jemand es ändern, würde Transloadit die
Anfrage ablehnen, da die Signatur nicht mehr übereinstimmt. Sie haben dann eine andere Nutzlast signiert als die, die wir
erhalten haben. Stimmt die Signatur überein, vergleichen wir selbstverständlich das Datum und lehnen gegebenenfalls ab, wie
angewiesen. So wird es für Dritte, die in den Besitz dieser Nutzlast gelangt sind, sehr schwer, Anfragen unbegrenzt
zu wiederholen. Denn auch wenn unser mit A+ bewertetes HTTPS dies bereits weitgehend
verhindern sollte, ließe sich der Browser-Cache womöglich 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 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:
- Wandeln Sie im Front-End das obige JavaScript-Objekt in einen JSON-String um und senden Sie ihn an Ihr Back-End.
- Berechnen Sie im Back-End eine RFC-6234-konforme HMAC-Signatur
in Hexadezimaldarstellung über den String, mit Ihrem Auth Secret als Schlüssel und dem Algorithmus,
der im
signature_algoIhres Auth Keys konfiguriert ist, oder einem stärkeren Algorithmus. Neue Auth Keys verwenden standardmäßigsha384. Eine explizite Einstellung ist ein Minimum für Signaturen von API-Anfragen, vom schwächsten zum stärksten:sha1→sha256→sha384→sha512. Ein Schlüssel mitsha256akzeptiertsha256,sha384undsha512mit Präfix, lehnt abersha1und Digests ohne Präfix ab. Legacy-Signaturen ohne Präfix behalten ihre bestehenden Einschränkungen auf exakt einen Algorithmus; die Akzeptanz stärkerer Algorithmen erfordert ein Präfix. Ältere Auth Keys (Legacy) ohne konfigurierten Algorithmus akzeptierensha384,sha256odersha1. Dieses nicht festgelegte Verhalten bleibt unverändert und umfasstsha512nicht. Stellen Sie demsignature-String den Namen des Algorithmus in Kleinbuchstaben voran. Der Standardalgorithmus verwendet zum Beispielsha384:<HMAC-signature>. Diesen String können Sie 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). - Fügen Sie im Front-End Ihrer Anfrage ein Multipart-POST-Feld
signaturemit diesem Wert hinzu (z. B. über ein verstecktes Feld in einem HTML-Formular).
Wenn Ihre Implementierung eine template_id statt steps verwendet, müssen Sie keine Signatur
für die Instructions generieren, die Ihr Template enthält. Wir
sollten nur Kommunikationsnutzlasten signieren.
Wir empfehlen dringend, für jede Anfrage einen zufällig generierten Wert params.nonce
auf der obersten Ebene von params anzugeben. Dadurch unterscheiden sich unabhängig voneinander generierte Signaturen, und eine versehentliche
Wiederverwendung von Signaturen wird vermieden. Eine nonce macht Wiederholungsversuche nicht idempotent: Ein wiederholter Versuch einer Anfrage zur Erstellung einer Assembly
kann eine weitere Assembly erstellen. Kümmern Sie sich bei Bedarf in Ihrer Anwendung um die Deduplizierung von Wiederholungsversuchen.
Verwenden Sie signierte params nicht endpunktübergreifend wieder. Template-Lesezugriffe, das Auflisten von Auth Keys, das Auflisten von Template-Zugangsdaten
und Lesezugriffe auf Abrechnungsdaten lehnen Signaturen, die bereits für einen anderen Endpunkt erfasst oder
zur Erstellung einer Assembly verwendet wurden, mit SIGNATURE_REUSE_DETECTED ab. Generieren Sie für jede Anfrage neue signierte params.
Die vollständige Anfrage sollte etwa so 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 eine Signatur nach demselben
Verfahren und vergleichen die beiden Signaturen. Unterscheiden sich die Signaturen, antworten unsere Server
mit INVALID_SIGNATURE.
Zusammengefasst läuft der Prozess wie folgt ab:
- Erzeugen Sie eine JSON-Nutzlast, die als Feld
paramsan Transloadit gesendet wird. - Berechnen Sie anhand des Inhalts der Nutzlast eine Signatur und verwenden Sie dabei Ihr Auth Secret als Schlüssel.
- Senden Sie die Anfrage an Transloadit und übergeben Sie die Signatur im Feld
signature - Transloadit berechnet dieselbe Signatur mithilfe des Auth Secrets Ihres Kontos und des Inhalts der Nutzlast.
- Stimmen die Signaturen überein, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet.
Andernfalls wird die Anfrage abgelehnt und ein Fehler mit dem Code
INVALID_SIGNATUREzurü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 gut getestet sind.
Webhooks werden anders signiert als API-Anfragen.
Transloadit signiert den JSON-String im Formularfeld transloadit byte-genau mit
HMAC-SHA1 und dem jeweils zutreffenden Auth Secret. Das Feld signature enthält
den hexadezimalen Digest ohne Algorithmus-Präfix. Befolgen Sie die
Anleitung zur Webhook-Verifizierung, einschließlich der Auswahl des Auth Secrets,
statt die unten stehenden Signaturbeispiele für API-Anfragen zu verwenden.
Beispielcode für verschiedene Sprachen
Die folgenden Beispiele zeigen, wie Sie Assemblies mit unseren offiziellen SDKs erstellen. 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)
Wenn Sie eine Signatur separat berechnen müssen (z. B. für die Verwendung im Front-End), können Sie
calcSignature verwenden:
const { signature, params } = transloadit.calcSignature({
template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})
console.log(signature, params)
Wenn Sie die Details der Signaturimplementierung im Rohformat sehen möchten (z. B. um das Signieren in einer
Sprache zu implementieren, für die wir kein SDK haben), sehen Sie sich die oben verlinkten Quellcodes an. Die Signatur ist ein
RFC-6234-konformer HMAC-Hex-Digest, der über den
als JSON codierten params-String berechnet wird, mit Ihrem Auth Secret als
Schlüssel und einem Algorithmus, der mindestens so stark ist wie das im signature_algo Ihres Auth Keys konfigurierte Minimum. Neue Auth Keys verwenden standardmäßig
sha384. Stellen Sie der Signatur den Namen ihres Algorithmus in Kleinbuchstaben voran
(z. B. sha384:...).
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.
Um eine signierte Smart-CDN-URL zu generieren, verwenden Sie den für die Nutzung von Smart CDN vorgesehenen Auth Key von Ihrer
Seite „Zugangsdaten“. Smart-CDN-URLs erfordern sha256. Signaturen regulärer API-Anfragen
können einen Algorithmus mit Präfix verwenden, der mindestens so stark ist wie der signature_algo des Auth Keys; neue Auth Keys verwenden standardmäßig
sha384.
Legacy-Signaturen für Smart CDN auf Basis von s= und expires= sind veraltet. Neue Integrationen sollten
immer sig= mit exp= verwenden.
Die Erzeugung einer Smart-CDN-Signatur muss im Back-End erfolgen. Das Verfahren verwendet das Auth Secret, das vertraulich ist und Ihren Benutzern 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 mit den folgenden Schritten erzeugt:
- Fügen Sie den Query-Parameter
exphinzu, um einen Zeitpunkt in der Zukunft festzulegen, nach dem die Signatur vom Smart CDN nicht mehr akzeptiert wird. Das 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 aber dringend, immer eine Ablaufzeit festzulegen. Eine Signatur mitexp=1722517200000ist beispielsweise gültig bis Donnerstag, 1. August 2024, 13:00:00 GMT. - Fügen Sie den Query-Parameter
auth_keyhinzu, um den Auth Key anzugeben, 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 das Setzen des Parametersauth_keykönnen Sie Ihren Auth Key rotieren, ohne dass es für Ihre Benutzer zu Unterbrechungen kommt, daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel:auth_key=23c96d084c744219a2ce156772ec3211 - Sortieren Sie die Query-Parameter 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 Query-String vorkommt, sollten die zugehörigen Werte ihre relative Reihenfolge beibehalten. Zum Beispiel wirdh=100&f=png&f=jpg&auth_key=hello&exp=123sortiert zuauth_key=hello&exp=123&f=png&f=jpg&h=100. - Bilden Sie den zu signierenden String, indem Sie die Werte verketten:
Die Werte für
[your-workspace]/[template-name]/[file-path]?[sorted-parameters][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. - Berechnen Sie eine RFC-6234-konforme HMAC-Signatur in Hexadezimaldarstellung ü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 Beispielsha256:[hmac-signature]. - Hängen Sie die Hex-Signatur mit Präfix im Query-Parameter
sigan die URL an, wodurch Sie die signierte Smart-CDN-URL erhalten:Die Werte fürhttps://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature][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 Origin 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 Sicherheitsanforderungen: 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 der Inhalte und dem gewünschten Maß an Wiederverwendung des Caches. Für viele Anwendungsfälle mit Bildern und Vorschauen bietet ein moderates Ablaufzeitfenster eine gute Balance. Für hochsensible Inhalte verwenden Sie ein deutlich kürzeres.
Beispielcode
Nachfolgend finden Sie Beispiele in verschiedenen Sprachen für die Erzeugung 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 einer Kündigung
Gekündigte Workspaces können keine neuen Bearer-Tokens erstellen. Endpunkte, die den Zugriff nach einer 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. Dies stellt weder den Schreibzugriff wieder her, noch macht es 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 liefert den Ablaufzeitpunkt.
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
das Objekt, das als erstes Argument übergeben wird, neben die Nonce.
Das SDK ruft für diese Anleitung nicht /token 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 OAuth-2.1-Autorisierungsserver: Der Client ermittelt die Endpunkte, identifiziert
sich, leitet Sie zur Console weiter, wo 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.
- Erkennung. Der MCP-Server beantwortet nicht authentifizierte Anfragen mit
401und einem HeaderWWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". Dieses Dokument gemäß RFC 9728 nennthttps://api2.transloadit.comals Autorisierungsserver, dessen Metadaten gemäß RFC 8414 unterhttps://api2.transloadit.com/.well-known/oauth-authorization-serverdie unten aufgeführten Endpunkte auflisten. - Client-Identifizierung. Legen Sie entweder ein
Client ID Metadata Document vor:
eine HTTPS-URL, die die
client_idist und JSON mit derselbenclient_id, einemclient_nameund denredirect_urisausliefert. Oder registrieren Sie den Client einmalig über Dynamic Client Registration gemäß RFC 7591 unterhttps://api2.transloadit.com/oauth/register; Clients senden entweder nur ihreclient_id(token_endpoint_auth_method: "none", auch wenn dieses Feld weggelassen wird), authentifizieren sich mit einem Client-Secret (client_secret_basicoderclient_secret_post) oder authentifizieren sich mitprivate_key_jwtund einerjwks_uri. Die Antwort enthält eine opakeclient_id, bei den Secret-Methoden zusätzlich einclient_secret, das nur in dieser Antwort angezeigt wird. Redirect-URIs müssen HTTPS-URLs sein, die exakt abgeglichen werden, oder Loopback-URLshttp://localhost/http://127.0.0.1, die auf jedem Port abgeglichen werden. Ein mit Secret registrierter Client sendet dieses bei jeder Token- und Widerrufsanfrage, über HTTP Basic oder alsclient_idundclient_secretim Formular. Andere Token-Anfragen authentifizieren den Client mitnoneoderprivate_key_jwt, je nachdem, was sein Dokument auflistet (intoken_endpoint_auth_methods_supportedoder andernfalls alstoken_endpoint_auth_method) oder seine Registrierung deklariert. Die erste Token-Anfrage bindet den Grant an die von ihr verwendete Methode: Sobald eine Anfrage für einen Grant eineclient_assertiongemäß RFC 7523 enthält, muss auch jede spätere Token- und Widerrufsanfrage dafür eine enthalten. Diese Assertion ist ein JWT, signiert (RS256 oder ES256) mit einem Schlüssel aus derjwks_urides Clients, mit der Client-ID alsissundsub. Ihraudist eine konfigurierte Token-Endpunkt-URL oder deren Origin (ohne abschließenden Schrägstrich) für dieses Deployment. Sie hat einexpinnerhalb von fünf Minuten und einejti, die pro Client und Region einmal akzeptiert wird, solange die Assertion gültig bleibt. Verwenden Sie für jede Anfrage eine neuejti. - Zustimmung. Der Client öffnet
https://transloadit.com/c/oauth/authorizemitresponse_type=code, seinerclient_id,redirect_uri, einer PKCE-code_challenge(nurS256), optionalscopeundstatesowieresource=https://api2.transloadit.com/mcp. Sie melden sich an, wählen einen Workspace aus und stimmen zu; die Console leitet den Browser mitcode, Ihremstateundiss=https://api2.transloadit.comzurück. Der Code ist an den Client, die Redirect-URI, die Challenge und den Workspace gebunden und läuft nach 120 Sekunden ab. - Tokens. Der Client sendet
grant_type=authorization_codemitcode,code_verifier,client_idundredirect_uriper POST anhttps://api2.transloadit.com/tokenund erhält einaccess_token(standardmäßig gültig für 604.800 Sekunden, also 7 Tage), dessenscopeund einrefresh_token. Das Senden vongrant_type=refresh_tokenmitrefresh_tokenundclient_idliefert 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-Kette. Clients, die sich mit einem Client-Secret authentifizieren, erhalten stattdessen dasselbe Refresh-Token zurück, das ab dieser Aktualisierung weitere 30 Tage gültig ist. - Widerruf. Senden Sie
token(ein Access- oder Refresh-Token) per POST anhttps://api2.transloadit.com/oauth/revokegemäß RFC 7009, oder widerrufen Sie die Verbindung in der Console.
Der resource-Indikator (RFC 8707) bestimmt, wofür das
Token bestimmt ist. resource=https://api2.transloadit.com/mcp (der Standard, wenn der Parameter weggelassen wird) erzeugt ein mcp-Token, das
höchstens die sicheren MCP-Scopes (assemblies:write, assemblies:read, templates:read) enthält, 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) erzeugt ein api2-Token für Anwendungen, die die REST API direkt aufrufen,
etwa Integrationen mit Vercel Connect: 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, mit der Ausnahme, dass ein Grant niemals die Verwaltung von Auth Keys oder Template-Zugangsdaten umfasst
(auth_keys:*, template_credentials:* oder das globale read/write, das diese impliziert), 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.
Unter /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 einen
Auth Key und ein Auth Secret besitzen, tauschen diese über den OAuth-2.0-Grant client_credentials,
der direkt von der Transloadit API verarbeitet wird, gegen ein kurzlebiges Bearer-Token ein. Verwenden Sie dies, wenn es keinen Browser
für die Zustimmung gibt; 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 als Authorization: Bearer <access_token> in API-Anfragen. 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 für Anfragen mit Key und Secret erzwungen.
Scope- und Audience-Prüfungen gelten weiterhin. Die Audience mcp wird vom MCP-Server akzeptiert, der
sie mit Service-Zugangsdaten an API2 weiterleitet; wird sie regulären API2-Endpunkten direkt vorgelegt,
wird 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 erzeugen und einfügen (Auto-Auth). Dies muss pro MCP-Server-Eintrag ausdrücklich aktiviert werden (Opt-in):
{
"mcp_servers": [
{
"type": "http",
"url": "https://api2.transloadit.com/mcp",
"auth": "transloadit"
}
]
}
Verhalten:
- Wenn
auth: "transloadit"gesetzt ist und keinAuthorization-Header vorhanden ist, erzeugt API2 ein Token und fügtAuthorization: Bearer <token>ein. - Wenn
Authorizationbereits inmcp_servers[].headersangegeben 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
443und exakt den Pfad/mcpoder 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 erzeugte Token wird auf die Schnittmenge dieser sicheren MCP-Scopes und der Scopes des Auth Keys eingeschränkt; es erhält nie 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 deren Echtheit überprüfen kann. Das Signieren von Webhooks ist getrennt vom HMAC, mit dem an Transloadit gesendete API-Anfragen authentifiziert werden.
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
verbleibt das Secret in Ihrem Back-End und wird als HMAC-Schlüssel verwendet. Dies verhindert, dass ein böswilliger Akteur
eine signierte Anfrage abfängt und gefälschte Anfragen an Ihr Konto sendet. 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 jedoch noch viele
weitere, die je nach gewählter Back-End-Plattform geeignet sein können.
Stellen Sie sicher, dass Auth Secrets niemals Teil des Front-Ends Ihrer Anwendung sind oder Benutzern offengelegt werden.
In welcher Reihenfolge müssen die Schlüssel im Body stehen?
Die Reihenfolge der Schlüssel im Body können Sie beliebig 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.