Authentification

Auth Keys

Pour les requêtes multipart de création d’Assembly authentifiées avec une Auth Key, incluez un objet auth dans le champ de formulaire params encodé en JSON. La plus petite valeur params de ce type est présentée ci-dessous.

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

Le champ key fait référence à l’Auth Key associée à votre Workspace Transloadit, disponible sur la page Informations d’identification. L’exemple ci-dessus constitue l’objet d’authentification minimal pour une requête d’Assembly utilisant une Auth Key. D’autres points de terminaison et méthodes d’authentification peuvent utiliser des formats de requête différents, comme indiqué dans leur documentation et ci-dessous.

Les Assemblies qui utilisent /transloadit/import, directement ou par l’intermédiaire d’un Template, nécessitent soit un jeton porteur, soit des params signés avec un horodatage params.auth.expires situé dans le futur. Cela s’applique même lorsque Signature Authentication est désactivée pour le Workspace. Une Auth Key seule ne suffit pas ; les requêtes authentifiées par jeton porteur n’ont pas besoin d’une signature ou d’une expiration distincte. Les Builtin Templates publics pour Storage font exception : ils peuvent traiter des requêtes non signées uniquement lorsque chaque importation depuis Storage reste dans les limites d’un préfixe déclaré public. Cela n’autorise pas les Assemblies non signées comportant des Steps arbitraires ni l’accès aux chemins privés de Storage.

Signature Authentication

Nous vous recommandons d’activer Signature Authentication sur votre compte, en particulier si vous intégrez Transloadit depuis un environnement non fiable (par exemple depuis le navigateur avec Uppy⁠). Vous pouvez activer Signature Authentication dans les Paramètres du Workspace.

Lorsque Signature Authentication est activée, l’Auth Secret de votre Workspace (disponible à côté de votre Auth Key sur la page Informations d’identification) est alors utilisé comme clé pour un HMAC généré à partir de la valeur params sérialisée exacte, octet pour octet. Cette valeur contient à la fois un champ key (qui correspond à votre Auth Key, comme indiqué précédemment) et un paramètre expires, qui est un horodatage situé dans un avenir proche et utilisé comme date d’expiration de la requête.

Pour créer des Assemblies avec Transloadit, votre back-end pourrait calculer une signature qui ne couvre que certains paramètres, utilisateurs authentifiés et une période qu’il considère comme un usage légitime. Par exemple, il refuserait de générer une signature pour les utilisateurs qui ne sont pas connectés. Vous pouvez appliquer ici toute logique métier côté serveur pour décider de fournir ou non une signature. Transloadit peut exiger une signature valide pour la charge utile lorsqu’une requête API s’authentifie avec votre Auth Key.

Pour exiger Signature Authentication pour les requêtes API authentifiées avec votre Auth Key :

1. Accédez aux Paramètres du Workspace dans votre compte.
2. Dans la section Paramètres de l’API, activez l’option Exiger une signature valide.
3. Attendez la fin de l’enregistrement automatique.

Les jetons porteurs valides permettent de s’affranchir des exigences de signature, y compris celles des paramètres du Workspace et du Template ; les restrictions de portée et d’audience du jeton continuent de s’appliquer. Ces paramètres n’ajoutent pas d’authentification aux accès fondés sur des URL donnant directement accès à une opération, comme les URL de consultation du statut d’une Assembly, d’annulation ou de téléversement avec reprise. Gardez les identifiants d’Assembly et ces URL d’accès privés, et suivez les consignes d’authentification de chaque point de terminaison.

Générer des signatures

À quoi cela ressemble-t-il concrètement ?

Le champ params habituel lors de la création d’une Assembly sans Signature Authentication se présente comme suit :

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

Dans cet exemple, auth.key correspond à l’Auth Key disponible dans les Informations d’identification de l’API de votre compte.

