Transloadit

Autenticación

Auth Keys

Para las solicitudes multipart de creación de Assemblies autenticadas con una Auth Key, incluye un objeto auth dentro del campo de formulario params codificado en JSON. A continuación se muestra el valor mínimo de params para estas solicitudes.

{
  "auth": {
    "key": "23c96d084c744219a2ce156772ec3211"
  }
}

El campo key hace referencia a la Auth Key asociada a tu Workspace de Transloadit, que encontrarás en la página Credenciales. El ejemplo anterior es el objeto de autenticación mínimo para una solicitud de Assembly que utiliza una Auth Key. Otros endpoints y métodos de autenticación pueden utilizar formatos de solicitud diferentes, tal como se describe en la documentación de cada endpoint y a continuación.

Las Assemblies que utilizan /transloadit/import, directamente o a través de un Template, requieren un token Bearer o unos params firmados con una marca de tiempo futura en params.auth.expires. Esto se aplica incluso cuando Signature Authentication está desactivada en el Workspace. Una Auth Key por sí sola no es suficiente; las solicitudes autenticadas con un token Bearer no necesitan una Signature ni una caducidad independientes.

Signature Authentication

Recomendamos activar Signature Authentication en tu cuenta, especialmente si integras Transloadit desde un entorno que no es de confianza (por ejemplo, desde el navegador con Uppy). Puedes activar Signature Authentication desde la Configuración del Workspace.

Con Signature Authentication activada, el Auth Secret de tu Workspace (que encontrarás junto a tu Auth Key en la página Credenciales) se utiliza como clave para un HMAC generado a partir del valor serializado exacto de params. Ese valor contiene tanto un key (que es tu Auth Key, como se ha mencionado antes) como un parámetro expires, que es una marca de tiempo de un futuro cercano utilizada como fecha de caducidad de la solicitud.

Para crear Assemblies con Transloadit, tu backend podría calcular una Signature que solo cubra determinados parámetros, usuarios autenticados y un intervalo de tiempo que considere de uso legítimo. Por ejemplo, se negaría a generar una Signature para los usuarios que no hayan iniciado sesión. Aquí podrías utilizar cualquier lógica de negocio en el servidor para decidir si proporcionas una Signature o no. Transloadit puede exigir una Signature correcta para el contenido cuando una solicitud a la API se autentica con tu Auth Key.

Para exigir Signature Authentication en las solicitudes a la API autenticadas con tu Auth Key:

  1. Ve a la Configuración del Workspace de tu cuenta.
  2. En la sección Configuración de la API, activa la opción Exigir una Signature correcta.
  3. Pulsa el botón Guardar.

Los tokens Bearer válidos eluden los requisitos de Signature, incluidos los de la configuración del Workspace y del Template; los ámbitos del token y las restricciones de audiencia siguen aplicándose. Esta configuración no añade autenticación al acceso basado en capacidades, como las URL de Assembly Status, cancelación o carga reanudable. Mantén privados los IDs de las Assemblies y las URL de capacidad, y sigue las indicaciones de autenticación de cada endpoint.

Cómo generar Signatures

¿Cómo se ve todo esto en la práctica?

El campo params habitual al crear una Assembly sin Signature Authentication es el siguiente:

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

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

Para firmar esta solicitud, hay que añadir el campo adicional auth.expires. Así se incorpora a nuestro contenido, que está protegido por nuestra Signature. Si alguien lo cambiara, Transloadit rechazaría la solicitud porque la Signature ya no coincidiría. Habrías firmado un contenido diferente del que hemos recibido. Si la Signature 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 contenido repita las solicitudes indefinidamente. Aunque nuestro HTTPS con calificación A+ ya debería contribuir en gran medida a impedirlo, la caché del navegador podría ser más fácil de espiar.

La propiedad expires debe contener una marca de tiempo de un futuro (cercano). Utiliza el formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) para la fecha y asegúrate de que la zona horaria sea UTC. Por ejemplo:

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

