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 représente 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 l’indiquent leur documentation et les sections 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 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 ne nécessitent ni signature ni expiration distinctes.

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 depuis les Paramètres du Workspace.

Lorsque Signature Authentication est activée, l’Auth Secret de votre Workspace (situé à 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 params sérialisée. Cette valeur contient à la fois une key (qui est votre Auth Key, comme indiqué précédemment) et un paramètre expires, un horodatage dans un futur 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, des utilisateurs authentifiés et une période qu’il considère comme relevant d’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 ici n’importe quelle logique métier côté serveur pour décider de fournir ou non une signature. Transloadit peut exiger une signature correcte 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 correcte.
3. Cliquez sur le bouton Enregistrer.

Les jetons porteurs valides contournent les exigences de signature, y compris les paramètres du Workspace et du Template ; les restrictions de portée et d’audience des jetons continuent de s’appliquer. Ces paramètres n’ajoutent pas d’authentification aux accès fondés sur des URL de capacité, comme les URL de consultation de l’état d’une Assembly, d’annulation ou de téléversement avec reprise. Gardez les identifiants d’Assembly et les URL de capacité confidentiels, 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 est 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 est ainsi ajouté à 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 alors la date et rejetterons la requête selon les indications fournies. Il devient ainsi 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 de niveau 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 dans un futur (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 sur cette chaîne une signature HMAC hexadécimale conforme à la RFC 6234⁠, avec votre Auth Secret comme clé et l’algorithme configuré dans 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 en suivant le même processus, puis nous 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, en transmettant 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 suit 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é testés de manière approfondie.

Exemples de code pour différents langages

Les exemples ci-dessous montrent comment créer des Assemblies à l’aide de nos SDK officiels. Les SDK gèrent toute la génération des signatures en interne, ce qui simplifie et sécurise l’intégration.

// 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 ordinaires. 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 l’utilisation du 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, suivez ces étapes :

1. Ajoutez le paramètre de requête exp pour définir un instant 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 de l’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 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 interrompre vos utilisateurs ; 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 devrait être stable, c’est-à-dire que si une clé apparaît plusieurs fois dans la chaîne de requête, les valeurs correspondantes devraient 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 compatibles avec 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 compatibles avec 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 uniquement 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 réutilisation des requêtes et renforcent le contrôle d’accès.
• Des valeurs exp plus longues augmentent la réutilisation du cache, réduisent le travail du serveur d’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 :

• Exigences de sécurité plus élevées : utilisez un exp plus court, ce qui réduit également le TTL effectif du cache.
• Réutilisation accrue du cache et coût réduit : utilisez un exp plus long, ce qui signifie également que l’URL reste utilisable plus longtemps.

Choisissez la période d’expiration en fonction de la sensibilité du contenu et du niveau de réutilisation du cache souhaité. Pour de nombreux cas d’utilisation d’images et d’aperçus, une période d’expiration modérée offre un bon équilibre. Pour les contenus très sensibles, utilisez une période 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 à cette procédure. Utilisez une Auth Key existante et active ainsi que 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 présentée sur la page du point de terminaison, en remplaçant les éventuels paramètres de chemin par les valeurs de votre ressource. 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, la valeur par défaut des nouvelles Auth Keys, et fournit l’expiration. L’exemple ajoute un nouveau nonce pour éviter la réutilisation de la signature. Si votre clé utilise un autre algorithme de signature, transmettez-le comme deuxième argument à calcSignature. Placez les éventuels filtres du point de terminaison dans l’objet transmis comme premier argument, aux côtés du nonce. Le SDK n’appelle pas /token dans cette procédure.

Enregistrez ce code 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))

Jetons porteurs (informations d’identification du client)

Si vous avez besoin d’un jeton de courte durée pour des clients serveur à serveur ou sans interface, vous pouvez échanger votre Auth Key et votre Auth Secret contre un jeton porteur. Cela reproduit un flux OAuth 2.0 client_credentials, mais est géré directement par l’API Transloadit. Pour la documentation 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 et rejetée par les 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 fonctionnalité s’active explicitement 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 via 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.

Questions fréquentes

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

Transloadit signe les requêtes de webhook EN (English) 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 ?

À l’exception de 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 doit être appelé uniquement 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 vers votre compte. Protégez votre Auth Secret en utilisant le système de gestion des secrets de votre choix. Voici quelques exemples : Vault⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ et Kubernetes Secrets⁠, mais de nombreuses autres solutions peuvent convenir selon la plateforme back-end que vous choisissez.

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 cet ordre doit être cohérent avec celui utilisé pour la génération de votre signature. L’empreinte générée dépend du contenu du JSON, et un ordre différent génère une empreinte différente, ce qui entraîne le refus de votre requête.