Pour signer cette requête, il faut ajouter le champ supplémentaire auth.expires. Il fait alors partie de notre charge utile, qui est protégée par notre signature. Si quelqu’un le modifiait, Transloadit rejetterait la requête, car la signature ne correspondrait plus. Vous auriez signé une charge utile différente de celle que nous avons reçue. Si la signature correspond, nous comparons alors naturellement la date et rejetons la requête selon les indications fournies. Il devient ainsi très difficile pour un tiers qui aurait obtenu cette charge utile de répéter indéfiniment les requêtes. En effet, même si notre connexion HTTPS notée A+ devrait déjà largement contribuer à empêcher cela, le cache du navigateur pourrait être plus facile à espionner.

La propriété expires doit contenir un horodatage situé dans un avenir (proche). Utilisez le format ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) pour la date, en vous assurant d’utiliser UTC comme fuseau horaire. Par exemple :

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

Pour calculer la signature de cette requête :

1. Depuis votre front-end, sérialisez l’objet JavaScript ci-dessus en JSON et envoyez-le à votre back-end.
2. Depuis votre back-end, calculez sur cette chaîne une signature HMAC hexadécimale conforme à la RFC 6234⁠, avec votre Auth Secret comme clé et l’algorithme configuré dans le paramètre signature_algo de votre Auth Key. Les nouvelles Auth Keys utilisent sha384 par défaut. Les anciennes Auth Keys sans algorithme configuré acceptent sha384, sha256 ou sha1. Préfixez la chaîne signature avec le nom de l’algorithme en minuscules. Par exemple, l’algorithme par défaut utilise sha384:<HMAC-signature>. Vous pouvez envoyer cette chaîne à votre front-end (à condition d’avoir effectué les vérifications appropriées pour garantir qu’il s’agissait bien d’une requête provenant de votre front-end).
3. Depuis votre front-end, ajoutez à votre requête un champ POST multipart signature contenant cette valeur (par exemple, avec un champ masqué dans un formulaire HTML).

La requête complète devrait ressembler à ceci :

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

Une fois la requête reçue par Transloadit, nous générons également une signature selon le même processus, puis comparons les deux signatures. Si elles diffèrent, nos serveurs répondent avec INVALID_SIGNATURE.

En résumé, le processus est le suivant :

1. Générez une charge utile JSON à envoyer à Transloadit dans le champ params.
2. Calculez une signature à partir du contenu de la charge utile, en utilisant votre Auth Secret comme clé.
3. Envoyez la requête à Transloadit, avec la signature dans le champ signature
4. Transloadit calcule la même signature à l’aide de l’Auth Secret de votre compte et du contenu de la charge utile.
5. Si les signatures correspondent, la requête est autorisée et une réponse appropriée est envoyée. Sinon, la requête est refusée et une erreur est renvoyée avec le code INVALID_SIGNATURE.

Cela permet à Transloadit d’authentifier l’appelant et de vérifier l’intégrité de params, puisqu’un tiers ne pourrait pas calculer une signature correspondante sans avoir accès à votre Auth Secret. TLS authentifie Transloadit auprès de votre client et protège la connexion. La signature des webhooks est un mécanisme distinct pour les requêtes que Transloadit envoie à vos serveurs.

Vous trouverez ci-dessous quelques exemples de requêtes POST permettant de créer une Assembly. Nous vous recommandons vivement d’utiliser l’un de nos SDK, qui gèrent automatiquement la génération des signatures et sont bien testés.

Exemples de code dans différents langages

Les exemples ci-dessous montrent comment créer des Assemblies avec nos SDK officiels. Les SDK gèrent la génération de toutes les signatures en interne, ce qui rend l’intégration plus simple et plus sûre.

// 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'

URL signées du Smart CDN

Pour signer une URL du Smart CDN, le processus est similaire à celui des signatures API habituelles. Une empreinte HMAC est calculée sur une chaîne dérivée de l’URL du Smart CDN, avec l’Auth Secret comme clé. Pour que la signature soit valide, l’Auth Key utilisée doit être activée pour une utilisation avec le Smart CDN.

La génération d’une signature du Smart CDN doit être effectuée côté back-end. Le processus utilise l’Auth Secret, qui est confidentiel et ne doit pas être exposé à vos utilisateurs côté front-end.

Une URL habituelle du Smart CDN présente la structure suivante :

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