Para calcular la Signature de esta solicitud:

  1. Desde tu frontend, convierte el objeto JavaScript anterior en una cadena JSON y envíala a tu backend.
  2. Desde tu backend, calcula sobre la cadena una Signature HMAC hexadecimal conforme a RFC 6234, con tu Auth Secret como clave y el algoritmo configurado en signature_algo de tu Auth Key. Las Auth Keys nuevas utilizan sha384 de forma predeterminada. Las Auth Keys antiguas sin un algoritmo configurado aceptan sha384, sha256 o sha1. Añade al principio de la cadena signature el nombre del algoritmo en minúsculas. Por ejemplo, el algoritmo predeterminado utiliza sha384:<HMAC-signature>. Puedes enviar esa cadena a tu frontend (siempre que hayas realizado las comprobaciones adecuadas para garantizar que se trata de una solicitud auténtica de tu frontend).
  3. Desde tu frontend, añade a tu solicitud un campo POST multipart signature que contenga este valor (por ejemplo, con un campo oculto en un formulario HTML).

La solicitud completa debería parecerse a la siguiente:

{
  "params": {
    "auth": {
      "key": "23c96d084c744219a2ce156772ec3211",
      "expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP",
    },
    "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
    "steps": {
      // …
    },
  },
  "signature": "sha384:YOUR_SIGNATURE",
}

Una vez que Transloadit recibe la solicitud, también generamos una Signature siguiendo el mismo proceso y comparamos las dos Signatures. Si las Signatures son diferentes, nuestros servidores responderán con INVALID_SIGNATURE.

En resumen, el proceso es el siguiente:

  1. Genera un contenido JSON para enviarlo a Transloadit como campo params.
  2. Calcula una Signature a partir del contenido, utilizando tu Auth Secret como clave.
  3. Envía la solicitud a Transloadit, pasando la Signature en el campo signature
  4. Transloadit calculará la misma Signature utilizando el Auth Secret de tu cuenta y el contenido enviado.
  5. Si las Signatures coinciden, se permite la solicitud y se envía una respuesta adecuada. De lo contrario, se deniega la solicitud y se devuelve un error con el código INVALID_SIGNATURE.

Esto permite a Transloadit autenticar a quien realiza la llamada y verificar la integridad de params, ya que un tercero no podría calcular una Signature coincidente sin acceso a tu Auth Secret. TLS autentica a Transloadit ante tu cliente y protege la conexión. La firma de webhooks es un flujo independiente para las solicitudes que Transloadit envía a tus servidores.

A continuación se muestran algunos ejemplos de cómo realizar una solicitud POST para crear una Assembly. Recomendamos encarecidamente utilizar uno de nuestros SDK, que gestionan la generación de Signatures automáticamente y están ampliamente probados.

Ejemplos de código para diferentes lenguajes

Los siguientes ejemplos muestran cómo crear Assemblies utilizando nuestros SDK oficiales. Los SDK gestionan internamente toda la generación de Signatures, lo que hace que la integración sea más sencilla y segura.

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

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 Signature por separado (por ejemplo, para utilizarla en el frontend), puedes utilizar calcSignature:

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

console.log(signature, params)

Ver el código fuente de la implementación de Signatures

curl --fail-with-body -sS --location 'https://api2.transloadit.com/assemblies' \
  --form 'params={"auth":{"key":"23c96d084c744219a2ce156772ec3211","expires":"YOUR_FUTURE_ISO_8601_TIMESTAMP"},"template_id":"9cf67cbba601e37ee10c442b037e0"}' \
  --form 'signature=sha384:YOUR_SIGNATURE' \
  --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 Signatures habituales de la API. Se calcula un resumen HMAC sobre una cadena derivada de la URL de Smart CDN, con el Auth Secret como clave. Para que la Signature sea válida, la Auth Key utilizada debe estar habilitada para su uso con Smart CDN.

La generación de una Signature de Smart CDN debe realizarse en el backend. El proceso utiliza el Auth Secret, que es confidencial y no debe exponerse a tus usuarios en el frontend.

