Autenticação
Auth Keys
Em solicitações multipart de criação de Assembly autenticadas com uma Auth Key, inclua um objeto auth
dentro do campo de formulário params codificado em JSON. O menor valor de params desse tipo é mostrado abaixo.
{
"auth": {
"key": "23c96d084c744219a2ce156772ec3211"
}
}
O campo key se refere à Auth Key associada ao seu Workspace da Transloadit, disponível
na página Credenciais. O exemplo acima é o objeto de autenticação mínimo para
uma solicitação de Assembly que usa uma Auth Key. Outros endpoints e métodos de autenticação podem usar
formatos de solicitação diferentes, conforme descrito na documentação de cada endpoint e abaixo.
As Assemblies que usam /transloadit/import, diretamente ou por meio de um Template, exigem
um token bearer ou params assinados com um timestamp params.auth.expires no futuro.
Isso vale mesmo quando a Signature Authentication do Workspace está desativada. Uma Auth Key sozinha
não é suficiente; solicitações autenticadas com token bearer não precisam de assinatura nem de expiração separadas.
Os Builtin Templates públicos do Storage são a exceção: eles podem atender a solicitações não assinadas somente
quando cada importação do Storage permanece dentro de um prefixo público declarado. Isso não autoriza
Assemblies não assinadas com Steps arbitrários nem o acesso a caminhos privados do Storage.
Signature Authentication
Recomendamos ativar a Signature Authentication na sua conta, principalmente se você estiver integrando a Transloadit a partir de um ambiente não confiável (como o navegador, com o Uppy). Você pode ativar a Signature Authentication nas Configurações do Workspace.
Recomendamos fortemente ativar a Signature Authentication ao interagir com a nossa API, especialmente em ambientes não confiáveis em que os usuários possam acessar a sua Auth Key.
Com a Signature Authentication ativada, o Auth Secret do seu Workspace (que fica
ao lado da sua Auth Key na página Credenciais) passa
a ser usado como chave de um HMAC gerado a partir dos bytes exatos do valor serializado de params. Esse valor contém tanto uma key (que é a sua
Auth Key, como mencionado antes) quanto um parâmetro expires, que é um timestamp no futuro
próximo usado como data de expiração da solicitação.
Para criar Assemblies com a Transloadit, o seu back-end pode calcular uma assinatura que cubra apenas determinados parâmetros, usuários autenticados e um intervalo de tempo que ele considere uso legítimo. Por exemplo, ele se recusaria a gerar uma assinatura para usuários que não estão logados. Você pode usar qualquer lógica de negócio no servidor para decidir se entrega uma assinatura ou não. A Transloadit pode exigir uma assinatura correta para o payload quando uma solicitação de API é autenticada com a sua Auth Key.
Para exigir Signature Authentication em solicitações de API autenticadas com a sua Auth Key:
- Acesse as Configurações do Workspace na sua conta.
- Na seção Configurações da API, ative a opção Exigir uma assinatura correta.
- Aguarde a conclusão do salvamento automático.
Tokens bearer válidos dispensam os requisitos de assinatura, incluindo as configurações do Workspace e do Template; os escopos do token e as restrições de audiência continuam valendo. Essas configurações não adicionam autenticação ao acesso baseado em capacidade, como as URLs de Assembly Status, de cancelamento ou de upload retomável. Mantenha os Assembly IDs e as URLs de capacidade em sigilo e siga as orientações de autenticação de cada endpoint.
A maioria dos SDKs de back-end usa a Signature Authentication automaticamente quando você fornece o seu Auth Secret. Então talvez esta introdução seja tudo o que você precisa saber. Porém, se você estiver integrando a Transloadit em ambientes não confiáveis, como navegadores (Uppy!), continue lendo para ver como o seu back-end pode fornecer assinaturas a eles.
Como gerar assinaturas
Então, como tudo isso fica na prática?
O campo params típico ao criar uma Assembly sem Signature Authentication
é o seguinte:
{
"auth": {
"key": "23c96d084c744219a2ce156772ec3211"
},
"steps": {
// …
}
}
O auth.key neste exemplo é a Auth Key das
credenciais de API na sua conta.
Para assinar esta solicitação, é preciso adicionar o campo auth.expires. Isso o inclui no nosso
payload, que é protegido pela nossa assinatura. Se alguém alterá-lo, a Transloadit rejeitará
a solicitação, pois a assinatura não corresponde mais: você assinou um payload diferente daquele que
recebemos. Se a assinatura corresponder, naturalmente compararemos a data e rejeitaremos conforme
instruído. Assim, fica muito difícil para um terceiro que tenha obtido esse payload repetir as
solicitações indefinidamente. Afinal, embora o nosso HTTPS com nota A+ já ajude muito a
evitar isso, o cache do navegador pode ser mais fácil de bisbilhotar.
A propriedade expires deve conter um timestamp no futuro (próximo). Use o formato ISO 8601
(YYYY-MM-DDTHH:mm:ss.sssZ) para a data, garantindo que o fuso horário seja UTC. Por
exemplo:
{
"auth": {
"key": "23c96d084c744219a2ce156772ec3211",
"expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP"
},
"steps": {
// …
}
}
Para calcular a assinatura desta solicitação:
- No front-end, converta o objeto JavaScript acima em uma string JSON e envie-a ao seu back-end.
- No back-end, calcule uma assinatura HMAC hexadecimal compatível com o RFC 6234
sobre a string, usando o seu Auth Secret como chave e o algoritmo
configurado no
signature_algoda sua Auth Key, ou um algoritmo mais forte. Novas Auth Keys usamsha384por padrão. Uma configuração explícita é um mínimo para assinaturas de solicitações de API, do mais fraco ao mais forte:sha1→sha256→sha384→sha512. Uma chavesha256aceitasha256,sha384esha512com prefixo, mas rejeitasha1e digests sem prefixo. Assinaturas legadas sem prefixo mantêm as restrições existentes de algoritmo exato; a aceitação de algoritmos mais fortes exige um prefixo. Auth Keys legadas sem algoritmo configurado aceitamsha384,sha256ousha1. Esse comportamento sem algoritmo fixado não mudou e não incluisha512. Prefixe a stringsignaturecom o nome do algoritmo em letras minúsculas. Por exemplo, o algoritmo padrão usasha384:<HMAC-signature>. Você pode enviar essa string ao seu front-end (desde que tenha feito as verificações adequadas para garantir que a solicitação veio de fato do seu front-end). - No front-end, adicione à sua solicitação um campo POST multipart
signaturecom esse valor (por exemplo, com um campo oculto em um formulário HTML).
Se a sua implementação usa um template_id em vez de steps, não é necessário
gerar uma assinatura para as Instructions que o seu Template contém. Só
devemos assinar payloads de comunicação.
Recomendamos fortemente incluir um valor params.nonce gerado aleatoriamente para cada solicitação,
no nível superior de params. Isso torna distintas as assinaturas geradas de forma independente e evita a reutilização
acidental de assinaturas. Um nonce não torna as novas tentativas idempotentes: repetir uma solicitação de criação
de Assembly pode criar outra Assembly. Faça a deduplicação de novas tentativas na sua aplicação quando necessário.
Não reutilize params assinados entre endpoints. Leituras de Template, listagem de Auth Keys, listagem de credenciais
de Template e leituras de faturamento rejeitam, com SIGNATURE_REUSE_DETECTED, assinaturas já registradas para outro endpoint
ou usadas para criar uma Assembly. Gere params assinados novos para cada solicitação.
A solicitação completa deve ser parecida com esta:
{
"params": {
"auth": {
"key": "23c96d084c744219a2ce156772ec3211",
"expires": "YOUR_FUTURE_ISO_8601_TIMESTAMP",
},
"nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1",
"steps": {
// …
},
},
"signature": "sha384:YOUR_SIGNATURE",
}
Quando a Transloadit recebe a solicitação, também geramos uma assinatura seguindo o mesmo
processo e comparamos as duas assinaturas. Se elas forem diferentes, os nossos servidores
responderão com INVALID_SIGNATURE.
Em resumo, o processo é o seguinte:
- Gere um payload JSON para enviar à Transloadit como o campo
params. - Calcule uma assinatura com base no conteúdo do payload, usando o seu Auth Secret como chave.
- Envie a solicitação à Transloadit, com a assinatura no campo
signature - A Transloadit calculará a mesma assinatura usando o Auth Secret da sua conta e o conteúdo do payload.
- Se as assinaturas corresponderem, a solicitação será permitida e uma resposta adequada será enviada.
Caso contrário, a solicitação será negada e um erro será retornado com o código
INVALID_SIGNATURE.
Isso permite que a Transloadit autentique quem faz a chamada e verifique a integridade de params, já que um terceiro
não conseguiria calcular uma assinatura correspondente sem acesso ao seu Auth Secret. O TLS autentica a Transloadit para o seu cliente
e protege a conexão. A assinatura de webhooks é um fluxo separado, para solicitações que a Transloadit envia aos
seus servidores.
Abaixo estão alguns exemplos de como fazer uma solicitação POST para criar uma Assembly. Recomendamos fortemente usar um dos nossos SDKs, que cuidam da geração de assinaturas automaticamente e são bem testados.
Webhooks são assinados de forma diferente das solicitações de API.
A Transloadit assina exatamente os bytes da string JSON presente no campo de formulário transloadit usando
HMAC-SHA1 e o Auth Secret aplicável. O campo signature contém
o digest hexadecimal sem prefixo de algoritmo. Siga as
instruções de verificação de webhooks, incluindo como selecionar o Auth Secret,
em vez de usar os exemplos de assinatura de solicitações de API abaixo.
Exemplos de código para diferentes linguagens
Os exemplos abaixo mostram como criar Assemblies usando os nossos SDKs oficiais. Os SDKs cuidam internamente de toda a geração de assinaturas, tornando a integração mais simples e 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)
Se precisar calcular uma assinatura separadamente (por exemplo, para uso no front-end), você pode usar
calcSignature:
const { signature, params } = transloadit.calcSignature({
template_id: 'YOUR_TRANSLOADIT_TEMPLATE_ID',
})
console.log(signature, params)
Se preferir ver os detalhes brutos da implementação da assinatura (por exemplo, para implementar a assinatura em uma
linguagem para a qual não temos SDK), confira os links de código-fonte acima. A assinatura é um
digest HMAC hexadecimal compatível com o RFC 6234 calculado sobre a
string de params codificada em JSON, usando o seu Auth Secret como
chave e um algoritmo pelo menos tão forte quanto o mínimo configurado no signature_algo da sua Auth Key. Novas Auth Keys usam
sha384 por padrão. Prefixe a assinatura com o nome do algoritmo em letras minúsculas
(por exemplo, 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 assinadas do Smart CDN
Para assinar uma URL do Smart CDN, usa-se um processo semelhante ao das assinaturas de API comuns. Um digest HMAC é calculado sobre uma string derivada da URL do Smart CDN, com o Auth Secret como chave. Para que a assinatura seja válida, a Auth Key usada precisa estar habilitada para uso com o Smart CDN.
Para gerar uma URL assinada do Smart CDN, use a Auth Key designada para uso com o Smart CDN na sua
página Credenciais. As URLs do Smart CDN exigem sha256. As assinaturas de solicitações de API
comuns podem usar um algoritmo com prefixo pelo menos tão forte quanto o signature_algo da Auth Key; novas Auth Keys usam
sha384 por padrão.
As assinaturas legadas do Smart CDN baseadas em s= e expires= estão obsoletas. Novas integrações devem
sempre usar sig= com exp=.
A geração de uma assinatura do Smart CDN deve ser feita no back-end. O processo usa o Auth Secret, que é confidencial e não deve ser exposto aos seus usuários no front-end.
Uma URL típica do Smart CDN tem a seguinte estrutura:
https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]
[your-workspace]é o nome do seu Workspace da Transloadit[template-name]é o nome do seu Template[file-path]é o caminho do arquivo que você deseja transformar[parameters]são os parâmetros de transformação desejados (por exemplo,h=100)
Uma URL assinada do Smart CDN é gerada seguindo estes passos:
- Adicione o parâmetro de consulta
exppara definir um momento no futuro após o qual a assinatura deixa de ser aceita pelo Smart CDN. Isso é útil para limitar temporalmente o acesso a um arquivo. O momento de expiração é representado pelo número de milissegundos desde a época UNIX (a meia-noite do início de 1º de janeiro de 1970, UTC). Embora esse parâmetro seja opcional, recomendamos muito sempre definir um horário de expiração. Por exemplo, uma assinatura comexp=1722517200000é válida até quinta-feira, 01 de agosto de 2024, 13:00:00 GMT. - Adicione o parâmetro de consulta
auth_keypara definir a Auth Key correspondente ao Auth Secret usado para criar a assinatura. Se esse parâmetro não for definido, a API da Transloadit presume que o par de Auth Key mais antigo habilitado para o Smart CDN foi usado para a assinatura. Definir o parâmetroauth_keypermite fazer a rotação da sua Auth Key sem interromper seus usuários, por isso recomendamos muito defini-lo. Por exemplo:auth_key=23c96d084c744219a2ce156772ec3211 - Ordene os parâmetros de consulta por chave em ordem crescente usando unidades de código UTF-16, de forma equivalente a
URLSearchParams.sort(). A ordenação deve ser estável, ou seja, se uma chave aparecer várias vezes na query string, os valores correspondentes devem manter sua ordem relativa. Por exemplo,h=100&f=png&f=jpg&auth_key=hello&exp=123é ordenado comoauth_key=hello&exp=123&f=png&f=jpg&h=100. - Construa a string a ser assinada concatenando os valores:
Os valores de
[your-workspace]/[template-name]/[file-path]?[sorted-parameters][your-workspace],[template-name]e[file-path]devem ser codificados para URL, para garantir que contenham apenas caracteres seguros para URL. Observe que a string não começa com uma barra inicial. O caractere?deve ser omitido se[sorted-parameters]estiver vazio. - Calcule uma assinatura HMAC hexadecimal compatível com o RFC 6234 sobre a
string a ser assinada, com o seu Auth Secret como chave e SHA256 como algoritmo de hash.
Prefixe a assinatura hexadecimal com o nome do algoritmo em letras minúsculas e dois-pontos, ou seja,
sha256:. Por exemplo, para SHA256, usesha256:[hmac-signature]. - Anexe à URL a assinatura hexadecimal com prefixo no parâmetro de consulta
sig, obtendo a URL assinada do Smart CDN:Os valores dehttps://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature][your-workspace],[template-name]e[file-path]devem ser codificados para URL, para garantir que contenham apenas caracteres seguros para URL. Essa URL assinada pode então ser enviada ao seu front-end ou usada nele até que a data de expiração seja atingida.
Segurança e tempo de vida do cache
As URLs assinadas do Smart CDN não são apenas um mecanismo de controle de acesso. A expiração delas também determina por quanto tempo um resultado recém-gerado pode continuar armazenável em cache.
- Valores de
expmais curtos reduzem a janela de repetição e reforçam o controle de acesso. - Valores de
expmais longos aumentam a reutilização do cache, reduzem o trabalho na origem e, em geral, diminuem a latência e o volume de codificação. - Na prática, o tempo de vida efetivo em cache de uma resposta assinada do Smart CDN é limitado pelo tempo de vida restante da assinatura.
Ou seja, o equilíbrio é simples:
- Mais sensibilidade de segurança: use um
expmais curto, o que também significa um TTL de cache efetivo mais curto. - Mais reutilização do cache e menor custo: use um
expmais longo, o que também significa que a URL continua utilizável por mais tempo.
Escolha a janela de expiração de acordo com a sensibilidade do conteúdo e com o quanto de reutilização do cache você deseja. Para muitos casos de uso com imagens e prévias, uma janela de expiração moderada oferece um bom equilíbrio. Para conteúdo altamente sensível, use uma bem mais curta.
Exemplo de código
Abaixo você encontra exemplos em diferentes linguagens para gerar URLs assinadas do Smart CDN usando os nossos 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)
Acesso de leitura após o cancelamento
Workspaces cancelados não podem criar novos tokens bearer. Os endpoints que permitem explicitamente o acesso após o cancelamento apontam para esta receita. Use uma Auth Key ativa existente e o respectivo Auth Secret; a chave ainda precisa conceder os escopos listados para o endpoint. Isso não restaura o acesso de escrita nem disponibiliza outros endpoints após o cancelamento.
Em um projeto Node.js confiável do lado do servidor, instale o SDK com yarn add @transloadit/node.
Defina TRANSLOADIT_KEY e TRANSLOADIT_SECRET e, em seguida, defina TRANSLOADIT_URL com a URL HTTPS
completa mostrada na página do endpoint, substituindo quaisquer parâmetros de caminho pelos valores dos seus recursos.
Mantenha em sigilo as duas credenciais, a URL assinada e a resposta. Nunca execute essa configuração em código de navegador.
O SDK assina params com sha384, o padrão para novas Auth Keys, e fornece a expiração.
O exemplo adiciona um nonce novo para evitar a reutilização de assinaturas. Se a sua chave usar outro algoritmo
de assinatura, passe-o como segundo argumento de calcSignature. Coloque os filtros do endpoint dentro
do objeto passado como primeiro argumento, junto com o nonce.
O SDK não chama /token nesta receita.
Salve isto como read-api.mjs e execute 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 um cliente MCP por URL
Clientes de agentes como ChatGPT, Codex, Claude.ai, Claude Desktop, Claude Code e Cursor se conectam
ao servidor MCP hospedado em https://api2.transloadit.com/mcp usando apenas essa URL. A API da Transloadit
atua como servidor de autorização OAuth 2.1 para ele: o cliente descobre os endpoints, se identifica,
envia você ao Console para fazer login e dar consentimento e, ao final, obtém um token Bearer de curta duração
para a audiência mcp, além de um token de atualização. Nenhum Auth Secret sai da sua conta em momento algum.
- Descoberta. O servidor MCP responde a solicitações não autenticadas com
401e um cabeçalhoWWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". Esse documento RFC 9728 indicahttps://api2.transloadit.comcomo servidor de autorização, cujos metadados RFC 8414 emhttps://api2.transloadit.com/.well-known/oauth-authorization-serverlistam os endpoints abaixo. - Identificação do cliente. Apresente um
documento de metadados de ID do cliente (Client ID Metadata Document):
uma URL HTTPS que é o
client_ide serve um JSON com o mesmoclient_id, umclient_namee osredirect_uris. Ou registre o cliente uma única vez por meio do registro dinâmico de clientes do RFC 7591 emhttps://api2.transloadit.com/oauth/register; os clientes enviam apenas o seuclient_id(token_endpoint_auth_method: "none", também quando omitido), se autenticam com um segredo de cliente (client_secret_basicouclient_secret_post) ou se autenticam comprivate_key_jwte umjwks_uri. A resposta traz umclient_idopaco e, nos métodos com segredo, umclient_secret, que é exibido somente nessa resposta. As URIs de redirecionamento devem ser URLs HTTPS, comparadas de forma exata, ou URLs de loopbackhttp://localhost/http://127.0.0.1, aceitas em qualquer porta. Um cliente registrado com um segredo o envia em toda solicitação de token e de revogação, via HTTP Basic ou comoclient_ideclient_secretno formulário. Outras solicitações de token autenticam o cliente comnoneouprivate_key_jwt, conforme o que o documento dele listar (emtoken_endpoint_auth_methods_supportedou, na ausência disso, comotoken_endpoint_auth_method) ou o que o registro dele declarar. A primeira solicitação de token vincula a concessão ao método usado: depois que uma solicitação para uma concessão incluir umclient_assertiondo RFC 7523, todas as solicitações posteriores de token e de revogação para ela também precisam incluir um. Essa asserção é um JWT assinado (RS256 ou ES256) com uma chave dojwks_urido cliente, com o ID do cliente comoissesub. Oauddela é uma URL de endpoint de token configurada, ou a origem dessa URL (sem barra final), para esta implantação. Ela tem umexpdentro de cinco minutos e umjtique é aceito uma única vez por cliente e por região enquanto a asserção continuar válida. Use umjtinovo para cada solicitação. - Consentimento. O cliente abre
https://transloadit.com/c/oauth/authorizecomresponse_type=code, oclient_iddele,redirect_uri, umcode_challengePKCE (somenteS256), opcionalmentescopeestate, eresource=https://api2.transloadit.com/mcp. Você faz login, escolhe um Workspace e aprova; o Console redireciona o navegador de volta comcode, o seustateeiss=https://api2.transloadit.com. O código fica vinculado ao cliente, à URI de redirecionamento, ao desafio e ao Workspace, e expira após 120 segundos. - Tokens. O cliente envia via POST
grant_type=authorization_codecomcode,code_verifier,client_ideredirect_uriparahttps://api2.transloadit.com/tokene recebe umaccess_token(válido por 604.800 segundos, 7 dias, por padrão), oscopedele e umrefresh_token. Enviar via POSTgrant_type=refresh_tokencomrefresh_tokeneclient_idretorna um novo par e desativa o token de atualização apresentado; os tokens de atualização duram 30 dias, e reutilizar um token desativado revoga toda a linhagem. Clientes que se autenticam com um segredo de cliente recebem de volta o mesmo token de atualização, válido por mais 30 dias a partir dessa atualização. - Revogação. Envie via POST
token(um token de acesso ou de atualização) parahttps://api2.transloadit.com/oauth/revokeconforme o RFC 7009, ou revogue a conexão no Console.
O indicador resource (RFC 8707) define para que serve o
token. resource=https://api2.transloadit.com/mcp (o padrão quando omitido) gera um token mcp que
carrega no máximo os escopos seguros do MCP (assemblies:write, assemblies:read, templates:read), restritos ao que a
Auth Key do Workspace concede, e que só o servidor MCP aceita. resource=https://api2.transloadit.com (com ou
sem barra final) gera um token api2 para aplicações que chamam a REST API diretamente,
como integrações do Vercel Connect: ele carrega os
escopos solicitados, restritos aos escopos da Auth Key, ou tudo o que a chave concede quando scope é
omitido, com a ressalva de que uma concessão nunca inclui o gerenciamento de Auth Keys ou de credenciais de Template
(auth_keys:*, template_credentials:* ou os escopos globais read/write que os implicam), portanto não pode
criar nem revelar credenciais duradouras. Qualquer outro resource recebe invalid_target como resposta.
Os erros do protocolo OAuth no registro de clientes, na autorização e na revogação usam
o corpo padrão com error e error_description; limites de taxa podem retornar RATE_LIMIT_REACHED.
Em /token, os erros de concessão OAuth para authorization_code e refresh_token usam o corpo padrão com
error e error_description. Limites de taxa retornam RATE_LIMIT_REACHED (429), e
falhas internas inesperadas retornam SERVER_500 (500). Solicitações malformadas rejeitadas
antes de a concessão ser identificada podem receber um desafio HTTP Basic (401) ou
TOKEN_INVALID_REQUEST, se credenciais Basic tiverem sido fornecidas.
Tokens bearer (credenciais do cliente)
Tarefas de CI, servidores e outros clientes headless que têm uma
Auth Key e um Auth Secret os trocam por um token Bearer de curta duração
com a concessão client_credentials do OAuth 2.0, processada diretamente pela API da Transloadit. Use isso quando não houver um navegador
para dar consentimento; clientes MCP interativos devem se conectar por URL, como descrito acima. Para a referência
completa do endpoint, consulte a documentação da API /token.
Como usar o token
Passe o token como Authorization: Bearer <access_token> nas solicitações de API. Quando uma solicitação é
autenticada com um token Bearer válido, a API2 considera a
Signature Authentication atendida e
ignora a validação da assinatura. A Signature Authentication só é aplicada em solicitações com chave/segredo.
As verificações de escopo e de audiência continuam valendo. A audiência mcp é aceita pelo servidor MCP, que
a repassa à API2 com uma credencial de serviço; ela é rejeitada quando apresentada diretamente aos endpoints
normais da API2. Você pode omitir auth.key em params, mas o envelope params continua obrigatório
nos endpoints que o esperam.
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"}'
Autenticação automática do MCP para /ai/chat
Se os seus Steps de /ai/chat chamam um servidor MCP hospedado pela Transloadit, a API2 pode gerar e injetar automaticamente um token Bearer
de curta duração (auto-auth). Isso é opcional e precisa ser ativado em cada entrada de servidor MCP:
{
"mcp_servers": [
{
"type": "http",
"url": "https://api2.transloadit.com/mcp",
"auth": "transloadit"
}
]
}
Comportamento:
- Se
auth: "transloadit"estiver definido e nenhum cabeçalhoAuthorizationestiver presente, a API2 gera um token e injetaAuthorization: Bearer <token>. - Se
Authorizationjá for fornecido emmcp_servers[].headers, ele não é alterado. - A autenticação automática só funciona via HTTPS para hosts apex e subdomínios gerenciados pela Transloadit:
transloadit.com,*.transloadit.com,transloadit.dev,*.transloadit.dev,transloadit.website,*.transloadit.website,transloadit.work,*.transloadit.work. - A URL deve usar a porta
443e o caminho exato/mcpou um subcaminho abaixo de/mcp/. - A URL não pode conter credenciais, query string nem fragmento.
- A Auth Key deve conceder pelo menos um destes escopos seguros do MCP:
assemblies:write,assemblies:read,templates:read. - O token gerado é restrito à interseção desses escopos seguros do MCP com os escopos da Auth Key; ele nunca ganha um escopo que a Auth Key não conceda.
Perguntas frequentes
A Transloadit inclui assinaturas nas solicitações que envia?
A Transloadit assina as solicitações de webhook para que o seu servidor possa verificar a autenticidade delas. A assinatura de webhooks é separada do HMAC que autentica as solicitações de API enviadas à Transloadit.
Por que não posso usar o meu Auth Secret como token Bearer?
Com exceção da troca de tokens entre servidores descrita acima, o seu Auth Secret
nunca deve ser transmitido a um cliente nem incluído em parâmetros de solicitações de API. POST /token o envia como
senha HTTP Basic via HTTPS e só deve ser chamado a partir do seu back-end. Em solicitações assinadas,
o segredo permanece no seu back-end e é usado como chave do HMAC. Isso impede que um agente mal-intencionado
intercepte uma solicitação assinada e falsifique solicitações para a sua conta. Mantenha o seu Auth Secret seguro usando
o sistema de gerenciamento de segredos que preferir. Alguns exemplos são: Vault,
AWS Secrets Manager,
GCP Secret Manager e
Kubernetes Secrets, mas há muitos
outros que podem ser adequados, dependendo da plataforma de back-end que você escolher.
Garanta que os Auth Secrets nunca sejam incluídos no front-end da sua aplicação nem expostos aos usuários.
Em que ordem as chaves do corpo precisam estar?
A ordem das chaves no corpo pode ser arbitrária, mas é importante observar que a ordem escolhida precisa ser consistente com a geração da sua assinatura. O hash gerado depende do conteúdo do JSON, e uma ordem diferente gerará um hash diferente, o que significa que a sua solicitação será negada.