• [your-workspace] est le nom de votre Workspace Transloadit
• [template-name] est le nom de votre Template
• [file-path] est le chemin du fichier que vous souhaitez transformer
• [parameters] correspond aux paramètres de transformation souhaités (par exemple, h=100)

Pour générer une URL signée du Smart CDN, procédez comme suit :

1. Ajoutez le paramètre de requête exp pour définir un instant dans le futur après lequel la signature n’est plus acceptée par le Smart CDN. Cela permet de limiter l’accès à un fichier dans le temps. Le moment d’expiration est représenté par le nombre de millisecondes écoulées depuis l’époque UNIX (minuit au début du 1er janvier 1970, UTC). Bien que ce paramètre soit facultatif, nous vous recommandons vivement de toujours définir une heure d’expiration. Par exemple, une signature utilisant exp=1722517200000 est valide jusqu’au jeudi 01 août 2024 à 13:00:00 GMT.
2. Ajoutez le paramètre de requête auth_key pour définir l’Auth Key correspondant à l’Auth Secret utilisé pour créer la signature. Si ce paramètre n’est pas défini, l’API de Transloadit suppose que la paire associée à l’Auth Key la plus ancienne activée pour le Smart CDN a été utilisée pour la signature. Définir le paramètre auth_key vous permet de renouveler votre Auth Key sans interruption pour vos utilisateurs, et nous vous recommandons donc vivement de le définir. Par exemple : auth_key=23c96d084c744219a2ce156772ec3211
3. Triez les paramètres de requête par clé dans l’ordre croissant des unités de code UTF-16, conformément à URLSearchParams.sort(). Le tri doit être stable, c’est-à-dire que si une clé apparaît plusieurs fois dans la chaîne de requête, les valeurs correspondantes doivent conserver leur ordre relatif. Par exemple, h=100&f=png&f=jpg&auth_key=hello&exp=123 devient après le tri auth_key=hello&exp=123&f=png&f=jpg&h=100.
4. Construisez la chaîne à signer en concaténant les valeurs :

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

   Les valeurs de [your-workspace], [template-name] et [file-path] doivent être encodées pour les URL afin de garantir qu’elles ne contiennent que des caractères autorisés dans les URL. Notez que la chaîne ne commence pas par une barre oblique. Le caractère ? doit être omis si [sorted-parameters] est vide.
5. Calculez sur la chaîne à signer une signature HMAC hexadécimale conforme à la RFC 6234⁠, avec votre Auth Secret comme clé et SHA256 comme algorithme de hachage. Préfixez la signature hexadécimale avec le nom de l’algorithme en minuscules suivi de deux-points, soit sha256:. Par exemple, pour SHA256, utilisez sha256:[hmac-signature].
6. Ajoutez la signature hexadécimale préfixée à l’URL dans le paramètre de requête sig, ce qui donne l’URL signée du Smart CDN :

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

   Les valeurs de [your-workspace], [template-name] et [file-path] doivent être encodées pour les URL afin de garantir qu’elles ne contiennent que des caractères autorisés dans les URL. Cette URL signée peut ensuite être envoyée à votre front-end ou y être utilisée jusqu’à la date d’expiration.

Sécurité et durée de vie du cache

Les URL signées du Smart CDN ne servent pas uniquement au contrôle d’accès. Leur expiration détermine également combien de temps un résultat nouvellement généré peut rester admissible à la mise en cache.

• Des valeurs exp plus courtes réduisent la fenêtre de réutilisation de l’URL et renforcent le contrôle d’accès.
• Des valeurs exp plus longues augmentent la réutilisation du cache, réduisent le travail à l’origine et diminuent généralement la latence et le volume d’encodage.
• En pratique, la durée de vie effective en cache d’une réponse signée du Smart CDN est limitée par la durée de validité restante de la signature.

Le compromis est donc simple :

• Des exigences de sécurité plus élevées : utilisez une valeur exp plus courte, ce qui implique également un TTL effectif du cache plus court.
• Une plus grande réutilisation du cache et un coût réduit : utilisez une valeur exp plus longue, ce qui signifie également que l’URL reste utilisable plus longtemps.