Una URL habitual 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 al 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. Añade el parámetro de consulta exp para definir un momento futuro a partir del cual Smart CDN ya no aceptará la Signature. Esto resulta útil para limitar temporalmente el acceso a un archivo. El momento de caducidad se representa mediante el número de milisegundos desde el inicio de la época UNIX (la medianoche al comienzo del 1 de enero de 1970, UTC). Aunque este parámetro es opcional, recomendamos encarecidamente establecer siempre un momento de caducidad. Por ejemplo, una Signature con exp=1722517200000 es válida hasta el jueves, 01 de agosto de 2024 a las 13:00:00 GMT.
  2. Añade el parámetro de consulta auth_key para definir la Auth Key correspondiente al Auth Secret que se utiliza para crear la Signature. Si no se establece este parámetro, la API de Transloadit asume que se ha utilizado para la Signature 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 recomendamos encarecidamente establecerlo. Por ejemplo: auth_key=23c96d084c744219a2ce156772ec3211
  3. Ordena los parámetros de consulta por clave en orden ascendente utilizando unidades de código UTF-16, de la misma forma que URLSearchParams.sort(). La ordenación 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 va a 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 para garantizar que solo contengan caracteres seguros para URL. Ten en cuenta que la cadena no comienza con una barra. Debes omitir el carácter ? si [sorted-parameters] está vacío.
  5. Calcula una Signature HMAC hexadecimal conforme a RFC 6234 sobre la cadena que se va a firmar, con tu Auth Secret como clave y SHA256 como algoritmo hash. Añade a la Signature hexadecimal el prefijo del nombre del algoritmo en minúsculas seguido de dos puntos, es decir, sha256:. Por ejemplo, para SHA256, utiliza sha256:[hmac-signature].
  6. Añade la Signature hexadecimal con su prefijo a la URL bajo 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 para garantizar que solo contengan caracteres seguros para URL. Después, esta URL firmada puede enviarse a tu frontend o utilizarse en él hasta que se alcance la fecha de caducidad.

Seguridad y tiempo de vida de la caché

Las URL firmadas de Smart CDN no son solo un mecanismo de control de acceso. Su caducidad también determina durante cuánto tiempo un resultado recién generado puede seguir siendo apto para almacenarse en caché.

  • Los valores de exp más cortos reducen la ventana de repetición y refuerzan el control de acceso.
  • Los valores de exp más largos aumentan la reutilización de la caché, reducen el trabajo en el servidor de origen y, por lo general, disminuyen la latencia y el volumen de codificación.
  • En la práctica, el tiempo de vida efectivo en caché de una respuesta firmada de Smart CDN está limitado por el tiempo de validez restante de la Signature.

Esto significa que la relación entre ambas opciones es sencilla:

  • Mayor sensibilidad en materia de seguridad: utiliza 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 coste: utiliza un exp más largo, lo que también implica que la URL seguirá siendo utilizable durante más tiempo.

Elige el intervalo de caducidad 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 intervalo de caducidad moderado ofrece un buen equilibrio. Para contenido muy sensible, utiliza uno mucho más corto.

Ejemplos de código

A continuación encontrarás ejemplos en diferentes lenguajes para generar URL firmadas de Smart CDN utilizando nuestros SDK.

// yarn add @transloadit/node
// or
// npm install --save @transloadit/node

import { Transloadit } from '@transloadit/node'

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)

Acceso de lectura tras la cancelación

Los Workspaces cancelados no pueden crear nuevos tokens Bearer. Los endpoints que permiten explícitamente el acceso tras la cancelación enlazan a esta guía. Utiliza una Auth Key activa existente y su Auth Secret; la clave debe seguir concediendo los ámbitos indicados para el endpoint. Esto no restablece el acceso de escritura ni hace que otros endpoints estén disponibles tras la cancelación.

En un proyecto Node.js de confianza que se ejecute en el servidor, instala el SDK con yarn add @transloadit/node. Establece TRANSLOADIT_KEY y TRANSLOADIT_SECRET, y después establece TRANSLOADIT_URL con la URL HTTPS completa que se muestra en la página del endpoint, sustituyendo los parámetros de ruta por los valores de tu recurso. Mantén privadas ambas credenciales, la URL firmada y la respuesta. Nunca ejecutes esta configuración en código de navegador.

El SDK firma params con sha384, el algoritmo predeterminado para las Auth Keys nuevas, y proporciona la caducidad. El ejemplo añade un nonce nuevo para evitar la reutilización de Signatures. Si tu clave utiliza otro algoritmo de Signature, pásalo como segundo argumento a calcSignature. Coloca los filtros del endpoint dentro del objeto que pasas como primer argumento, junto al nonce. El SDK no llama a /token para esta guía.

Guarda esto como read-api.mjs y ejecuta node read-api.mjs:

import { randomUUID } from 'node:crypto'

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_URL } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_URL) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_URL')
}
const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})
const { params, signature } = transloadit.calcSignature({ nonce: randomUUID() })
const url = new URL(TRANSLOADIT_URL)
url.searchParams.set('params', params)
url.searchParams.set('signature', signature)
const response = await fetch(url, { redirect: 'error' })
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const result = await response.json()
if (result.error) throw new Error(result.error)
console.log(JSON.stringify(result, null, 2))

Tokens Bearer (credenciales de cliente)

Si necesitas un token de corta duración para clientes de servidor a servidor o sin interfaz, puedes intercambiar tu Auth Key y tu Auth Secret por un token Bearer. Esto reproduce un flujo client_credentials de OAuth 2.0, pero lo gestiona directamente la API de Transloadit. Para consultar la referencia completa del endpoint, consulta la documentación de la API /token.

Uso del token

Pasa el token como Authorization: Bearer <access_token> en las solicitudes a la API. Cuando una solicitud se autentica con un token Bearer válido, API2 considera que Signature Authentication se ha satisfecho y omite la validación de la Signature. Signature Authentication solo se exige en las solicitudes con clave y secreto. Las comprobaciones de ámbitos y audiencia siguen aplicándose. El servidor MCP acepta la audiencia mcp, y los endpoints habituales de API2 la rechazan. Puedes omitir auth.key en params, pero la envoltura params sigue siendo obligatoria para los endpoints que la esperan.

curl --fail-with-body -sS --request POST \
  --url 'https://api2.transloadit.com/assemblies' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --form 'params={"template_id":"YOUR_TEMPLATE_ID"}'

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 emitir e inyectar automáticamente un token Bearer de corta duración (autenticación automática). Esta función se activa de forma explícita 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 ninguna cabecera Authorization, API2 emite un token e inyecta Authorization: Bearer <token>.
  • Si ya se proporciona Authorization en mcp_servers[].headers, se deja sin cambios.
  • La autenticación automática solo funciona mediante HTTPS para los hosts de dominio raíz y subdominios gestionados por Transloadit: transloadit.com, *.transloadit.com, transloadit.dev, *.transloadit.dev, transloadit.website, *.transloadit.website, transloadit.work, *.transloadit.work.
  • La URL debe utilizar el puerto 443 y la ruta exacta /mcp o una subruta dentro de /mcp/.
  • La URL no debe contener credenciales, una cadena de consulta ni un fragmento.
  • La Auth Key debe conceder al menos uno de estos ámbitos seguros de MCP: assemblies:write, assemblies:read, templates:read.
  • El token emitido se limita a la intersección de esos ámbitos seguros de MCP y los ámbitos de la Auth Key; nunca obtiene un ámbito que la Auth Key no conceda.

Preguntas frecuentes

¿Transloadit incluye Signatures en sus solicitudes?

Transloadit firma las solicitudes de webhook para que tu servidor pueda verificar su autenticidad. La firma de webhooks es independiente del HMAC que autentica las solicitudes a la API enviadas a Transloadit.

¿Por qué no puedo utilizar mi Auth Secret como token Bearer?

Salvo en el intercambio de tokens de servidor a servidor descrito anteriormente, tu Auth Secret no debe transmitirse nunca a un cliente ni incluirse en los parámetros de las solicitudes a la API. POST /token lo envía como contraseña de HTTP Basic mediante HTTPS y solo debe llamarse desde tu backend. Para las solicitudes firmadas, el secreto permanece en tu backend y se utiliza como clave HMAC. Esto impide que un actor malicioso intercepte una solicitud firmada y falsifique solicitudes a tu cuenta. Mantén tu Auth Secret seguro utilizando el sistema de gestión de secretos que prefieras. Algunos ejemplos son: Vault, AWS Secrets Manager, GCP Secret Manager y Kubernetes Secrets, pero hay muchos más que podrían ser adecuados según la plataforma de backend que elijas.

¿En qué orden deben aparecer las claves del cuerpo?

El orden que elijas para las claves del cuerpo puede ser arbitrario, pero ten en cuenta que cualquier orden que elijas debe ser coherente con la generación de tu Signature. El hash generado depende del contenido del JSON, y un orden diferente generará un hash diferente, lo que significa que se denegará tu solicitud.