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 params más pequeño de este tipo.
{
"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. Lo anterior es el objeto de autenticación mínimo para
una solicitud de Assembly que usa una Auth Key. Otros endpoints y métodos de autenticación pueden usar
formatos de solicitud diferentes, como se describe en la documentación de cada endpoint y más abajo.
Las Assemblies que usan /transloadit/import, directamente o mediante un Template, requieren
un token Bearer o params firmados con una marca de tiempo params.auth.expires futura.
Esto se aplica incluso cuando la Signature Authentication del Workspace está desactivada. Una Auth Key por sí sola
no es suficiente; las solicitudes autenticadas con token Bearer no necesitan una firma ni una caducidad aparte.
Los Builtin Templates públicos de Storage son la excepción: pueden atender solicitudes sin firmar solo
cuando cada importación de Storage permanece dentro de un prefijo público declarado. Esto no autoriza
Assemblies sin firmar con Steps arbitrarios ni el acceso a rutas privadas de Storage.
Signature Authentication
Te recomendamos activar la Signature Authentication en tu cuenta, sobre todo si integras Transloadit desde un entorno no confiable (como desde el navegador con Uppy). Puedes activar la Signature Authentication desde la Configuración del Workspace.
Te recomendamos encarecidamente activar la Signature Authentication al interactuar con nuestra API, en particular en entornos no confiables donde los usuarios podrían acceder a tu Auth Key.
Con la Signature Authentication activada, el Auth Secret de tu Workspace (que se encuentra
junto a tu Auth Key en la página Credenciales) se
usa como clave para un HMAC generado a partir de la serialización exacta, byte a byte, del valor params. Ese valor contiene tanto una key (que es tu
Auth Key, como se mencionó antes) como un parámetro expires, que es una marca de tiempo en el futuro
cercano usada como fecha de caducidad de la solicitud.
Para crear Assemblies con Transloadit, tu back-end podría calcular una firma que solo cubra ciertos parámetros, usuarios autenticados y un intervalo de tiempo que considere uso legítimo. Por ejemplo, se negaría a generar una firma para usuarios que no hayan iniciado sesión. Aquí podrías usar cualquier lógica de negocio en el servidor para decidir si entregas una firma o no. Transloadit puede exigir una firma correcta para la carga útil cuando una solicitud de API se autentica con tu Auth Key.
Para exigir la Signature Authentication en las solicitudes de API autenticadas con tu Auth Key:
- Ve a la Configuración del Workspace de tu cuenta.
- En la sección de configuración de la API, activa la opción Requerir una Signature correcta.
- Espera a que se complete el guardado automático.
Los tokens Bearer válidos omiten los requisitos de firma, incluida la configuración del Workspace y del Template; los ámbitos y las restricciones de audiencia del token se siguen aplicando. Esta configuración no añade autenticación al acceso basado en capacidades, como las URLs de estado o cancelación de una Assembly o las URLs de carga reanudable. Mantén privados los IDs de las Assemblies y las URLs de capacidad, y sigue las indicaciones de autenticación de cada endpoint.
La mayoría de los SDKs de back-end usan automáticamente la Signature Authentication cuando proporcionas tu Auth Secret. Así que quizá esta introducción sea todo lo que necesitas saber. Sin embargo, si integras Transloadit en entornos no confiables, como navegadores (Uppy!), te conviene seguir leyendo para ver cómo tu back-end puede proporcionarles firmas.
Cómo generar firmas
Entonces, ¿cómo se ve todo esto?
El campo params típico al crear una Assembly sin Signature Authentication
es el siguiente:
{
"auth": {
"key": "23c96d084c744219a2ce156772ec3211"
},
"steps": {
// …
}
}
La auth.key de este ejemplo es la Auth Key de
las credenciales de API de tu cuenta.
Para firmar esta solicitud, hay que añadir el campo adicional auth.expires. Esto lo añade a nuestra
carga útil, que está protegida por nuestra firma. Si alguien lo modificara, Transloadit rechazaría
la solicitud porque la firma ya no coincidiría: habrías firmado una carga útil distinta de la que
recibimos. Si la firma coincide, naturalmente compararemos la fecha y rechazaremos la solicitud según lo
indicado. Así, a un tercero que se haya hecho con esta carga útil le resultará muy difícil repetir
las solicitudes indefinidamente. Porque, aunque nuestro HTTPS con calificación A+ ya debería contribuir mucho a
evitarlo, la caché del navegador podría ser más fácil de espiar.
La propiedad expires debe contener una marca de tiempo en el futuro (cercano). Usa el formato ISO 8601
(YYYY-MM-DDTHH:mm:ss.sssZ) para la fecha y asegúrate de usar UTC como zona horaria. Por
ejemplo:
{
"auth": {
"key": "23c96d084c744219a2ce156772ec3211",
"expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP"
},
"steps": {
// …
}
}
Para calcular la firma de esta solicitud:
- Desde tu front-end, convierte el objeto JavaScript anterior en una cadena JSON y envíala a tu back-end.
- Desde tu back-end, calcula una firma HMAC hexadecimal conforme a RFC 6234
sobre la cadena, con tu Auth Secret como clave y el algoritmo
configurado en el
signature_algode tu Auth Key, o un algoritmo más fuerte. Las Auth Keys nuevas usansha384de forma predeterminada. Una configuración explícita es un mínimo para las firmas de solicitudes de API, del más débil al más fuerte:sha1→sha256→sha384→sha512. Una clavesha256aceptasha256,sha384ysha512con prefijo, pero rechazasha1y los digests sin prefijo. Las firmas heredadas sin prefijo mantienen sus restricciones existentes de algoritmo exacto; la aceptación de algoritmos más fuertes requiere un prefijo. Las Auth Keys heredadas sin un algoritmo configurado aceptansha384,sha256osha1. Ese comportamiento sin fijar no cambia y no incluyesha512. Antepón a la cadenasignatureel nombre del algoritmo en minúsculas. Por ejemplo, el algoritmo predeterminado usasha384:<HMAC-signature>. Puedes enviar esa cadena a tu front-end (siempre que hayas hecho las comprobaciones adecuadas para garantizar que se trataba de una solicitud genuina de tu front-end). - Desde tu front-end, añade a tu solicitud un campo POST multipart
signatureque contenga este valor (por ejemplo, con un campo oculto en un formulario HTML).
Si tu implementación usa un template_id en lugar de steps, no es necesario
generar una firma para las Instructions que contiene tu Template. Solo
debemos firmar las cargas útiles de comunicación.
Te recomendamos encarecidamente incluir un valor params.nonce generado aleatoriamente para cada solicitud
en el nivel superior de params. Esto hace que las firmas generadas de forma independiente sean distintas y evita la
reutilización accidental de firmas. Un nonce no hace que los reintentos sean idempotentes: reintentar una solicitud de creación de Assembly
puede crear otra Assembly. Gestiona la deduplicación de reintentos en tu aplicación cuando sea necesario.
No reutilices params firmados entre endpoints. Las lecturas de Templates, el listado de Auth Keys, el listado de
credenciales de Template y las lecturas de facturación rechazan las firmas ya registradas para un endpoint diferente o usadas
para crear una Assembly, con SIGNATURE_REUSE_DETECTED. Genera params firmados nuevos para cada solicitud.
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 firma siguiendo el mismo
proceso y comparamos ambas firmas. Si las firmas son diferentes, nuestros servidores
responderán con INVALID_SIGNATURE.
En resumen, el proceso es el siguiente:
- Genera una carga útil JSON para enviarla a Transloadit como el campo
params. - Calcula una firma basada en el contenido de la carga útil, usando tu Auth Secret como clave.
- Envía la solicitud a Transloadit, con la firma en el campo
signature - Transloadit calculará la misma firma usando el Auth Secret de tu cuenta y el contenido de la carga útil.
- Si las firmas coinciden, la solicitud se permite y se envía una respuesta adecuada.
De lo contrario, la solicitud se deniega y se devolverá un error con el código
INVALID_SIGNATURE.
Esto permite a Transloadit autenticar a quien llama y verificar la integridad de params, ya que un tercero
no podría calcular una firma 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 encontrarás algunos ejemplos de cómo realizar una solicitud POST para crear una Assembly. Te recomendamos encarecidamente usar uno de nuestros SDKs, que gestionan la generación de firmas automáticamente y están bien probados.
Los webhooks se firman de forma distinta a las solicitudes de API.
Transloadit firma la cadena JSON exacta del campo de formulario transloadit usando
HMAC-SHA1 y el Auth Secret aplicable. El campo signature contiene
el digest hexadecimal sin prefijo de algoritmo. Sigue las
instrucciones de verificación de webhooks, incluido cómo seleccionar el Auth Secret,
en lugar de usar los ejemplos de firma de solicitudes de API que aparecen más abajo.
Código de ejemplo para distintos lenguajes
Los ejemplos siguientes muestran cómo crear Assemblies con nuestros SDKs oficiales. Los SDKs gestionan internamente toda la generación de firmas, 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 firma por separado (por ejemplo, para usarla en el front-end), puedes usar
calcSignature:
const { signature, params } = transloadit.calcSignature({
template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})
console.log(signature, params)
Si prefieres ver los detalles de la implementación de la firma sin procesar (por ejemplo, para implementar la firma en un
lenguaje para el que no tenemos SDK), consulta los enlaces al código fuente anteriores. La firma es un
digest HMAC hexadecimal conforme a RFC 6234 calculado sobre la
cadena de params codificada en JSON, usando tu Auth Secret como
clave y un algoritmo al menos tan fuerte como el mínimo configurado en el signature_algo de tu Auth Key. Las Auth Keys nuevas usan
sha384 de forma predeterminada. Antepón a la firma el nombre de su algoritmo en minúsculas
(por ejemplo, sha384:...).
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'
URLs firmadas de Smart CDN
Para firmar una URL de Smart CDN se usa un proceso similar al de las firmas de API normales. Se calcula un digest HMAC sobre una cadena derivada de la URL de Smart CDN, con el Auth Secret como clave. Para que la firma sea válida, la Auth Key usada debe estar habilitada para el uso de Smart CDN.
Para generar una URL firmada de Smart CDN, usa la Auth Key designada para el uso de Smart CDN en tu
página de credenciales. Las URLs de Smart CDN requieren sha256. Las firmas de las solicitudes de API
normales pueden usar un algoritmo con prefijo al menos tan fuerte como el signature_algo de la Auth Key; las Auth Keys nuevas usan
sha384 de forma predeterminada.
Las firmas heredadas de Smart CDN basadas en s= y expires= están obsoletas. Las integraciones nuevas
siempre deben usar sig= con exp=.
La generación de una firma de Smart CDN debe realizarse en el back-end. El proceso usa el 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 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:
- Añade el parámetro de consulta
exppara definir un momento futuro a partir del cual la Smart CDN ya no acepta la firma. Esto es útil para limitar temporalmente el acceso a un archivo. El momento de caducidad se representa como el número de milisegundos desde la época UNIX (la medianoche del inicio del 1 de enero de 1970, UTC). Aunque este parámetro es opcional, te recomendamos encarecidamente establecer siempre una hora de caducidad. Por ejemplo, una firma conexp=1722517200000es válida hasta el jueves 1 de agosto de 2024 a las 13:00:00 GMT. - Añade el parámetro de consulta
auth_keypara definir la Auth Key correspondiente al Auth Secret que se usa para crear la firma. Si este parámetro no se establece, la API de Transloadit asume que para la firma se ha usado el par de Auth Key más antiguo habilitado para Smart CDN. Establecer los parámetrosauth_keyte permite rotar tu Auth Key sin interrumpir a tus usuarios, por lo que te recomendamos encarecidamente establecerlo. Por ejemplo:auth_key=23c96d084c744219a2ce156772ec3211 - Ordena los parámetros de consulta por clave en orden ascendente usando unidades de código UTF-16, igual 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=123se ordena comoauth_key=hello&exp=123&f=png&f=jpg&h=100. - Construye la cadena que se va a firmar concatenando los valores:
Los valores de
[your-workspace]/[template-name]/[file-path]?[sorted-parameters][your-workspace],[template-name]y[file-path]deben estar codificados como URL para garantizar que solo contengan caracteres seguros para URL. Ten en cuenta que la cadena no empieza con una barra inicial. El carácter?debe omitirse si[sorted-parameters]está vacío. - Calcula una firma 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.
Antepón a la firma hexadecimal el nombre del algoritmo en minúsculas y dos puntos, es decir,
sha256:. Por ejemplo, para SHA256, usasha256:[hmac-signature]. - Añade a la URL la firma hexadecimal con prefijo en el parámetro de consulta
sig, lo que da como resultado la URL firmada de Smart CDN:Los valores dehttps://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature][your-workspace],[template-name]y[file-path]deben estar codificados como URL para garantizar que solo contengan caracteres seguros para URL. Después, puedes enviar esta URL firmada a tu front-end o usarla allí hasta que se alcance la fecha de caducidad.
Seguridad y vida útil de la caché
Las URLs firmadas de Smart CDN no son solo un mecanismo de control de acceso. Su caducidad también determina durante cuánto tiempo puede seguir siendo almacenable en caché un resultado recién generado.
- Los valores de
expmás cortos reducen la ventana de repetición y refuerzan el control de acceso. - Los valores de
expmás largos aumentan la reutilización de la caché, reducen el trabajo en el origen y, en general, disminuyen la latencia y el volumen de codificación. - En la práctica, la vida útil efectiva en caché de una respuesta firmada de Smart CDN está limitada por la vida útil restante de la firma.
Esto significa que la disyuntiva es sencilla:
- Mayor sensibilidad de seguridad: usa un
expmá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
expmás largo, lo que también implica que la URL sigue siendo utilizable durante más tiempo.
Elige la ventana de caducidad según la sensibilidad del contenido y la reutilización de la caché que quieras. Para muchos casos de uso de imágenes y vistas previas, una ventana de caducidad moderada ofrece un buen equilibrio. Para contenido muy sensible, usa una mucho más corta.
Código de ejemplo
A continuación encontrarás ejemplos en distintos lenguajes para generar URLs firmadas de Smart CDN con nuestros SDKs.
// 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 después de la cancelación
Los Workspaces cancelados no pueden crear tokens Bearer nuevos. Los endpoints que permiten explícitamente el acceso después de la cancelación enlazan a esta guía. Usa una Auth Key activa existente y su Auth Secret; la clave debe seguir otorgando los ámbitos indicados para el endpoint. Esto no restablece el acceso de escritura ni hace que otros endpoints estén disponibles después de la cancelación.
En un proyecto Node.js de confianza del lado del servidor, instala el SDK con yarn add @transloadit/node.
Establece TRANSLOADIT_KEY y TRANSLOADIT_SECRET y, a continuación, establece TRANSLOADIT_URL en la URL HTTPS
completa que aparece 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 del navegador.
El SDK firma params con sha384, el valor predeterminado para las Auth Keys nuevas, y proporciona la caducidad.
El ejemplo añade un nonce nuevo para evitar la reutilización de firmas. Si tu clave usa otro algoritmo
de firma, pásalo como segundo argumento a calcSignature. Coloca los filtros del endpoint dentro
del objeto que se pasa como primer argumento, junto al nonce.
El SDK no llama a /token en 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))
Conectar un cliente MCP por URL
Los clientes de agentes como ChatGPT, Codex, Claude.ai, Claude Desktop, Claude Code y Cursor se conectan
al servidor MCP alojado en https://api2.transloadit.com/mcp solo con esa URL. La API de Transloadit
es un servidor de autorización OAuth 2.1 para él: el cliente descubre los endpoints, se identifica,
te envía a la consola para iniciar sesión y dar tu consentimiento, y obtiene un token Bearer de corta duración
para la audiencia mcp más un token de actualización. Ningún Auth Secret sale nunca de tu cuenta.
- Descubrimiento. El servidor MCP responde a las solicitudes no autenticadas con
401y un encabezadoWWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". Ese documento RFC 9728 indicahttps://api2.transloadit.comcomo servidor de autorización, cuyos metadatos RFC 8414 enhttps://api2.transloadit.com/.well-known/oauth-authorization-serverenumeran los endpoints siguientes. - Identificación del cliente. Presenta un
Client ID Metadata Document:
una URL HTTPS que es el
client_idy sirve JSON con el mismoclient_id, unclient_namey lasredirect_uris. O regístrate una vez mediante el registro dinámico de clientes RFC 7591 enhttps://api2.transloadit.com/oauth/register; los clientes envían solo suclient_id(token_endpoint_auth_method: "none", también cuando se omite), se autentican con un secreto de cliente (client_secret_basicoclient_secret_post), o se autentican conprivate_key_jwty unjwks_uri. La respuesta incluye unclient_idopaco, más unclient_secretpara los métodos con secreto, que solo se muestra en esa respuesta. Las URIs de redirección deben ser URLs HTTPS, con coincidencia exacta, o URLs de loopbackhttp://localhost/http://127.0.0.1, con coincidencia en cualquier puerto. Un cliente registrado con un secreto lo envía en cada solicitud de token y de revocación, mediante HTTP Basic o comoclient_idyclient_secreten el formulario. Las demás solicitudes de token autentican al cliente connoneoprivate_key_jwt, según lo que indique su documento (entoken_endpoint_auth_methods_supported, o en su defecto comotoken_endpoint_auth_method) o lo que declare su registro. La primera solicitud de token vincula la concesión al método que usó: una vez que una solicitud para una concesión incluye unclient_assertionde RFC 7523, todas las solicitudes posteriores de token y revocación para ella también deben incluir uno. Esa aserción es un JWT firmado (RS256 o ES256) con una clave deljwks_uridel cliente, con el ID de cliente comoissysub. Suaudes una URL del endpoint de token configurada o su origen (sin barra final) para este despliegue. Tiene unexpdentro de cinco minutos y unjtique se acepta una vez por cliente y por región mientras la aserción siga siendo válida. Usa unjtinuevo para cada solicitud. - Consentimiento. El cliente abre
https://transloadit.com/c/oauth/authorizeconresponse_type=code, suclient_id,redirect_uri, uncode_challengePKCE (soloS256), opcionalmentescopeystate, yresource=https://api2.transloadit.com/mcp. Inicias sesión, eliges un Workspace y apruebas; la consola redirige el navegador de vuelta concode, tustateeiss=https://api2.transloadit.com. El código está vinculado al cliente, al URI de redirección, al desafío y al Workspace, y caduca después de 120 segundos. - Tokens. El cliente envía mediante POST
grant_type=authorization_codeconcode,code_verifier,client_idyredirect_uriahttps://api2.transloadit.com/tokeny recibe unaccess_token(válido durante 604.800 segundos, 7 días, de forma predeterminada), suscopey unrefresh_token. Enviargrant_type=refresh_tokenconrefresh_tokenyclient_iddevuelve un nuevo par y retira el token de actualización presentado; los tokens de actualización duran 30 días y reutilizar uno retirado revoca todo el linaje. Los clientes que se autentican con un secreto de cliente reciben en cambio el mismo token de actualización, válido durante otros 30 días a partir de esa actualización. - Revocación. Envía mediante POST
token(un token de acceso o de actualización) ahttps://api2.transloadit.com/oauth/revokesegún RFC 7009, o revoca la conexión en la consola.
El indicador resource (RFC 8707) decide para qué sirve el
token. resource=https://api2.transloadit.com/mcp (el valor predeterminado cuando se omite) genera un token mcp que
incluye como máximo los ámbitos MCP seguros (assemblies:write, assemblies:read, templates:read), limitados a lo que otorga la
Auth Key del Workspace, y que solo acepta el servidor MCP. resource=https://api2.transloadit.com (con o
sin barra final) genera un token api2 para aplicaciones que llaman directamente a la REST API,
como las integraciones de Vercel Connect: incluye los
ámbitos solicitados limitados a los ámbitos de la Auth Key, o todo lo que otorga la clave cuando se omite scope,
salvo que una concesión nunca incluye la gestión de Auth Keys ni de credenciales de Template
(auth_keys:*, template_credentials:*, ni los globales read/write que las implican), por lo que no puede
crear ni revelar credenciales duraderas. Cualquier otro resource responde con invalid_target.
Los errores del protocolo OAuth del registro de clientes, la autorización y la revocación usan
el cuerpo estándar con error y error_description; los límites de frecuencia pueden devolver RATE_LIMIT_REACHED.
En /token, los errores de concesión OAuth para authorization_code y refresh_token usan el cuerpo estándar
con error y error_description. Los límites de frecuencia devuelven RATE_LIMIT_REACHED (429), y
los fallos internos inesperados devuelven SERVER_500 (500). Las solicitudes mal formadas que se rechazan
antes de identificar la concesión pueden recibir un desafío HTTP Basic (401), o
TOKEN_INVALID_REQUEST si se proporcionaron credenciales Basic.
Tokens Bearer (credenciales de cliente)
Los trabajos de CI, los servidores y otros clientes sin interfaz que tienen una
Auth Key y un Auth Secret los intercambian por un token Bearer de corta duración
con la concesión client_credentials de OAuth 2.0, que gestiona directamente la API de Transloadit. Usa esto cuando no haya un navegador
en el que dar el consentimiento; los clientes MCP interactivos deben conectarse por URL como se describe arriba. Para 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 de 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. La Signature Authentication solo se aplica a las solicitudes con clave/secreto.
Las comprobaciones de ámbito y audiencia se siguen aplicando. La audiencia mcp la acepta el servidor MCP, que
la retransmite a API2 con una credencial de servicio; se rechaza cuando se presenta directamente a los endpoints
normales de API2. Puedes omitir auth.key en params, pero el envoltorio params sigue siendo obligatorio
para los endpoints que lo 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 generar e inyectar automáticamente un token Bearer
de corta duración (auto-auth). Esto se activa de forma opcional en 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 encabezadoAuthorization, API2 genera un token e inyectaAuthorization: Bearer <token>. - Si ya se proporciona
Authorizationenmcp_servers[].headers, no se modifica. - La autenticación automática solo funciona mediante HTTPS para los dominios apex y subdominios gestionados por Transloadit:
transloadit.com,*.transloadit.com,transloadit.dev,*.transloadit.dev,transloadit.website,*.transloadit.website,transloadit.work,*.transloadit.work. - La URL debe usar el puerto
443y la ruta exacta/mcpo una subruta bajo/mcp/. - La URL no debe contener credenciales, una cadena de consulta ni un fragmento.
- La Auth Key debe otorgar al menos uno de estos ámbitos MCP seguros:
assemblies:write,assemblies:read,templates:read. - El token generado se limita a la intersección de esos ámbitos MCP seguros y los ámbitos de la Auth Key; nunca obtiene un ámbito que la Auth Key no otorgue.
Preguntas frecuentes
¿Transloadit incluye firmas 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 de API enviadas a Transloadit.
¿Por qué no puedo usar mi Auth Secret como token Bearer?
Salvo en el intercambio de tokens de servidor a servidor descrito arriba, tu Auth Secret nunca
debe transmitirse a un cliente ni incluirse en los parámetros de las solicitudes de API. POST /token lo envía como
contraseña de HTTP Basic mediante HTTPS y solo debe llamarse desde tu back-end. En las solicitudes firmadas,
el secreto permanece en tu back-end y se usa como clave HMAC. Esto impide que un actor malintencionado
intercepte una solicitud firmada y suplante solicitudes a tu cuenta. Mantén seguro tu Auth Secret usando
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 back-end que elijas.
Debes asegurarte de que los Auth Secrets nunca se incluyan como parte del front-end de tu aplicación ni se expongan a los usuarios.
¿En qué orden deben estar las claves del cuerpo?
El orden que elijas para las claves del cuerpo puede ser arbitrario; sin embargo, es importante tener en cuenta que el orden que elijas debe ser coherente con la generación de tu firma. El hash generado depende del contenido del JSON, y un orden diferente generará un hash diferente, lo que significa que tu solicitud será denegada.