Choisissez la fenêtre d’expiration en fonction de la sensibilité du contenu et du degré de réutilisation du cache souhaité. Pour de nombreux cas d’utilisation d’images et d’aperçus, une fenêtre d’expiration modérée offre un bon équilibre. Pour les contenus très sensibles, utilisez une fenêtre beaucoup plus courte.

Exemples de code

Vous trouverez ci-dessous des exemples dans différents langages pour générer des URL signées du Smart CDN à l’aide de nos SDK.

// 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)

Accès en lecture après résiliation

Les Workspaces résiliés ne peuvent pas créer de nouveaux jetons porteurs. Les points de terminaison qui autorisent explicitement l’accès après résiliation renvoient vers cette procédure. Utilisez une Auth Key active existante et son Auth Secret ; la clé doit toujours accorder les portées indiquées pour le point de terminaison. Cela ne rétablit pas l’accès en écriture et ne rend pas d’autres points de terminaison disponibles après résiliation.

Dans un projet Node.js de confiance côté serveur, installez le SDK avec yarn add @transloadit/node. Définissez TRANSLOADIT_KEY et TRANSLOADIT_SECRET, puis définissez TRANSLOADIT_URL sur l’URL HTTPS complète indiquée sur la page du point de terminaison, en remplaçant les éventuels paramètres de chemin par les valeurs de vos ressources. Gardez les deux informations d’identification, l’URL signée et la réponse privées. N’exécutez jamais cette configuration dans du code de navigateur.

Le SDK signe params avec sha384, l’algorithme par défaut des nouvelles Auth Keys, et fournit l’expiration. L’exemple ajoute un nouveau nonce pour éviter la réutilisation des signatures. Si votre clé utilise un autre algorithme de signature, passez-le comme deuxième argument à calcSignature. Placez les éventuels filtres du point de terminaison dans l’objet passé comme premier argument, à côté du nonce. Le SDK n’appelle pas /token pour cette procédure.

Enregistrez ceci dans read-api.mjs et exécutez node read-api.mjs :

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))

Connecter un client MCP par URL

Les clients agents tels que ChatGPT, Codex, Claude.ai, Claude Desktop, Claude Code et Cursor se connectent au serveur MCP hébergé à l’adresse https://api2.transloadit.com/mcp avec cette seule URL. L’API Transloadit lui sert de serveur d’autorisation OAuth 2.1 : le client découvre les points de terminaison, s’identifie, vous dirige vers la Console pour vous connecter et donner votre consentement, puis obtient un jeton porteur de courte durée pour l’audience mcp, ainsi qu’un jeton de renouvellement. Aucun Auth Secret ne quitte jamais votre compte.

