Authentifizierung
Auth Keys
Fügen Sie bei mehrteiligen Anfragen zur Erstellung einer Assembly, die mit einem Auth Key authentifiziert werden, ein auth-Objekt
in das JSON-kodierte Formularfeld params ein. Der kleinstmögliche params-Wert dafür 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 zeigt 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 zukünftigen 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 Signature und keinen separaten Ablaufzeitpunkt.
Signature Authentication
Wir empfehlen, Signature Authentication für Ihr Konto zu aktivieren, insbesondere wenn Sie Transloadit aus einer nicht vertrauenswürdigen Umgebung integrieren (etwa aus dem Browser mit Uppy). Sie können Signature Authentication in Ihren Workspace-Einstellungen aktivieren.
Wir empfehlen dringend, Signature Authentication bei der Kommunikation mit unserer API zu aktivieren, insbesondere in nicht vertrauenswürdigen Umgebungen, in denen Benutzer möglicherweise auf Ihren Auth Key zugreifen können.
Wenn Signature Authentication aktiviert ist, 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 dem exakt serialisierten params-Wert generiert 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.
Für die Erstellung von Assemblies mit Transloadit könnte Ihr Back-End eine Signature berechnen, die nur bestimmte Parameter, authentifizierte Benutzer und einen Zeitraum abdeckt, die es als legitime Nutzung einstuft. Beispielsweise würde es sich weigern, eine Signature für Benutzer zu generieren, die nicht angemeldet sind. Sie können hier beliebige serverseitige Geschäftslogik verwenden, um zu entscheiden, ob Sie eine Signature ausgeben oder nicht. Transloadit kann eine korrekte Signature für die Nutzlast verlangen, wenn sich eine API-Anfrage mit Ihrem Auth Key authentifiziert.
So legen Sie fest, dass Signature Authentication für API-Anfragen erforderlich ist, die mit Ihrem Auth Key authentifiziert werden:
- Öffnen Sie die Workspace-Einstellungen in Ihrem Konto.
- Aktivieren Sie im Abschnitt „API-Einstellungen“ die Option Eine korrekte Signature verlangen.
- Klicken Sie auf die Schaltfläche „Speichern“.
Gültige Bearer-Tokens umgehen die Anforderungen an Signatures, einschließlich der Workspace- und Template-Einstellungen; Scope- und Audience-Beschränkungen gelten weiterhin. Diese Einstellungen ergänzen keine Authentifizierung für Capability-basierten Zugriff, etwa über 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 Back-End-SDKs verwenden automatisch Signature Authentication, wenn Sie Ihr Auth Secret angeben. Möglicherweise enthält diese Einführung also bereits alles, was Sie wissen müssen. Wenn Sie Transloadit jedoch in nicht vertrauenswürdige Umgebungen wie Browser integrieren (Uppy!), sollten Sie weiterlesen, um zu erfahren, wie Ihr Back-End dafür Signatures bereitstellen kann.
So generieren Sie Signatures
Wie sieht das Ganze nun 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 das zusätzliche Feld auth.expires hinzugefügt werden. Dadurch wird es Teil unserer
Nutzlast, die durch unsere Signature geschützt ist. Würde jemand es ändern, würde Transloadit
die Anfrage ablehnen, da die Signature nicht mehr übereinstimmt. Sie haben dann eine andere Nutzlast signiert als die, die wir
erhalten haben. Wenn die Signature übereinstimmt, prüfen wir natürlich das Datum und lehnen die Anfrage
entsprechend der Vorgabe ab. Dadurch wird es für Dritte, die in den Besitz dieser Nutzlast gelangt sind, sehr schwierig,
Anfragen unbegrenzt zu wiederholen. Denn obwohl unser mit A+ bewertetes HTTPS bereits viel 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 Signature für diese Anfrage:
- Serialisieren Sie in Ihrem Front-End das obige JavaScript-Objekt als JSON-Zeichenfolge und senden Sie diese an Ihr Back-End.
- Berechnen Sie in Ihrem Back-End eine RFC-6234-konforme HMAC-Signature
in Hexadezimaldarstellung über die Zeichenfolge, mit Ihrem Auth Secret als Schlüssel und dem Algorithmus,
der in
signature_algoIhres Auth Keys konfiguriert ist. Neue Auth Keys verwenden standardmäßigsha384. Ältere Auth Keys ohne konfigurierten Algorithmus akzeptierensha384,sha256odersha1. Stellen Sie der Zeichenfolgesignatureden Algorithmusnamen in Kleinbuchstaben voran. Der Standardalgorithmus verwendet beispielsweisesha384:<HMAC-signature>. Sie können diese Zeichenfolge an Ihr Front-End senden (sofern Sie die entsprechenden Prüfungen durchgeführt haben, um sicherzustellen, dass es sich um eine echte Anfrage Ihres Front-Ends handelt). - Fügen Sie in Ihrem Front-End Ihrer Anfrage ein mehrteiliges POST-Feld
signaturehinzu, das diesen Wert enthält (z. B. mit einem versteckten Feld in einem HTML-Formular).
Wenn Ihre Implementierung eine template_id anstelle von steps verwendet, müssen Sie keine
Signature für die Instructions generieren, die Ihr Template enthält. Wir
sollten nur die bei der Kommunikation übertragenen Nutzlasten signieren.
Wir empfehlen dringend, für jede Anfrage einen zufällig generierten Wert params.nonce
auf der obersten Ebene von params einzufügen. Dadurch unterscheiden sich unabhängig generierte Signatures voneinander, und eine versehentliche
Wiederverwendung von Signatures wird vermieden. Eine nonce macht Wiederholungsversuche nicht idempotent: Das Wiederholen einer Anfrage zur Erstellung einer Assembly
kann eine weitere Assembly erstellen. Sorgen Sie bei Bedarf in Ihrer Anwendung für die Deduplizierung von Wiederholungsversuchen.
Verwenden Sie signierte params nicht für verschiedene Endpunkte wieder. Lesezugriffe auf Templates, das Auflisten von Auth Keys, das Auflisten von Template-Zugangsdaten
und Lesezugriffe auf Abrechnungsdaten lehnen Signatures, die bereits für einen anderen Endpunkt registriert oder
zum Erstellen einer Assembly verwendet wurden, mit SIGNATURE_REUSE_DETECTED ab. Generieren Sie für jede Anfrage neue signierte params.
Die vollständige Anfrage sollte ähnlich wie das folgende Beispiel aussehen:
{
"params": {
"auth": {
"key": "23c96d084c744219a2ce156772ec3211",
"expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP",
},
"nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
"steps": {
// …
},
},
"signature": "sha384:YOUR_SIGNATURE",
}
Nachdem Transloadit die Anfrage erhalten hat, generieren auch wir nach demselben
Verfahren eine Signature und vergleichen die beiden Signatures. Wenn sie unterschiedlich sind, antworten unsere Server
mit INVALID_SIGNATURE.
Zusammengefasst läuft der Vorgang wie folgt ab:
- Generieren Sie eine JSON-Nutzlast, die als Feld
paramsan Transloadit gesendet werden soll. - Berechnen Sie eine Signature anhand des Inhalts der Nutzlast und verwenden Sie dabei Ihr Auth Secret als Schlüssel.
- Senden Sie die Anfrage an Transloadit und übergeben Sie die Signature im Feld
signature - Transloadit berechnet dieselbe Signature mit dem Auth Secret Ihres Kontos und dem Inhalt der Nutzlast.
- Wenn die Signatures übereinstimmen, wird die Anfrage zugelassen und eine entsprechende Antwort gesendet.
Andernfalls wird die Anfrage abgelehnt und ein Fehler mit dem Code
INVALID_SIGNATUREzurückgegeben.
Dadurch kann Transloadit den Aufrufer authentifizieren und die Integrität von params überprüfen, da Dritte
keine passende Signature ohne Zugriff auf Ihr Auth Secret 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 für POST-Anfragen zum Erstellen einer Assembly. Wir empfehlen dringend, eines unserer SDKs zu verwenden, die die Generierung von Signatures automatisch übernehmen und gründlich getestet sind.
Webhooks werden anders signiert als API-Anfragen.
Transloadit signiert die exakte JSON-Zeichenfolge im Formularfeld transloadit mit
HMAC-SHA1 und dem zutreffenden Auth Secret. Das Feld signature enthält
den hexadezimalen Digest ohne Algorithmuspräfix. Befolgen Sie die
Anleitung zur Webhook-Verifizierung, einschließlich der Hinweise zur Auswahl des Auth Secrets,
anstatt die folgenden Beispiele zum Signieren von API-Anfragen zu verwenden.
Beispielcode für verschiedene Sprachen
Die folgenden Beispiele zeigen, wie Sie mit unseren offiziellen SDKs Assemblies erstellen. Die SDKs übernehmen die gesamte Generierung von Signatures 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 Signature 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 sich die direkten Implementierungsdetails für Signatures ansehen möchten (z. B. um das Signieren in einer
Sprache zu implementieren, für die wir kein SDK anbieten), folgen Sie den obigen Quellcode-Links. Die Signature ist ein
RFC-6234-konformer HMAC-Digest in Hexadezimaldarstellung, der über die
JSON-kodierte params-Zeichenfolge berechnet wird. Dabei werden Ihr Auth Secret als
Schlüssel und der in signature_algo Ihres Auth Keys konfigurierte Algorithmus verwendet. Neue Auth Keys verwenden standardmäßig
sha384. Stellen Sie der Signature den Algorithmusnamen 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 für reguläre API-Signatures verwendet. Ein HMAC-Digest wird über eine Zeichenfolge berechnet, die aus der Smart CDN-URL abgeleitet wird, mit dem Auth Secret als Schlüssel. Damit die Signature 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 Auth Key, der auf Ihrer
Zugangsdaten-Seite für die Nutzung von Smart CDN vorgesehen ist. Smart CDN-URLs erfordern sha256. Signatures für reguläre API-Anfragen
verwenden den in signature_algo des Auth Keys konfigurierten Algorithmus; neue Auth Keys verwenden standardmäßig
sha384.
Ältere Smart CDN-Signatures auf Basis von s= und expires= sind veraltet. Neue Integrationen sollten
immer sig= mit exp= verwenden.
Die Generierung einer Smart CDN-Signature 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 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 zur 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 generiert:
- Fügen Sie den Abfrageparameter
exphinzu, um einen zukünftigen Zeitpunkt festzulegen, nach dem die Signature von 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 dargestellt (Mitternacht zu Beginn des 1. Januar 1970, UTC). Dieser Parameter ist zwar optional, wir empfehlen jedoch dringend, immer einen Ablaufzeitpunkt festzulegen. Eine Signature mitexp=1722517200000ist beispielsweise bis Do, 01 Aug 2024 13:00:00 GMT gültig. - Fügen Sie den Abfrageparameter
auth_keyhinzu, um den Auth Key festzulegen, der zu dem Auth Secret gehört, das zum Erstellen der Signature verwendet 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 Signature verwendet wurde. Durch das Setzen des Parametersauth_keykönnen Sie Ihren Auth Key rotieren, ohne die Nutzung durch Ihre Benutzer zu unterbrechen. Daher empfehlen wir dringend, ihn zu setzen. Zum Beispiel:auth_key=23c96d084c744219a2ce156772ec3211 - Sortieren Sie die Abfrageparameter anhand ihrer Schlüssel in aufsteigender Reihenfolge nach UTF-16-Codeeinheiten, entsprechend
URLSearchParams.sort(). Die Sortierung sollte stabil sein, d. h., wenn ein Schlüssel mehrfach in der Abfragezeichenfolge vorkommt, sollten die zugehörigen Werte ihre relative Reihenfolge beibehalten. Beispielsweise wirdh=100&f=png&f=jpg&auth_key=hello&exp=123zuauth_key=hello&exp=123&f=png&f=jpg&h=100sortiert. - Erstellen Sie die zu signierende Zeichenfolge, 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-kodiert sein, damit sie nur URL-sichere Zeichen enthalten. Beachten Sie, dass die Zeichenfolge 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-Signature in Hexadezimaldarstellung über die
zu signierende Zeichenfolge, mit Ihrem Auth Secret als Schlüssel und SHA256 als Hash-Algorithmus.
Stellen Sie der hexadezimalen Signature den Algorithmusnamen in Kleinbuchstaben und einen Doppelpunkt voran, also
sha256:. Verwenden Sie für SHA256 beispielsweisesha256:[hmac-signature]. - Hängen Sie die hexadezimale Signature mit Präfix unter dem Abfrageparameter
sigan die URL an. So erhalten Sie die signierte Smart CDN-URL: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-kodiert 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 dienen nicht nur der Zugriffskontrolle. Ihr Ablaufzeitpunkt bestimmt auch, wie lange ein neu generiertes Ergebnis cachebar bleiben darf.
- Kürzere
exp-Werte reduzieren das Replay-Zeitfenster und verschärfen die Zugriffskontrolle. - Längere
exp-Werte erhöhen die Wiederverwendung des Caches, reduzieren den Aufwand am Origin und verringern im Allgemeinen die Latenz und das Kodierungsvolumen. - In der Praxis wird die effektive Cache-Lebensdauer einer signierten Smart CDN-Antwort durch die verbleibende Gültigkeitsdauer der Signature begrenzt.
Daraus ergibt sich eine klare Abwägung:
- Höhere Sicherheitsanforderungen: Verwenden Sie einen kürzeren
exp-Wert, was auch eine kürzere effektive Cache-TTL bedeutet. - Mehr Wiederverwendung des Caches und geringere Kosten: Verwenden Sie einen längeren
exp-Wert, wodurch auch 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 ein gutes Gleichgewicht. Verwenden Sie für hochsensible Inhalte ein deutlich kürzeres.
Beispielcode
Nachfolgend finden Sie Beispiele in verschiedenen Sprachen zur Generierung 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 einer Kündigung ausdrücklich erlauben, verlinken auf diese Anleitung. Verwenden Sie einen bestehenden aktiven Auth Key und dessen Auth Secret; der Auth Key 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 das SDK in einem vertrauenswürdigen serverseitigen Node.js-Projekt 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 Endpunktseite angegeben ist. Ersetzen Sie dabei alle Pfadparameter durch die Werte Ihrer Ressourcen.
Halten Sie beide Zugangsdaten, die signierte URL und die Antwort geheim. Führen Sie diese Einrichtung 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 Signatures zu vermeiden. Wenn Ihr Auth Key einen anderen Signature-Algorithmus
verwendet, übergeben Sie ihn als zweites Argument an calcSignature. Fügen Sie alle Endpunktfilter
neben der Nonce in das Objekt ein, das als erstes Argument übergeben wird.
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))
Bearer-Tokens (Client-Zugangsdaten)
Wenn Sie ein kurzlebiges Token für Server-zu-Server- oder Headless-Clients benötigen, können Sie Ihren
Auth Key und Ihr Auth Secret gegen ein Bearer-Token eintauschen. Dies entspricht einem
client_credentials-Ablauf nach OAuth 2.0, wird jedoch direkt von der Transloadit-API abgewickelt. Die vollständige Endpunktreferenz
finden Sie in der /token-API-Dokumentation.
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 die
Signature Authentication als erfüllt und
überspringt die Validierung der Signature. Signature Authentication wird nur bei Anfragen mit Auth Key und Auth Secret durchgesetzt.
Scope- und Audience-Prüfungen gelten weiterhin. Die Audience mcp wird vom MCP-Server akzeptiert und
von regulären API2-Endpunkten abgelehnt. Sie können auth.key in params weglassen, aber die params-Hülle
ist für Endpunkte, die sie 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"}'
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 ausstellen und einfügen (automatische Authentifizierung). Dies muss für jeden MCP-Servereintrag ausdrücklich aktiviert werden:
{
"mcp_servers": [
{
"type": "http",
"url": "https://api2.transloadit.com/mcp",
"auth": "transloadit"
}
]
}
Verhalten:
- Wenn
auth: "transloadit"gesetzt ist und keinAuthorization-Header vorhanden ist, stellt API2 ein Token aus und fügtAuthorization: Bearer <token>ein. - Wenn
Authorizationbereits inmcp_servers[].headersangegeben ist, bleibt es unverändert. - Die automatische Authentifizierung 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 unter/mcp/verwenden. - Die URL darf keine Zugangsdaten, keine Abfragezeichenfolge und kein Fragment enthalten.
- Der Auth Key muss mindestens einen dieser sicheren MCP-Scopes gewähren:
assemblies:write,assemblies:read,templates:read. - Das ausgestellte Token wird auf die Schnittmenge dieser sicheren MCP-Scopes und der Scopes des Auth Keys beschränkt; es erhält niemals einen Scope, den der Auth Key nicht gewährt.
Häufig gestellte Fragen
Fügt Transloadit seinen Anfragen Signatures bei?
Transloadit signiert Webhook-Anfragen, damit Ihr Server deren Authentizität überprüfen kann. Das Signieren von Webhooks ist vom HMAC getrennt, der API-Anfragen authentifiziert, die an Transloadit gesendet werden.
Warum kann ich mein Auth Secret nicht als Bearer-Token verwenden?
Abgesehen vom oben beschriebenen Server-zu-Server-Tokenaustausch darf Ihr Auth Secret
niemals an einen Client übertragen oder in API-Anfrageparametern enthalten sein. 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. Dadurch wird verhindert, dass ein böswilliger Akteur
eine signierte Anfrage abfängt und gefälschte Anfragen an Ihr Konto stellt. Schützen Sie Ihr Auth Secret mit
einem System zur Verwaltung von Secrets Ihrer Wahl. Beispiele sind: Vault,
AWS Secrets Manager,
GCP Secret Manager und
Kubernetes Secrets. Es gibt jedoch viele
weitere, die je nach Ihrer bevorzugten Back-End-Plattform geeignet sein könnten.
Sie sollten sicherstellen, 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 ist frei wählbar. Wichtig ist jedoch, dass die gewählte Reihenfolge mit der Generierung Ihrer Signature übereinstimmt. Der generierte Hash hängt vom Inhalt des JSON ab. Eine andere Reihenfolge erzeugt einen anderen Hash, was dazu führt, dass Ihre Anfrage abgelehnt wird.