Transloadit

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 de params de ce type est présentée ci-dessous.

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

Le champ key désigne 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 qui utilise 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 date d’expiration distincte.

Signature Authentication

Nous vous recommandons d’activer Signature Authentication sur votre compte, en particulier si vous intégrez Transloadit dans un environnement non fiable (par exemple, dans 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 des octets exacts de la valeur sérialisée de params. Cette valeur contient à la fois une key (qui est votre Auth Key, comme indiqué précédemment) et un paramètre expires, qui est un horodatage situé dans un avenir proche, 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 pourriez utiliser n’importe quelle 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. Cliquez sur le bouton Enregistrer.

Les jetons porteurs valides permettent de contourner les exigences de signature, y compris les paramètres du Workspace et du Template ; les restrictions de portée et d’audience des jetons restent applicables. Ces paramètres n’ajoutent pas d’authentification aux accès fondés sur des capacités, comme les URL d’Assembly Status, d’annulation ou de téléversement avec reprise. Gardez les identifiants d’Assembly et les URL de capacité 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 typique lors de la création d’une Assembly sans Signature Authentication se présente comme suit :

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

La valeur auth.key dans cet exemple est l’Auth Key provenant des informations d’identification API de votre compte.

Pour signer cette requête, le champ supplémentaire auth.expires doit être ajouté. Il est ainsi inclus dans 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 comparerons naturellement la date et rejetterons la requête en fonction de celle-ci, comme indiqué. Ainsi, il devient très difficile pour un tiers ayant obtenu cette charge utile de répéter indéfiniment les requêtes. En effet, même si notre HTTPS noté A+ devrait déjà contribuer largement à 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 veillant à 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 une chaîne JSON et envoyez-la à votre back-end.
  2. Depuis votre back-end, calculez une signature HMAC hexadécimale conforme à la RFC 6234 sur cette chaîne, avec votre Auth Secret comme clé et l’algorithme configuré dans le 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 d’une requête authentique 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 en suivant le même processus, puis comparons les deux signatures. Si les signatures sont différentes, 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 transmise dans le champ signature
  4. Transloadit calculera la même signature en utilisant l’Auth Secret de votre compte et le 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, car 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 processus distinct pour les requêtes que Transloadit envoie à vos serveurs.

Vous trouverez ci-dessous quelques exemples de requêtes POST pour 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 ont été soigneusement 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 toute la génération des 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)

Si vous devez calculer une signature séparément (par exemple, pour une utilisation dans le front-end), vous pouvez utiliser calcSignature :

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

console.log(signature, params)

Afficher le code source de l’implémentation des signatures

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 utilisé pour les signatures API ordinaires. Un condensat HMAC est calculé 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 sur le back-end. Le processus utilise l’Auth Secret, qui est confidentiel et ne doit pas être exposé à vos utilisateurs sur le front-end.

Une URL typique 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, suivez ces étapes :

  1. Ajoutez le paramètre de requête exp pour définir un instant futur après lequel la signature ne sera plus acceptée par le Smart CDN. Cela permet de limiter dans le temps l’accès à un fichier. 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 date d’expiration. Par exemple, une signature utilisant exp=1722517200000 est valide jusqu’au jeu. 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 d’Auth Key la plus ancienne parmi celles activées pour le Smart CDN a été utilisée pour la signature. Définir les paramètres auth_key vous permet de renouveler votre Auth Key sans interruption pour vos utilisateurs ; nous vous recommandons donc vivement de définir ce paramètre. Par exemple : auth_key=23c96d084c744219a2ce156772ec3211
  3. Triez les paramètres de requête par clé dans l’ordre croissant selon les unités de code UTF-16, comme 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 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 une signature HMAC hexadécimale conforme à la RFC 6234 sur la chaîne à signer, 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 sont pas seulement un mécanisme de 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 rejeu et renforcent le contrôle d’accès.
  • Des valeurs exp plus longues augmentent la réutilisation du cache, réduisent le travail côté origine et diminuent généralement la latence et le volume d’encodage.
  • En pratique, la durée de vie effective du 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 :

  • Sensibilité accrue à la sécurité : utilisez un exp plus court, ce qui implique aussi un TTL effectif du cache plus court.
  • Davantage de réutilisation du cache et coût réduit : utilisez un exp plus long, ce qui signifie aussi 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.

