Crear un nuevo Auth Key
Crea una Auth Key con ámbitos para el Workspace autenticado.
https://api2.transloadit.com/ auth_keysLa respuesta de creación incluye el nuevo Auth Secret. Guárdalo de forma segura cuando lo recibas.
La recuperación posterior está deshabilitada de forma predeterminada. Establece can_show_auth_secret en true durante la creación
solo si necesitas revelarlo una vez posteriormente mediante Recuperar el secreto de una Auth Key.
Una clave de Smart CDN no puede autenticar solicitudes normales a la API ni emitir tokens Bearer. Crea una clave independiente para Smart CDN; habilitarlo en una clave de integración hace que esa clave deje de autenticar solicitudes a la API.
Ejemplo de solicitud
Ejecuta esta solicitud en una shell del lado del servidor con curl y un token Bearer adecuado en TRANSLOADIT_TOKEN. Si necesitas un token, despliega la sección de configuración siguiente.
¿Necesitas un token Bearer?
En una shell de confianza del lado del servidor con curl y jq, asigna a TRANSLOADIT_KEY y TRANSLOADIT_SECRET los valores de tu Auth Key y tu Auth Secret, respectivamente. Mantén en secreto ambas credenciales y el token resultante; nunca ejecutes esta configuración en código del navegador.
Primero, crea un token con los ámbitos requeridos por este endpoint. Tu Auth Key ya debe conceder esos ámbitos.
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
Deja esta shell abierta y ejecuta la solicitud que aparece a continuación. Reutiliza el token mientras siga siendo válido.
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"}'
Autenticación
Este endpoint acepta params firmados o un token Bearer. Consulta Autenticación para ver las instrucciones de configuración.
Ámbito requerido para el Auth Key o el token de portador: auth_keys:write.
Las solicitudes firmadas requieren tanto una signature como una marca de tiempo futura en params.auth.expires. Los tokens Bearer no requieren ninguno de estos dos elementos.
Campos del formulario
Tipo de contenido: application/x-www-form-urlencoded
params(cadena JSON), obligatorio. Un objeto codificado en JSON cuyas claves compatibles se enumeran a continuación.signature(cadena). Obligatorio para las solicitudes firmadas. Omite este campo cuando uses un token Bearer.
Claves admitidas dentro del campo params
Los campos de autenticación de esta lista se aplican a las solicitudes firmadas. Con un token Bearer puedes omitir params.auth y el campo separado signature. Compara a continuación los parámetros de solicitud de cada método de autenticación.
JSON Schema completo
params: Solo se aceptan los campos enumerados para este objeto.
| Campo | Tipo y descripción |
|---|---|
params.obligatorio para las solicitudes firmadas; opcional con un token Bearer | Contiene la clave de API de Transloadit y los metadatos de Signature Authentication para una solicitud de Auth Keys.
|
params.obligatorio | stringMarca de tiempo de vencimiento ISO 8601 en el futuro. Es obligatoria cuando una solicitud está firmada o requiere autenticación mediante firma; las solicitudes autenticadas con Bearer pueden omitirla. |
params.obligatorio | stringClave de API de Transloadit utilizada para autenticar solicitudes |
params. | string | integerValor aleatorio y único incluido en los parámetros de las solicitudes firmadas para que cada firma sea única y evitar su reutilización accidental. |
params. | string (longitud máxima: 64)Valor personalizado de Auth Key. API2 genera uno si se omite. No se admiten caracteres fuera del plano multilingüe básico de Unicode, incluidos la mayoría de los emojis. Patrón de validación (expresión regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
params. | boolean | 0 | 1Indica si el secreto generado puede revelarse una sola vez después de la creación. El valor predeterminado es false. La respuesta de creación incluye el secreto independientemente de esta opción; guárdalo de forma segura. |
params. | string (longitud máxima: 255)Descripción legible de Auth Key. No se admiten caracteres fuera del plano multilingüe básico de Unicode, incluidos la mayoría de los emojis. Patrón de validación (expresión regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
params. | boolean | 0 | 1Indica si esta Auth Key está dedicada a las URLs de Smart CDN. Una clave de Smart CDN no puede autenticar solicitudes normales de la API ni emitir tokens Bearer. Usa una clave independiente para Smart CDN. Al crearla, omitir el campo equivale a false. Al actualizarla, omitirlo conserva el valor actual; envía false explícitamente para desactivar su uso con Smart CDN. |
params. | string | integerValor aleatorio y único incluido en los parámetros de las solicitudes firmadas para que cada firma sea única y evitar su reutilización accidental. |
params.obligatorio | stringÁmbitos de la Auth Key separados por comas. API2 normaliza los ámbitos duplicados. Patrón de validación (expresión regular)^(?:[\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:write|template_credentials:read|template_credentials:write|billing:read|queues:read|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:write|template_credentials:read|template_credentials:write|billing:read|queues:read|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" | nullAlgoritmo HMAC utilizado para firmar solicitudes con este Auth Key. Al crearse, las claves de API normales usan |
Parámetros de solicitud según el método de autenticación
Con parámetros firmados
Incluye tu Auth Key como params.auth.key. Al firmar la solicitud, incluye una marca de tiempo futura en params.auth.expires y envía la Signature en el campo separado signature. Las definiciones de los campos que aparecen a continuación usan rutas dentro de params.
JSON Schema completo
params: Solo se aceptan los campos enumerados para este objeto.
Utiliza las definiciones de campos indicadas arriba: params.auth, params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.scope, params.signature_algo
Con un token Bearer
Envía el token Bearer en el encabezado Authorization. Puedes omitir params.auth y el campo independiente signature. Los demás parámetros obligatorios siguen siendo necesarios. Las definiciones de los campos que aparecen a continuación usan rutas dentro de params.
JSON Schema completo
params: Solo se aceptan los campos enumerados para este objeto.
Utiliza las definiciones de campos indicadas arriba: params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.scope, params.signature_algo
| Campo | Tipo y descripción |
|---|---|
params. | Contiene la clave de API de Transloadit y los metadatos de Signature Authentication para una solicitud de Auth Keys.
|
params. | stringMarca de tiempo de vencimiento ISO 8601 en el futuro. Es obligatoria cuando una solicitud está firmada o requiere autenticación mediante firma; las solicitudes autenticadas con Bearer pueden omitirla. |
params. | stringClave de API de Transloadit utilizada para autenticar solicitudes |
params. | string | integerValor aleatorio y único incluido en los parámetros de las solicitudes firmadas para que cada firma sea única y evitar su reutilización accidental. |
Respuesta
Este es un ejemplo del cuerpo de la respuesta:
{
"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"
}éxito 2xx
Cuerpo de respuesta JSON. application/json text/plain; charset=utf-8
Esquema del cuerpo de la respuesta
JSON Schema completo
La respuesta puede contener campos adicionales.
| Campo | Tipo y descripción |
|---|---|
auth_keyobligatorio |
|
auth_key.obligatorio | string (longitud máxima: 64)Patrón de validación (expresión regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obligatorio | string |
auth_key.obligatorio | boolean |
auth_key.obligatorio | string | nullHora de creación del Auth Key como marca de tiempo ISO 8601, o null si no se ha registrado la hora de creación. Patrón de validación (expresión regular)^(([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.obligatorio | string (longitud máxima: 255)Patrón de validación (expresión regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obligatorio | string |
auth_key.obligatorio | boolean |
auth_key.obligatorio | boolean |
auth_key.obligatorio | string | nullHora aproximada del último uso como marca de tiempo ISO 8601, o null si no se ha registrado ninguna. El uso se registra de forma asíncrona y se guarda por lotes, por lo que este valor puede ir por detrás de las solicitudes. No es una marca de auditoría exacta y null no demuestra que la clave nunca se haya usado. Patrón de validación (expresión regular)^(([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.obligatorio | string | nullHora de la última actualización de la configuración del Auth Key como marca de tiempo ISO 8601, o null si no se ha registrado una modificación. El seguimiento del uso se indica por separado en Patrón de validación (expresión regular)^(([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.obligatorio | string | null (longitud máxima: 255)Patrón de validación (expresión regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obligatorio | null | string |
messageobligatorio | string (longitud mínima: 1) |
okobligatorio | string (siempre: "AUTH_KEY_CREATED") |
Respuesta de error
Cuerpo de respuesta JSON. application/json text/plain; charset=utf-8
Esquema del cuerpo de la respuesta
JSON Schema completo
La respuesta puede contener campos adicionales.
| Campo | Tipo y descripción |
|---|---|
assembly_id | string |
error | string (longitud mínima: 1) |
http_code | number | string
|
message | stringExplicación del error legible por humanos. Su redacción puede variar; usa el código |
reason | null | string | number | boolean | Array<cualquier valor> | objectPuede aplicarse cualquiera de los esquemas siguientes: nullnullstringstringnumbernumberbooleanbooleanArray<cualquier valor>Array<cualquier valor>Esquema de los elementos del arraycualquier valorobjectobjectEsquema de propiedades adicionalescualquier valor |
HTTP 400
Cuerpo de respuesta JSON. application/json text/plain; charset=utf-8
Esquema del cuerpo de la respuesta
JSON Schema completo
Errores con nombre y el formato general de error
error: "AUTH_KEY_NOT_CREATED"
No se pudo crear tu Auth Key.
La respuesta puede contener campos adicionales.