1. Découverte. Le serveur MCP répond aux requêtes non authentifiées avec 401 et un en-tête WWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". Ce document RFC 9728⁠ désigne https://api2.transloadit.com comme serveur d’autorisation, dont les métadonnées RFC 8414⁠ à l’adresse https://api2.transloadit.com/.well-known/oauth-authorization-server répertorient les points de terminaison ci-dessous.
2. Identification du client. Présentez soit un document de métadonnées d’identifiant client⁠ : une URL HTTPS qui constitue le client_id et fournit du JSON contenant le même client_id, un client_name et les redirect_uris. Ou enregistrez-vous une seule fois au moyen de l’enregistrement dynamique des clients RFC 7591⁠ à l’adresse https://api2.transloadit.com/oauth/register ; les clients envoient soit uniquement leur client_id (token_endpoint_auth_method: "none", également lorsque ce paramètre est omis), s’authentifient avec un secret client (client_secret_basic ou client_secret_post), ou s’authentifient avec private_key_jwt et un jwks_uri. La réponse contient un client_id opaque, ainsi qu’un client_secret pour les méthodes à secret, qui n’est affiché que dans cette réponse. Les URI de redirection doivent être des URL HTTPS, avec correspondance exacte, ou des URL de bouclage http://localhost / http://127.0.0.1, avec correspondance sur n’importe quel port. Un client enregistré avec un secret l’envoie lors de chaque requête de jeton et de révocation, par HTTP Basic ou sous la forme de client_id et client_secret dans le formulaire. Les autres requêtes de jeton authentifient le client avec none ou private_key_jwt, selon la méthode indiquée dans son document (dans token_endpoint_auth_methods_supported, ou à défaut dans token_endpoint_auth_method) ou déclarée lors de son enregistrement. La première requête de jeton lie l’autorisation à la méthode utilisée : dès qu’une requête pour une autorisation contient une client_assertion RFC 7523⁠, toutes les requêtes de jeton et de révocation ultérieures pour cette autorisation doivent également en contenir une. Cette assertion est un JWT signé (RS256 ou ES256) avec une clé provenant du jwks_uri du client, avec l’identifiant du client comme iss et sub. Son aud est une URL de point de terminaison de jeton configurée ou son origine (sans barre oblique finale) pour ce déploiement. Son exp se situe dans les cinq minutes et son jti est accepté une seule fois par client et par région tant que l’assertion reste valide. Utilisez un nouveau jti pour chaque requête.
3. Consentement. Le client ouvre https://transloadit.com/c/oauth/authorize avec response_type=code, son client_id, redirect_uri, un code_challenge PKCE (S256 uniquement), éventuellement scope et state, et resource=https://api2.transloadit.com/mcp. Vous vous connectez, choisissez un Workspace et approuvez ; la Console redirige le navigateur vers le client avec code, votre state et iss=https://api2.transloadit.com. Le code est lié au client, à l’URI de redirection, au challenge et au Workspace, et expire après 120 secondes.
4. Jetons. Le client envoie par POST grant_type=authorization_code avec code, code_verifier, client_id et redirect_uri à https://api2.transloadit.com/token et reçoit un access_token (valide pendant 604 800 secondes, soit 7 jours, par défaut), son scope et un refresh_token. L’envoi par POST de grant_type=refresh_token avec refresh_token et client_id renvoie une nouvelle paire et invalide le jeton de renouvellement présenté ; les jetons de renouvellement ont une durée de vie de 30 jours et la réutilisation d’un jeton invalidé révoque toute sa lignée. Les clients qui s’authentifient avec un secret client récupèrent à la place le même jeton de renouvellement, valide pendant 30 jours supplémentaires à compter de ce renouvellement.
5. Révocation. Envoyez token (un jeton d’accès ou de renouvellement) par POST à https://api2.transloadit.com/oauth/revoke conformément à la RFC 7009⁠, ou révoquez la connexion dans la Console.

L’indicateur resource (RFC 8707⁠) détermine à quoi sert le jeton. resource=https://api2.transloadit.com/mcp (la valeur par défaut lorsqu’il est omis) génère un jeton mcp qui porte au maximum les portées MCP sûres (assemblies:write, assemblies:read, templates:read), limitées à celles accordées par l’Auth Key du Workspace, et que seul le serveur MCP accepte. resource=https://api2.transloadit.com (avec ou sans barre oblique finale) génère un jeton api2 pour les applications qui appellent directement l’API REST, comme les intégrations Vercel Connect⁠ : il porte les portées demandées, limitées à celles de l’Auth Key, ou toutes celles accordées par la clé lorsque scope est omis, à ceci près qu’une autorisation ne porte jamais de droits de gestion des Auth Keys ou des informations d’identification de Template (auth_keys:*, template_credentials:*, ou les portées globales read/write qui les impliquent), de sorte qu’elle ne peut ni créer ni révéler des informations d’identification durables. Toute autre valeur de resource renvoie invalid_target.

Les erreurs du protocole OAuth provenant de l’enregistrement des clients, de l’autorisation et de la révocation utilisent le corps standard contenant error et error_description ; les limites de débit peuvent renvoyer RATE_LIMIT_REACHED.

Sur /token, les erreurs d’autorisation OAuth pour authorization_code et refresh_token utilisent le corps standard contenant error et error_description. Les limites de débit renvoient RATE_LIMIT_REACHED (429), et les défaillances internes inattendues renvoient SERVER_500 (500). Les requêtes mal formées rejetées avant l’identification du type d’autorisation peuvent recevoir un challenge HTTP Basic (401), ou TOKEN_INVALID_REQUEST si des informations d’identification Basic ont été fournies.

Jetons porteurs (informations d’identification du client)

