# Autenticación ## Auth Keys Al interactuar con la REST API de Transloadit, **exigimos** que un parámetro `auth` forme parte de la solicitud de formulario multipart. A continuación se muestra un ejemplo del JSON necesario para este campo. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```json { "auth": { "key": "23c96d084c744219a2ce156772ec3211" } } ``` El campo `key` hace referencia a la Auth Key asociada con tu Workspace de Transloadit, que se encuentra en la página [Credenciales](/c/credentials/). Por lo tanto, lo anterior es el mínimo necesario para autenticarte y utilizar la mayoría de los endpoints de la API de Transloadit, y es obligatorio para casi todas las solicitudes. ## Signature Authentication Te recomendamos habilitar Signature Authentication en tu cuenta, especialmente si estás integrando Transloadit desde un entorno que no es de confianza (como el navegador con[Uppy](https://uppy.io/)). Puedes habilitar Signature Authentication desde la[Configuración del Workspace](/c/settings/). ###### Advertencia Te recomendamos *enfáticamente* habilitar Signature Authentication cuando interactúes con nuestra API, en especial en entornos que no sean de confianza, donde los usuarios podrían acceder a tuAuth Key. Con Signature Authentication habilitada, la Auth Secret de tu Workspace (que se encuentra junto a tu Auth Key en la página [Credenciales](/c/credentials/)) se utiliza para agregar una sal a un hash generado a partir del cuerpo de la solicitud, que contiene tanto una `key` (que es tuAuth Key, como se mencionó anteriormente) como un parámetro `expires`, que es una marca de tiempo de un momento cercano en el futuro utilizada como fecha de vencimiento de la solicitud. Para crear Assemblies con Transloadit, tu back-end podría calcular unafirma que cubra solo determinados parámetros, usuarios autenticados y un período que considere como uso legítimo. Por ejemplo, se negaría a generar una firma para los usuarios que no hayan iniciado sesión. Puedes utilizar cualquier lógica de negocio del lado del servidor para decidir si proporcionas o no una firma, y Transloadit puede configurarse para rechazar cualquier solicitud dirigida a tu cuenta que no esté acompañada de una firma correcta para el payload. Si quieres que Signature Authentication sea obligatoria para todas las solicitudes relacionadas con tu cuenta: 1. Ve a [Configuración del Workspace](/c/settings/) en tu cuenta. 2. En la sección Configuración de la API, habilita la opción **Exigir una firma correcta**. 3. Presiona el botón Guardar. ###### Nota La mayoría de los [SDK](/docs/sdks.md) de back-end utilizan automáticamente Signature Authentication cuando proporcionas tu Auth Secret. Por lo tanto, quizá esta introducción sea todo lo que necesitas saber. Sin embargo, si estás integrando Transloadit en entornos que no son de confianza, como navegadores (¡[Uppy](/docs/sdks/uppy.md)!), te conviene seguir leyendo para ver cómo tu back-end puede proporcionarle firmas. ## Cómo generar firmas Entonces, ¿cómo funciona todo esto? El campo `params` típico al crear una Assembly **sin** Signature Authentication es el siguiente: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```jsonc { "auth": { "key": "23c96d084c744219a2ce156772ec3211" }, "steps": { // … } } ``` El valor `auth.key` de este ejemplo es la Auth Key de[Credenciales de la API en tu cuenta](/c/template-credentials/). Para firmar esta solicitud, debes agregar el campo adicional `auth.expires`. Esto lo agrega a nuestro payload, que está protegido por nuestra firma. Si alguien lo modificara, Transloadit rechazaría la solicitud porque la firma ya no coincidiría. Habrías firmado un payload distinto del que recibimos. Si la firma coincide, compararemos la fecha y rechazaremos la solicitud según lo indicado. De esta forma, resulta muy difícil que un tercero que haya obtenido este payload repita las solicitudes indefinidamente. Aunque nuestro HTTPS con calificación A+ ya debería contribuir considerablemente a evitarlo, podría ser más fácil espiar la caché del navegador. La propiedad `expires` debe contener una marca de tiempo de un momento (cercano) en el futuro. Usa el formato ISO 8601 (`YYYY-MM-DDTHH:mm:ss.sssZ`) para la fecha y asegúrate de utilizar UTC como zona horaria. Por ejemplo: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```jsonc { "auth": { "key": "23c96d084c744219a2ce156772ec3211", "expires": "2009-08-28T01:02:03.000Z" }, "steps": { // … } } ``` Para calcular la firma de esta solicitud: 1. Desde tu front-end, convierte el objeto JavaScript anterior en una cadena JSON y envíala a tu back-end. 2. Desde tu back-end, calcula una firma hexadecimal HMAC [compatible con RFC 6234](https://www.ietf.org/rfc/rfc6234.txt)sobre la cadena, con tu Auth Secret como clave y SHA384 como algoritmo hash. Anteponle a la cadena `signature` el nombre del algoritmo en minúsculas. Por ejemplo, para SHA384, usa `sha384:`. Puedes enviar esa cadena a tu front-end (siempre que hayas realizado las comprobaciones adecuadas para garantizar que se trataba de una solicitud auténtica de tu front-end). 3. Desde tu front-end, agrega a tu solicitud un campo POST multipart `signature` que contenga este valor (por ejemplo, mediante un campo oculto en un formulario HTML). ###### Nota Si tu implementación utiliza un `template_id` en lugar de `steps`, no es necesario generar una firma para las Instructions que contiene tu Template. Solo debemos firmar los payloads de comunicación. ###### Nota Te recomendamos enfáticamente incluir un `nonce` generado aleatoriamente: un valor único por solicitud que evita el procesamiento duplicado durante los reintentos, puede ayudar con la depuración y evita vectores de ataque como la reutilización de claves de firma. Es importante que el `nonce` sea único para cada solicitud; de lo contrario, no será eficaz. La solicitud completa debería ser similar a la siguiente: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```jsonc { "params": { "auth": { "key": "23c96d084c744219a2ce156772ec3211", "expires": "2009-08-28T01:02:03.000Z", "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1", }, "steps": { // … }, }, "signature": "9cf67cbba601e37ee10c442b037e0", } ``` Una vez que Transloadit recibe la solicitud, también generamos una firma siguiendo el mismo proceso y comparamos ambas firmas. Si son diferentes, nuestros servidores responderán con `INVALID_SIGNATURE`. En resumen, el proceso es el siguiente: 1. Genera un payload JSON para enviarlo a Transloadit como campo `params`. 2. Calcula una firma basada en el contenido del payload y usa tu Auth Secret como clave. 3. Envía la solicitud a Transloadit y pasa la firma en el campo `signature`. 4. Transloadit calculará la misma firma mediante la Auth Secret de tu cuenta y el contenido del payload. 5. Si las firmas coinciden, se permite la solicitud y se envía una respuesta apropiada. De lo contrario, se rechaza la solicitud y se devuelve un error con el código`INVALID_SIGNATURE`. Esto permite que ambas partes verifiquen que la otra está autenticada (ya que un tercero no podría calcular una firma coincidente sin acceder a tu Auth Secret) sin transmitir nunca directamente la Auth Secret. A continuación se muestran algunos ejemplos de cómo realizar una solicitud POST para crear una Assembly. Te recomendamos enfáticamente utilizar uno de nuestros [SDK](/docs/sdks.md), que gestionan automáticamente la generación de firmas y se han probado exhaustivamente. ###### Importante Para verificar la firma que enviamos con un webhook de una Assembly, usa la Auth Secret que pertenece a la Auth Key utilizada para esa Assembly específica. Para generar una firma con fines de verificación, debes utilizar el algoritmo `sha1` debido a problemas de compatibilidad con versiones anteriores. Muchos clientes de larga trayectoria dependen de que estas firmas se generen con sha1 desde hace años, por lo que no podemos cambiarlo fácilmente. ## Código de ejemplo para distintos lenguajes Los siguientes ejemplos muestran cómo crear Assemblies mediante nuestros SDK oficiales. Los SDK gestionan internamente toda la generación de firmas, lo que hace que la integración sea más sencilla y segura. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```js // yarn add transloadit // or // npm install --save transloadit import { Transloadit } from 'transloadit' 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 necesitas calcular una firma por separado (por ejemplo, para utilizarla en el front-end), puedes usar`calcSignature`: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```js const { signature, params } = transloadit.calcSignature({ template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID', }) console.log(signature, params) ``` [Consulta el código fuente de la implementación de firmas](https://github.com/transloadit/node-sdk/blob/main/src/Transloadit.ts) ###### Nota Si prefieres consultar los detalles de la implementación básica de firmas (por ejemplo, para implementar la firma en un lenguaje para el cual no tengamos un SDK), revisa los enlaces al código fuente anteriores. La firma es un resumen hexadecimal HMAC [compatible con RFC 6234](https://www.ietf.org/rfc/rfc6234.txt), calculado sobre la cadena de parámetros codificada en JSON, con tu Auth Secret como clave y SHA384 como algoritmo hash. La firma debe incluir como prefijo el nombre del algoritmo (por ejemplo, `sha384:...`). ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```sh curl --location 'https://api2.transloadit.com/assemblies' \ --form 'params="{\"auth\":{\"key\":\"\23c96d084c744219a2ce156772ec3211\",\"expires\":\"2024/02/28 15:09:32.941Z\"},\"template_id\":\"\9cf67cbba601e37ee10c442b037e0\"}"' \ --form 'signature="sha1:46253af0d7b2f0603375bbc6bfd5393363a8138c"' \ --form 'files=@/path/to/your/file.jpg' ``` ## URL firmadas de Smart CDN Para firmar una URL de Smart CDN, se utiliza un proceso similar al de las firmas normales de la API. Se calcula un resumen HMAC sobre una cadena derivada de la URL de Smart CDN, con la Auth Secret como clave. Para que la firma sea válida, la Auth Key utilizada debe estar habilitada para Smart CDN. ###### Importante Para generar una URL firmada de Smart CDN, usa la Auth Key designada para Smart CDN en tu página Credenciales. Las URL de Smart CDN utilizan `sha256`. Las firmas de solicitudes normales de la API continúan utilizando`sha384`. ###### Nota Las firmas heredadas de Smart CDN basadas en `s=` y `expires=` están obsoletas. Las integraciones nuevas deben utilizar siempre `sig=` con `exp=`. La generación de una firma de Smart CDN debe realizarse en el back-end. El proceso utiliza laAuth Secret, que es confidencial y no debe exponerse a tus usuarios en el front-end. Una URL típica de Smart CDN tiene la siguiente estructura: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ``` https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters] ``` * `[your-workspace]` es el nombre de tu Workspace de Transloadit * `[template-name]` es el nombre de tu Template * `[file-path]` es la ruta del archivo que quieres transformar * `[parameters]` son los parámetros de transformación deseados (por ejemplo, `h=100`) Para generar una URL firmada de Smart CDN, sigue estos pasos: 1. Agrega el parámetro de consulta `exp` para definir un momento futuro después del cual Smart CDN dejará de aceptar la firma. Esto resulta útil para limitar el acceso temporal a un archivo. El momento de vencimiento se representa mediante la cantidad de milisegundos desde la época UNIX (la medianoche al inicio del 1 de enero de 1970, UTC). Aunque este parámetro es opcional, te recomendamos enfáticamente establecer siempre un tiempo de vencimiento. Por ejemplo, una firma que utiliza `exp=1722517200000` es válida hasta Thu, 01 Aug 2024 13:00:00 GMT. 2. Agrega el parámetro de consulta `auth_key` para definir la Auth Key correspondiente a laAuth Secret utilizada para crear la firma. Si no se establece este parámetro, la API de Transloadit supone que se utilizó para la firma el par de Auth Key más antiguo habilitado para Smart CDN. Establecer el parámetro `auth_key` te permite rotar tu Auth Key sin interrumpir a tus usuarios, por lo que te recomendamos enfáticamente configurarlo. Por ejemplo:`auth_key=23c96d084c744219a2ce156772ec3211` 3. Ordena los parámetros de consulta según los puntos de código Unicode de las claves en orden descendente. El ordenamiento debe ser estable; es decir, si una clave aparece varias veces en la cadena de consulta, los valores correspondientes deben conservar su orden relativo. Por ejemplo,`h=100&f=png&f=jpg&auth_key=hello&exp=123` se ordena como`auth_key=hello&exp=123&h=100&f=png&f=jpg`. 4. Construye la cadena que se firmará concatenando los valores:\ ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ``` [your-workspace]/[template-name]/[file-path]?[sorted-parameters] ``` Los valores de `[your-workspace]`, `[template-name]` y `[file-path]` deben codificarse para URL a fin de garantizar que solo contengan caracteres seguros para URL. Ten en cuenta que la cadena no comienza con una barra. El carácter `?` debe omitirse si `[sorted-parameters]` está vacío. 5\. Calcula una firma hexadecimal HMAC [compatible con RFC 6234](https://www.ietf.org/rfc/rfc6234.txt) sobre la cadena que se firmará, con tu Auth Secret como clave y SHA256 como algoritmo hash. Anteponle a la firma hexadecimal el nombre del algoritmo en minúsculas y dos puntos, es decir, `sha256`. Por ejemplo, para SHA256, usa `sha256:[hmac-signature]`. 6\. Agrega a la URL la firma hexadecimal con prefijo mediante el parámetro de consulta `sig` para obtener la URL firmada de Smart CDN:\ ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ``` https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature] ``` Los valores de `[your-workspace]`, `[template-name]` y `[file-path]` deben codificarse para URL a fin de garantizar que solo contengan caracteres seguros para URL. Después puedes enviar esta URL firmada a tu front-end o utilizarla allí hasta alcanzar la fecha de vencimiento. ### Seguridad y duración de la caché Las URL firmadas de Smart CDN no son solo un mecanismo de control de acceso. Su vencimiento también determina durante cuánto tiempo puede permanecer en caché un resultado recién generado. * Los valores de `exp` más cortos reducen el período de reejecución y refuerzan el control de acceso. * Los valores de `exp` más largos aumentan la reutilización de la caché, reducen el trabajo del origen y, por lo general, disminuyen la latencia y el volumen de encoding. * En la práctica, la duración efectiva de la caché de una respuesta firmada de Smart CDN está limitada por el tiempo restante de validez de la firma. Esto significa que la compensación es sencilla: * Mayor sensibilidad de seguridad: usa un `exp` más corto, lo que también implica un TTL efectivo de caché más corto. * Mayor reutilización de la caché y menor costo: usa un `exp` más largo, lo que también significa que la URL podrá utilizarse durante más tiempo. Elige el período de vencimiento según la sensibilidad del contenido y el grado de reutilización de la caché que quieras. Para muchos casos de uso de imágenes y vistas previas, un período de vencimiento moderado ofrece un buen equilibrio. Para contenido muy sensible, usa uno mucho más corto. ### Código de ejemplo A continuación puedes encontrar ejemplos en distintos lenguajes para generar URL firmadas de Smart CDN mediante nuestros SDK. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```js // yarn add transloadit // or // npm install --save transloadit import { Transloadit } from 'transloadit' 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) ``` ## Tokens Bearer (credenciales del cliente) Si necesitas un token de corta duración para comunicaciones entre servidores o clientes sin interfaz, puedes intercambiar tuAuth Key y tu Auth Secret por un token Bearer. Esto refleja un flujo`client_credentials` de OAuth 2.0, pero la API de Transloadit lo gestiona directamente. Para consultar la referencia completa del endpoint, consulta la [documentación de la API de /token](/es/docs/api/token-post.md). ### `POST /token` **Solicitud** * **Autenticación:** Basic Auth con tu Auth Key y tu Auth Secret * **Content-Type:** `application/x-www-form-urlencoded` * **Cuerpo:** * `grant_type=client_credentials` (obligatorio) * `scope=assemblies:read assemblies:write` (opcional; separado por espacios o comas) * `aud=api2` (opcional) ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```bash curl --request POST \ --url 'https://api2.transloadit.com/token' \ --user 'auth_key:auth_secret' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=assemblies:read assemblies:write' ``` **Respuesta** ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```json { "access_token": "opaque-token", "token_type": "Bearer", "expires_in": 21600, "scope": "assemblies:read assemblies:write" } ``` Los tokens son válidos durante seis horas (`expires_in: 21600`). ###### Nota Los tokens se generan del lado del servidor mediante `/token` con tu Auth Key/Secret. Si expones la creación de tokens mediante una interfaz, llama a `/token` desde tu back-end (nunca directamente desde el navegador). ### Uso del token Pasa el token como `Authorization: Bearer ` en las solicitudes de la API. Cuando una solicitud se autentica con un token Bearer válido, API2 considera satisfecha laSignature Authentication y omite la validación de la firma. Signature Authentication solo se aplica a las solicitudes con clave/secreto. Las comprobaciones de alcance siguen aplicándose. Puedes omitir `auth.key` en `params`, pero el contenedor `params` sigue siendo obligatorio para los endpoints que lo esperan. El valor `aud` se almacena para aplicar restricciones de audiencia en el futuro. ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```bash curl --request POST \ --url 'https://api2.transloadit.com/assemblies' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --form 'params={"steps":{}}' ``` ### Autenticación automática de MCP para `/ai/chat` Si tus Steps de `/ai/chat` llaman a un servidor MCP alojado por Transloadit, API2 puede generar e inyectar automáticamente un token Bearer de corta duración (autenticación automática). Esta función debe habilitarse para cada entrada de servidor MCP: ![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_GBjmaCTpH3rF6sBBsH4gkTL4K8CU) ```json { "mcp_servers": [ { "type": "http", "url": "https://api2.transloadit.com/mcp", "auth": "transloadit" } ] } ``` Comportamiento: * Si se establece `auth: "transloadit"` y no hay ningún encabezado `Authorization`, API2 genera un token e inyecta `Authorization: Bearer `. * Si ya se proporciona `Authorization` en `mcp_servers[].headers`, no se modifica. * La autenticación automática solo funciona con hosts de Transloadit (`*.transloadit.com`, `*.transloadit.dev`,`*.transloadit.work`) mediante HTTPS. ## Preguntas frecuentes ### ¿Transloadit incluye firmas en sus solicitudes? Sí, Signature Authentication funciona en ambas direcciones, lo que significa que también proporcionaremos una firma para todas las solicitudes de [Webhooks](/es/docs/topics/webhooks.md) que te enviemos, de modo que puedas verificar la autenticidad de cualquier solicitud que reciban tus servidores. ### ¿Por qué no puedo usar mi Auth Secret como token Bearer? Como parte de los estándares criptográficos, tu Auth Secret nunca debe transmitirse como parte de la solicitud; solo se utiliza como sal para el hash de la firma. Esto garantiza que un actor malicioso no pueda interceptar la solicitud y falsificar solicitudes para tu cuenta mediante tu secreto. Por lo tanto, te recomendamos mantener segura tu Auth Secret almacenándola únicamente en tu back-end y utilizando el sistema de gestión de secretos que prefieras. Algunos ejemplos son [Vault](https://www.vaultproject.io/),[AWS Secrets Manager](https://aws.amazon.com/secrets-manager/),[GCP Secret Manager](https://cloud.google.com/security/products/secret-manager) y[Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/), aunque hay muchas otras opciones que podrían ser adecuadas según la plataforma de back-end que elijas. ###### Nota Debes asegurarte de que las Auth Secrets *nunca* se incluyan como parte del front-end de tu aplicación ni se expongan a los usuarios. ### ¿En qué orden deben aparecer las claves del cuerpo? Puedes elegir cualquier orden para las claves del cuerpo; sin embargo, es importante tener en cuenta que el orden que elijas debe coincidir con el utilizado para generar la firma. El hash generado depende del contenido del JSON, y un orden diferente generará un hash distinto, lo que provocará que se rechace tu solicitud.