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.

{
  "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. 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⁠). Puedes habilitar Signature Authentication desde la Configuración del Workspace.

Con Signature Authentication habilitada, la Auth Secret de tu Workspace (que se encuentra junto a tu Auth Key en la página Credenciales) se utiliza para agregar una sal a un hash generado a partir del cuerpo de la solicitud, que contiene tanto una key (que es tu Auth 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 una firma 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 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.

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:

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  },
  "steps": {
    // …
  }
}

El valor auth.key de este ejemplo es la Auth Key de Credenciales de la API en tu cuenta.

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:

{
  "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⁠ 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:<HMAC-signature>. 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).

La solicitud completa debería ser similar a la siguiente:

{
  "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, que gestionan automáticamente la generación de firmas y se han probado exhaustivamente.

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.

// 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)

const { signature, params } = transloadit.calcSignature({
  template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})

console.log(signature, params)

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.

La generación de una firma de Smart CDN debe realizarse en el back-end. El proceso utiliza la Auth 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:

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 la Auth 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 las unidades de código UTF-16 de las claves en orden ascendente. 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&f=png&f=jpg&h=100.
4. Construye la cadena que se firmará concatenando los valores:

   [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⁠ 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:

   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.

// 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 tu Auth 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.

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)

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

{
  "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).

Uso del token

Pasa el token como Authorization: Bearer <access_token> en las solicitudes de la API. Cuando una solicitud se autentica con un token Bearer válido, API2 considera satisfecha la Signature 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.

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:

{
  "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 <token>.
• 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 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⁠, AWS Secrets Manager⁠, GCP Secret Manager⁠ y Kubernetes Secrets⁠, aunque hay muchas otras opciones que podrían ser adecuadas según la plataforma de back-end que elijas.

¿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.