Exemple de code

Vous trouverez ci-dessous des exemples dans différents langages pour générer des URL signées du Smart CDN avec 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 encore accorder les portées répertorié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 la résiliation.

Dans un projet Node.js côté serveur au sein d’un environnement de confiance, 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 confidentielles. 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 la date d’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, aux côtés 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 redirige 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 de 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 le client une seule fois via l’enregistrement dynamique des clients RFC 7591 à l’adresse https://api2.transloadit.com/oauth/register ; les clients envoient uniquement leur client_id (token_endpoint_auth_method: "none") ou s’authentifient avec private_key_jwt et un jwks_uri, et la réponse contient un client_id opaque. Les URI de redirection doivent être des URL HTTPS, avec une correspondance exacte, ou des URL de boucle locale http://localhost / http://127.0.0.1, acceptées sur n’importe quel port. Les 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 qu’elle a utilisée : dès qu’une requête relative à une autorisation contient une client_assertion RFC 7523, toutes les requêtes de jeton et de révocation ultérieures pour cette autorisation doivent aussi en contenir une. Cette assertion est un JWT signé (RS256 ou ES256) avec une clé issue 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. Elle possède un exp situé dans les cinq minutes qui suivent et un jti 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, ainsi que 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 retire 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 retiré révoque toute la lignée.
  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 l’usage du jeton. resource=https://api2.transloadit.com/mcp (valeur par défaut en cas d’omission) génère un jeton mcp qui contient au plus les portées MCP sûres (assemblies:write, assemblies:read, templates:read), limitées à celles qu’accorde 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 la REST API, comme les intégrations Vercel Connect : il contient 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 comprend jamais la 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), et ne peut donc pas créer ni révéler d’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 entraîner une réponse 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 entraînent une réponse 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 de l’autorisation peuvent recevoir une demande d’authentification HTTP Basic (401), ou TOKEN_INVALID_REQUEST si des informations d’identification Basic ont été fournies.

Jetons porteurs (informations d’identification client)

Les tâches CI, les serveurs et les autres clients sans interface utilisateur qui disposent d’une Auth Key et d’un Auth Secret les échangent contre un jeton porteur de courte durée avec le type d’autorisation OAuth 2.0 client_credentials, géré directement par l’API Transloadit. Utilisez ce mécanisme lorsqu’aucun navigateur n’est disponible pour donner votre consentement ; les clients MCP interactifs devraient se connecter par URL comme décrit ci-dessus. Pour la documentation complète du point de terminaison, consultez la documentation API de /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 Signature Authentication comme satisfaite et ignore la validation de la signature. Signature Authentication n’est imposée que pour les requêtes avec clé/secret. Les vérifications de portée et d’audience restent applicables. L’audience mcp est acceptée par le serveur MCP, qui relaie le jeton à API2 avec des informations d’identification de service ; le jeton est rejeté lorsqu’il est présenté directement aux points de terminaison API2 ordinaires. 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 automatique MCP 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 authentification est facultative et s’active séparément 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 fonctionne uniquement en HTTPS pour les hôtes de domaine racine et les 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.

FAQ

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

Transloadit signe les requêtes de webhook afin 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 ?

Hormis pour l’échange de jetons de serveur à serveur 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 via 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 de falsifier des requêtes adressé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 il en existe bien d’autres qui pourraient convenir selon la plateforme back-end choisie.

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

L’ordre des clés dans le corps peut être arbitraire. Toutefois, il est important de noter que, quel que soit l’ordre choisi, il doit être cohérent avec la génération de votre signature. L’empreinte générée dépend du contenu du JSON, et un ordre différent produira une empreinte différente, ce qui signifie que votre requête sera refusée.