Les jobs de CI, les serveurs et les autres clients sans interface utilisateur qui détiennent une Auth Key et un Auth Secret les échangent contre un jeton porteur de courte durée avec le type d’autorisation client_credentials d’OAuth 2.0, géré directement par l’API Transloadit. Utilisez cette méthode lorsqu’aucun navigateur ne permet de donner son consentement ; les clients MCP interactifs devraient se connecter par URL comme décrit ci-dessus. Pour la référence complète du point de terminaison, consultez la documentation de l’API /token.

Utiliser le jeton

Transmettez le jeton sous la forme Authorization: Bearer <access_token> dans les requêtes API. Lorsqu’une requête est authentifiée avec un jeton porteur valide, API2 considère que les exigences de Signature Authentication sont satisfaites et ignore la validation de la signature. Signature Authentication n’est imposée que pour les requêtes utilisant une clé et un secret. Les vérifications de portée et d’audience continuent de s’appliquer. L’audience mcp est acceptée par le serveur MCP, qui la relaie à API2 avec une information d’identification de service ; elle est rejetée lorsqu’elle est présentée directement aux points de terminaison API2 habituels. Vous pouvez omettre auth.key dans params, mais l’enveloppe params reste obligatoire pour les points de terminaison qui l’attendent.

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

Authentification MCP automatique pour /ai/chat

Si vos Steps /ai/chat appellent un serveur MCP hébergé par Transloadit, API2 peut générer et injecter automatiquement un jeton porteur de courte durée (authentification automatique). Cette fonctionnalité doit être activée pour chaque entrée de serveur MCP :

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

Comportement :

• Si auth: "transloadit" est défini et qu’aucun en-tête Authorization n’est présent, API2 génère un jeton et injecte Authorization: Bearer <token>.
• Si Authorization est déjà fourni dans mcp_servers[].headers, il reste inchangé.
• L’authentification automatique ne fonctionne qu’en HTTPS pour les domaines racines et sous-domaines gérés par Transloadit : transloadit.com, *.transloadit.com, transloadit.dev, *.transloadit.dev, transloadit.website, *.transloadit.website, transloadit.work, *.transloadit.work.
• L’URL doit utiliser le port 443 et le chemin exact /mcp ou un sous-chemin sous /mcp/.
• L’URL ne doit contenir ni informations d’identification, ni chaîne de requête, ni fragment.
• L’Auth Key doit accorder au moins l’une de ces portées MCP sûres : assemblies:write, assemblies:read, templates:read.
• Le jeton généré est limité à l’intersection de ces portées MCP sûres et des portées de l’Auth Key ; il n’obtient jamais une portée que l’Auth Key n’accorde pas.

Questions fréquentes

Transloadit inclut-il des signatures dans ses requêtes ?

Transloadit signe les requêtes de webhook pour que votre serveur puisse vérifier leur authenticité. La signature des webhooks est distincte du HMAC qui authentifie les requêtes API envoyées à Transloadit.

Pourquoi ne puis-je pas utiliser mon Auth Secret comme jeton porteur ?

À l’exception de l’échange de jetons entre serveurs décrit ci-dessus, votre Auth Secret ne doit jamais être transmis à un client ni inclus dans les paramètres d’une requête API. POST /token l’envoie comme mot de passe HTTP Basic sur HTTPS et ne doit être appelé que depuis votre back-end. Pour les requêtes signées, le secret reste sur votre back-end et sert de clé HMAC. Cela empêche un acteur malveillant d’intercepter une requête signée et d’envoyer des requêtes usurpées à votre compte. Protégez votre Auth Secret en utilisant le système de gestion des secrets de votre choix. Par exemple : Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ et Kubernetes Secrets⁠, mais de nombreuses autres solutions pourraient convenir selon la plateforme back-end que vous avez choisie.

Dans quel ordre les clés du corps doivent-elles apparaître ?

Vous pouvez choisir n’importe quel ordre pour les clés du corps, mais il est important de noter que l’ordre choisi doit être cohérent avec celui utilisé pour générer votre signature. L’empreinte générée dépend du contenu du JSON, et un ordre différent produit une empreinte différente, ce qui entraîne le refus de votre requête.