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 inclut le nouvel Auth Secret. Conservez-le en lieu sûr dès que vous le recevez.
La 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 l’afficher une fois par la suite via Récupérer le secret d’une Auth Key.
Une Auth Key pour laquelle Smart CDN est activé peut également authentifier des requêtes API ordinaires et émettre des jetons porteurs. L’activation de Smart CDN n’accorde pas de portées supplémentaires : n’accordez que les autorisations dont votre intégration a besoin. Conservez l’Auth Secret sur votre serveur. Vous pouvez utiliser des Auth Keys distinctes lorsque les intégrations ont besoin d’autorisations ou d’une révocation indépendantes.
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 la section de configuration ci-dessous.
Besoin d’un jeton porteur ?
Dans un shell de confiance côté serveur avec curl et jq, affectez votre Auth Key à TRANSLOADIT_KEY et votre Auth Secret à TRANSLOADIT_SECRET. Gardez confidentiels les deux éléments d’authentification et le jeton obtenu ; n’exécutez jamais cette configuration dans du code de navigateur.
Tout d’abord, créez un jeton doté des 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
Laissez 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 maximale : 64)Valeur personnalisée de l’Auth Key. API2 en génère une si elle est omise. Les caractères situés en dehors du plan multilingue de base d’Unicode, y compris 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 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.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.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.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",
"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.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.