Créer une nouvelle Auth Key
Crée une Auth Key à portée limitée pour le Workspace authentifié.
https://api2.transloadit.com/ auth_keysLa réponse à la création contient le nouvel Auth Secret. Stockez-le de manière sécurisée dès sa réception.
Sa récupération ultérieure est désactivée par défaut. Définissez can_show_auth_secret sur true lors de la création
uniquement si vous avez besoin de le révéler une seule fois par la suite via Récupérer le secret d’une Auth Key.
Une clé pour laquelle le Smart CDN est activé peut également authentifier des requêtes API ordinaires et émettre des jetons porteurs. L’activation du Smart CDN n’accorde aucune portée supplémentaire : accordez uniquement les permissions dont votre intégration a besoin. Conservez l’Auth Secret sur votre serveur. Vous pouvez utiliser des clés distinctes lorsque les intégrations nécessitent des permissions ou une révocation indépendantes.
Définissez notification_signature_algo pour activer une signature de webhook supplémentaire plus robuste.
Cette option est indépendante de la signature des requêtes API et laisse inchangée la signature de formulaire historique en SHA-1.
Exemple de requête
Exécutez cette requête dans un shell côté serveur avec curl et un jeton porteur approprié dans TRANSLOADIT_TOKEN. Si vous avez besoin d’un jeton, développez les instructions de configuration ci-dessous.
Besoin d’un jeton porteur ?
Dans un shell de confiance côté serveur disposant de curl et de jq, définissez TRANSLOADIT_KEY et TRANSLOADIT_SECRET avec les valeurs de votre Auth Key et de votre Auth Secret. Gardez confidentiels ces deux éléments d’identification ainsi que le jeton obtenu ; n’exécutez jamais cette configuration dans du code de navigateur.
Commencez par créer un jeton avec les portées requises par ce point de terminaison. Votre Auth Key doit déjà accorder ces portées.
if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
--request POST \
--url 'https://api2.transloadit.com/token' \
--user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'aud=api2' \
--data-urlencode 'scope=auth_keys:write')"; then
printf '%s\n' "$TOKEN_RESPONSE" >&2
exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
jq -er '.access_token | strings | select(length > 0)')" || exit 1
Gardez ce shell ouvert et exécutez la requête ci-dessous. Réutilisez le jeton tant qu’il reste valide.
curl --fail-with-body -sS --request POST \
--url "https://api2.transloadit.com/auth_keys" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"scope":"assemblies:read,assemblies:write","description":"Backend Assembly integration"}'
Authentification
Ce point de terminaison accepte des params signés ou un jeton porteur. Consultez la section Authentification pour les instructions de configuration.
Portée requise pour l’Auth Key ou le jeton porteur : auth_keys:write.
Les requêtes signées nécessitent à la fois une signature et un horodatage params.auth.expires situé dans le futur. Les jetons porteurs ne nécessitent ni l’un ni l’autre.
Champs de formulaire
Type de contenu : application/x-www-form-urlencoded
params(Chaîne JSON), obligatoire. Un objet encodé en JSON dont les clés prises en charge sont répertoriées ci-dessous.signature(chaîne de caractères). Obligatoire pour les requêtes signées. Omettez ce champ lorsque vous utilisez un jeton porteur.
Clés prises en charge dans le champ params
Les champs d’authentification de cette liste s’appliquent aux requêtes signées. Avec un jeton porteur, vous pouvez omettre params.auth et le champ distinct signature. Comparez les paramètres de requête spécifiques à l’authentification ci-dessous.
Schéma JSON complet
params: Seuls les champs répertoriés pour cet objet sont acceptés.
| Champ | Type et description |
|---|---|
params.obligatoire pour les requêtes signées ; facultatif avec un jeton porteur | Contient la clé API Transloadit et les métadonnées de Signature Authentication pour une requête Auth Keys.
|
params.obligatoire | stringHorodatage d’expiration au format ISO 8601 situé dans le futur. Obligatoire lorsqu’une requête est signée ou nécessite Signature Authentication ; les requêtes authentifiées par jeton porteur peuvent l’omettre. |
params.obligatoire | stringClé API Transloadit utilisée pour authentifier les requêtes |
params. | string (longueur minimale : 32, longueur maximale : 64)Valeur personnalisée de l’Auth Key composée de 32–64 caractères parmi les lettres ASCII, les chiffres, les traits d’union et les traits de soulignement. API2 génère une valeur aléatoire si cette valeur est omise ; privilégiez cette option plutôt que de choisir une valeur prévisible. Les valeurs existantes des Auth Keys restent valides et ne peuvent pas être modifiées en place. Motif de validation (expression régulière)^[A-Za-z0-9_-]+$ |
params. | boolean | 0 | 1Indique si le secret généré peut être révélé une fois après sa création. La valeur par défaut est false. La réponse de création elle-même inclut le secret, indépendamment de ce paramètre ; stockez-le de manière sécurisée. |
params. | string (longueur maximale : 255)Description lisible par un humain de l’Auth Key. Les caractères situés hors du plan multilingue de base d’Unicode, notamment la plupart des émojis, ne sont pas pris en charge. Motif de validation (expression régulière)^[\u0000-\ud7ff\ue000-\uffff]*$ |
params. | boolean | 0 | 1Indique si cette Auth Key peut authentifier les URL du Smart CDN en plus des requêtes API ordinaires et de l’émission de jetons porteurs. Chaque opération nécessite toujours sa propre portée. À la création, si ce paramètre est omis, sa valeur par défaut est false. Lors d’une mise à jour, son omission conserve la valeur actuelle ; envoyez explicitement false pour désactiver l’utilisation du Smart CDN. |
params. | string | integerValeur unique et aléatoire incluse dans les paramètres de la requête signée pour rendre chaque signature unique et empêcher la réutilisation accidentelle d’une signature. |
params. | "sha256" | "sha384" | nullAlgorithme pour l’en-tête de webhook supplémentaire Transloadit-Signature. Le champ de formulaire historique de signature SHA-1 reste inchangé. Valeur par défaut : null (aucun en-tête supplémentaire). Lors d’une mise à jour, l’omission conserve la valeur actuelle ; null désactive l’en-tête supplémentaire. Indépendant de la signature des requêtes à l’API. |
params.obligatoire | stringPortées de l’Auth Key séparées par des virgules. Les portées en double sont normalisées par API2. Motif de validation (expression régulière)^(?:[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*,)*[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:read|write|auth_keys:write|auth_keys:read|assemblies:write|assemblies:read|assembly_notifications:write|dam:read|dam:write|template_credentials:read|template_credentials:write|billing:read|queues:read|smart_cdn:sign|templates:read|templates:write|storage_grants:write)[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:,[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:(?:read|write|auth_keys:write|auth_keys:read|assemblies:write|assemblies:read|assembly_notifications:write|dam:read|dam:write|template_credentials:read|template_credentials:write|billing:read|queues:read|smart_cdn:sign|templates:read|templates:write|storage_grants:write)[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*)?)*$ |
params. | "sha1" | "sha256" | "sha384" | nullAlgorithme HMAC utilisé pour signer les requêtes avec cette Auth Key. À la création, les clés API ordinaires utilisent |
Paramètres de requête par méthode d’authentification
Avec des paramètres signés
Incluez votre Auth Key dans params.auth.key. Lors de la signature de la requête, incluez un horodatage futur dans params.auth.expires et envoyez la signature dans le champ distinct signature. Les définitions des champs ci-dessous utilisent des chemins à l’intérieur de params.
Schéma JSON complet
params: Seuls les champs répertoriés pour cet objet sont acceptés.
Utilise les définitions des champs ci-dessus : params.auth, params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.notification_signature_algo, params.scope, params.signature_algo
Avec un jeton porteur
Envoyez le jeton porteur dans l’en-tête Authorization. Vous pouvez omettre params.auth et le champ distinct signature. Les autres paramètres obligatoires restent requis. Les définitions des champs ci-dessous utilisent des chemins à l’intérieur de params.
Schéma JSON complet
params: Seuls les champs répertoriés pour cet objet sont acceptés.
Utilise les définitions des champs ci-dessus : params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.notification_signature_algo, params.scope, params.signature_algo
| Champ | Type et description |
|---|---|
params. | Contient la clé API Transloadit et les métadonnées de Signature Authentication pour une requête Auth Keys.
|
params. | stringHorodatage d’expiration au format ISO 8601 situé dans le futur. Obligatoire lorsqu’une requête est signée ou nécessite Signature Authentication ; les requêtes authentifiées par jeton porteur peuvent l’omettre. |
params. | stringClé API Transloadit utilisée pour authentifier les requêtes |
Réponse
Voici un exemple de corps de réponse :
{
"auth_key": {
"auth_key": "example_auth_key",
"auth_secret": "example_secret_store_securely",
"can_show_auth_secret": false,
"created": "2026-09-12T10:00:00.000Z",
"description": "Backend Assembly integration",
"id": "ca7644b763c848e6af4f4ccf3eaea622",
"is_active": true,
"is_allowed_for_smartcdn": false,
"last_used": null,
"modified": "2026-09-12T10:00:00.000Z",
"notification_signature_algo": null,
"scope": "assemblies:read,assemblies:write",
"signature_algo": "sha384"
},
"message": "Your auth key was successfully created.",
"ok": "AUTH_KEY_CREATED"
}Succès 2xx
Corps de la réponse JSON. application/json text/plain; charset=utf-8
Schéma du corps de la réponse
Schéma JSON complet
La réponse peut contenir des champs supplémentaires.
| Champ | Type et description |
|---|---|
auth_keyobligatoire |
|
auth_key.obligatoire | string (longueur maximale : 64)Motif de validation (expression régulière)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obligatoire | string |
auth_key.obligatoire | boolean |
auth_key.obligatoire | string | nullDate et heure de création de l’Auth Key, sous forme d’horodatage ISO 8601, ou null lorsqu’aucun horodatage de création n’est enregistré. Motif de validation (expression régulière)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.obligatoire | string (longueur maximale : 255)Motif de validation (expression régulière)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obligatoire | string |
auth_key.obligatoire | boolean |
auth_key.obligatoire | boolean |
auth_key.obligatoire | string | nullDate et heure approximatives de la dernière utilisation, sous forme d’horodatage ISO 8601, ou null si aucun horodatage n’a été enregistré. L’utilisation est suivie de manière asynchrone et enregistrée par lots, cette valeur peut donc accuser un retard par rapport aux requêtes. Il ne s’agit pas d’un horodatage d’audit exact, et null ne prouve pas que la clé n’a jamais été utilisée. Motif de validation (expression régulière)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.obligatoire | string | nullDate et heure de la dernière mise à jour des paramètres de l’Auth Key, sous la forme d’un horodatage ISO 8601, ou null lorsqu’aucun horodatage de modification n’est enregistré. Le suivi de l’utilisation est indiqué séparément dans Motif de validation (expression régulière)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key. | "sha256" | "sha384" | nullAlgorithme pour l’en-tête de webhook supplémentaire Transloadit-Signature. Le champ de formulaire historique de signature SHA-1 reste inchangé. Valeur par défaut : null (aucun en-tête supplémentaire). Lors d’une mise à jour, l’omission conserve la valeur actuelle ; null désactive l’en-tête supplémentaire. Indépendant de la signature des requêtes à l’API. |
auth_key.obligatoire | string | null (longueur maximale : 512)Motif de validation (expression régulière)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obligatoire | null | string |
messageobligatoire | string (longueur minimale : 1) |
okobligatoire | string (toujours : "AUTH_KEY_CREATED") |
Réponse d’erreur
Corps de la réponse JSON. application/json text/plain; charset=utf-8
Schéma du corps de la réponse
Schéma JSON complet
La réponse peut contenir des champs supplémentaires.
| Champ | Type et description |
|---|---|
assembly_id | string |
error | string (longueur minimale : 1) |
http_code | number | string
|
message | stringExplication de l’erreur destinée à être lue par un humain. Sa formulation peut varier ; utilisez le code |
reason | null | string | number | boolean | Array<n’importe quelle valeur> | objectN’importe lequel des schémas suivants peut s’appliquer : nullstringnumberbooleanArray<n’importe quelle valeur>Array<n’importe quelle valeur>Schéma d’un élément de tableaun’importe quelle valeurobjectobjectSchéma de la propriété supplémentairen’importe quelle valeur |
HTTP 400
Corps de la réponse JSON. application/json text/plain; charset=utf-8
Schéma du corps de la réponse
Schéma JSON complet
Erreurs nommées et format général des erreurs
error: "AUTH_KEY_NOT_CREATED"
Votre Auth Key n’a pas pu être créée.
La réponse peut contenir des champs supplémentaires.