Autenticação

Auth Keys

Para requisições multipart de criação de Assembly autenticadas com uma Auth Key, inclua um objeto auth no campo de formulário params codificado em JSON. O menor valor possível de params nesse caso é mostrado abaixo.

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

O campo key se refere à Auth Key associada ao seu Workspace da Transloadit, encontrada na página Credenciais. O exemplo acima é o objeto mínimo de autenticação para uma requisição de Assembly que usa uma Auth Key. Outros endpoints e métodos de autenticação podem usar formatos de requisição diferentes, conforme descrito na documentação de cada endpoint e abaixo.

Assemblies que usam /transloadit/import, diretamente ou por meio de um Template, exigem um token bearer ou params assinados com um timestamp futuro em params.auth.expires. Isso se aplica mesmo quando a Signature Authentication do Workspace está desativada. Uma Auth Key sozinha não é suficiente; requisições autenticadas com bearer não precisam de uma assinatura ou expiração separada.

Signature Authentication

Recomendamos ativar a Signature Authentication na sua conta, especialmente se você estiver integrando a Transloadit a partir de um ambiente não confiável (como pelo navegador com o Uppy⁠). Você pode ativar a Signature Authentication nas Configurações do Workspace.

Com a Signature Authentication ativada, o Auth Secret do seu Workspace (encontrado ao lado da sua Auth Key na página Credenciais) é usado como chave para um HMAC gerado a partir do valor serializado exato de params. Esse valor contém tanto uma key (que é a sua Auth Key, como mencionado anteriormente) quanto um parâmetro expires, que é um timestamp em um futuro próximo usado como data de expiração da requisição.

Para criar Assemblies com a Transloadit, seu back-end pode calcular uma assinatura que abranja apenas determinados parâmetros, usuários autenticados e um intervalo de tempo que ele considere um uso legítimo. Por exemplo, ele se recusaria a gerar uma assinatura para usuários que não estejam conectados. Você pode usar qualquer lógica de negócio no lado do servidor para decidir se fornece uma assinatura ou não. A Transloadit pode exigir uma assinatura correta para o payload quando uma requisição à API se autentica com a sua Auth Key.

Para exigir Signature Authentication nas requisições à API autenticadas com a sua Auth Key:

1. Acesse as Configurações do Workspace na sua conta.
2. Na seção Configurações da API, ative a opção Exigir uma assinatura correta.
3. Clique no botão Salvar.

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 público-alvo continuam se aplicando. Essas configurações não adicionam autenticação ao acesso baseado em capacidades, como URLs de Assembly Status, cancelamento ou upload retomável. Mantenha os Assembly IDs e as URLs de capacidade privados e siga as orientações de autenticação de cada endpoint.

Como gerar assinaturas

Então, como tudo isso funciona 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 encontrada em Credenciais da API na sua conta.

Para assinar esta requisição, é necessário adicionar o campo auth.expires. Isso o inclui no nosso payload, que é protegido pela nossa assinatura. Se alguém o alterasse, a Transloadit rejeitaria a requisição, pois a assinatura não corresponderia mais. Você teria assinado um payload diferente daquele que recebemos. Se a assinatura corresponder, então naturalmente compararemos a data e rejeitaremos a requisição conforme instruído. Dessa forma, fica muito difícil que terceiros que obtiveram esse payload repitam as requisições indefinidamente. Embora nosso HTTPS com classificação A+ já deva contribuir bastante para impedir isso, o cache do navegador pode ser mais fácil de bisbilhotar.

A propriedade expires deve conter um timestamp em um futuro (próximo). Use o formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) para a data, garantindo que UTC seja usado como fuso horário. Por exemplo:

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

Para calcular a assinatura desta requisição:

1. No seu front-end, serialize o objeto JavaScript acima em uma string JSON e envie-a ao seu back-end.
2. No seu back-end, calcule uma assinatura HMAC hexadecimal em conformidade com a RFC 6234⁠ sobre a string, usando seu Auth Secret como chave e o algoritmo configurado em signature_algo da sua Auth Key. Novas Auth Keys usam sha384 por padrão. Auth Keys legadas sem um algoritmo configurado aceitam sha384, sha256 ou sha1. Adicione o nome do algoritmo em letras minúsculas como prefixo à string signature. Por exemplo, o algoritmo padrão usa sha384:<HMAC-signature>. Você pode enviar essa string ao seu front-end (desde que tenha feito as verificações adequadas para garantir que se tratava de uma requisição legítima do seu front-end).
3. No seu front-end, adicione à requisição um campo POST multipart signature contendo esse valor (por exemplo, com um campo oculto em um formulário HTML).

A requisição completa deve ser semelhante à seguinte:

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

Assim que a requisição é recebida pela Transloadit, também geramos uma assinatura seguindo o mesmo processo e comparamos as duas assinaturas. Se as assinaturas forem diferentes, nossos servidores responderão com INVALID_SIGNATURE.

Em resumo, o processo é o seguinte:

1. Gere um payload JSON para enviar à Transloadit como o campo params.
2. Calcule uma assinatura com base no conteúdo do payload, usando seu Auth Secret como chave.
3. Envie a requisição à Transloadit, com a assinatura passada no campo signature
4. A Transloadit calculará a mesma assinatura usando o Auth Secret da sua conta e o conteúdo do payload.
5. Se as assinaturas corresponderem, a requisição será permitida e uma resposta apropriada será enviada. Caso contrário, a requisiçã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, pois um terceiro não conseguiria calcular uma assinatura correspondente sem acesso ao seu Auth Secret. O TLS autentica a Transloadit perante seu cliente e protege a conexão. A assinatura de webhooks é um fluxo separado para as requisições que a Transloadit envia aos seus servidores.

Abaixo estão alguns exemplos de como fazer uma requisição POST para criar uma Assembly. Recomendamos fortemente usar um dos nossos SDKs EN (English), que geram assinaturas automaticamente e são bem testados.

Exemplos de código para diferentes linguagens

Os exemplos abaixo demonstram a criação de Assemblies usando nossos SDKs oficiais. Os SDKs cuidam de toda a geração de assinaturas internamente, 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)

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

console.log(signature, params)

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, é usado um processo semelhante ao das assinaturas comuns da API. Um resumo 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 deve estar habilitada para uso no Smart CDN.

A geração de uma assinatura do Smart CDN deve ser realizada 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ê quer transformar
• [parameters] são os parâmetros de transformação desejados (por exemplo, h=100)

Uma URL assinada do Smart CDN é gerada seguindo estas etapas:

1. Adicione o parâmetro de consulta exp para definir um momento no futuro após o qual a assinatura não será mais aceita pelo Smart CDN. Isso é útil para limitar o tempo de acesso a um arquivo. O momento de expiração é representado pelo número de milissegundos desde a época UNIX (a meia-noite no início de 1º de janeiro de 1970, UTC). Embora esse parâmetro seja opcional, recomendamos fortemente sempre definir um momento de expiração. Por exemplo, uma assinatura que usa exp=1722517200000 é válida até quinta-feira, 1º de agosto de 2024, às 13:00:00 GMT.
2. Adicione o parâmetro de consulta auth_key para 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 pressupõe que o par da Auth Key mais antiga habilitada para Smart CDN foi usado para a assinatura. Definir o parâmetro auth_key permite que você alterne sua Auth Key sem interromper seus usuários, por isso recomendamos fortemente defini-lo. Por exemplo: auth_key=23c96d084c744219a2ce156772ec3211
3. Ordene os parâmetros de consulta por chave em ordem crescente usando unidades de código UTF-16, correspondendo a URLSearchParams.sort(). A ordenação deve ser estável, ou seja, se uma chave aparecer várias vezes na string de consulta, os valores correspondentes devem manter sua ordem relativa. Por exemplo, h=100&f=png&f=jpg&auth_key=hello&exp=123 é ordenado como auth_key=hello&exp=123&f=png&f=jpg&h=100.
4. Construa a string a ser assinada concatenando os valores:

   [your-workspace]/[template-name]/[file-path]?[sorted-parameters]
   

   Os valores de [your-workspace], [template-name] e [file-path] devem ser codificados para URL para garantir que contenham apenas caracteres seguros para URLs. Observe que a string não começa com uma barra. O caractere ? deve ser omitido se [sorted-parameters] estiver vazio.
5. Calcule uma assinatura HMAC hexadecimal em conformidade com a RFC 6234⁠ sobre a string a ser assinada, usando seu Auth Secret como chave e SHA256 como algoritmo de hash. Adicione à assinatura hexadecimal o nome do algoritmo em letras minúsculas seguido de dois-pontos como prefixo, ou seja, sha256:. Por exemplo, para SHA256, use sha256:[hmac-signature].
6. Acrescente a assinatura hexadecimal com prefixo à URL no parâmetro de consulta sig, obtendo a URL assinada do Smart CDN:

   https://[your-workspace].tlcdn.com/[template-name]/[file-path]?[parameters]&sig=sha256:[hmac-signature]
   

   Os valores de [your-workspace], [template-name] e [file-path] devem ser codificados para URL para garantir que contenham apenas caracteres seguros para URLs. 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. Sua expiração também determina por quanto tempo um resultado recém-gerado pode permanecer apto a ser armazenado em cache.

• Valores de exp mais próximos reduzem a janela de repetição de requisições e tornam o controle de acesso mais restrito.
• Valores de exp mais distantes aumentam a reutilização do cache, reduzem o trabalho na origem e geralmente diminuem a latência e o volume de codificação.
• Na prática, o tempo de vida efetivo do cache de uma resposta assinada do Smart CDN é limitado pelo tempo de vida restante da assinatura.

Isso significa que a relação entre essas escolhas é direta:

• Maior sensibilidade à segurança: use um exp mais próximo, o que também significa um TTL efetivo de cache menor.
• Mais reutilização do cache e menor custo: use um exp mais distante, o que também significa que a URL permanece utilizável por mais tempo.

Escolha a janela de expiração de acordo com a sensibilidade do conteúdo e o nível de reutilização de cache que você deseja. Para muitos casos de uso de imagens e pré-visualizações, uma janela de expiração moderada oferece um bom equilíbrio. Para conteúdo altamente sensível, use uma janela muito menor.

Exemplos de código

Abaixo você encontra exemplos em diferentes linguagens para gerar URLs assinadas do Smart CDN usando 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 incluem um link para este procedimento. Use uma Auth Key ativa existente e seu Auth Secret; a chave ainda deve 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 como a URL HTTPS completa mostrada na página do endpoint, substituindo os parâmetros de caminho pelos valores do seu recurso. Mantenha ambas as credenciais, a URL assinada e a resposta privados. Nunca execute essa configuração no código do navegador.

O SDK assina params com sha384, o padrão para novas Auth Keys, e fornece a expiração. O exemplo adiciona um novo nonce para evitar a reutilização de assinaturas. Se a sua chave usa outro algoritmo de assinatura, passe-o como segundo argumento para calcSignature. Coloque os filtros do endpoint no objeto passado como primeiro argumento, junto com o nonce. O SDK não chama /token neste procedimento.

Salve este código 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))

Tokens bearer (credenciais de cliente)

Se precisar de um token de curta duração para comunicação entre servidores ou clientes sem interface, você pode trocar sua Auth Key e seu Auth Secret por um token Bearer. Isso segue o modelo de um fluxo client_credentials do OAuth 2.0, mas é tratado diretamente pela API da Transloadit. Para a referência completa do endpoint, consulte a documentação da API /token.

Usar o token

Passe o token como Authorization: Bearer <access_token> nas requisições à API. Quando uma requisição é autenticada com um token Bearer válido, a API2 considera o requisito de Signature Authentication atendido e pula a validação da assinatura. A Signature Authentication é exigida apenas para requisições com chave e segredo. As verificações de escopo e público-alvo continuam se aplicando. O público-alvo mcp é aceito pelo servidor MCP e rejeitado pelos endpoints comuns da API2. Você pode omitir auth.key em params, mas o envelope params ainda é obrigatório para 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 de MCP para /ai/chat

Se os seus Steps de /ai/chat chamarem um servidor MCP hospedado pela Transloadit, a API2 poderá emitir e inserir um token Bearer de curta duração automaticamente (autenticação automática). Esse recurso precisa ser ativado explicitamente 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 não houver um cabeçalho Authorization, a API2 emitirá um token e inserirá Authorization: Bearer <token>.
• Se Authorization já tiver sido fornecido em mcp_servers[].headers, ele será mantido sem alterações.
• A autenticação automática só funciona via HTTPS para hosts de domínio raiz 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 443 e o caminho exato /mcp ou um subcaminho abaixo de /mcp/.
• A URL não deve conter credenciais, uma string de consulta ou um fragmento.
• A Auth Key deve conceder pelo menos um destes escopos seguros de MCP: assemblies:write, assemblies:read, templates:read.
• O token emitido é limitado à interseção desses escopos seguros de MCP com os escopos da Auth Key; ele nunca recebe um escopo que a Auth Key não conceda.

Perguntas frequentes

A Transloadit inclui assinaturas nas suas requisições?

A Transloadit assina requisições de webhook para que seu servidor possa verificar sua autenticidade. A assinatura de webhooks é separada do HMAC que autentica as requisições à API enviadas à Transloadit.

Por que não posso usar meu Auth Secret como token Bearer?

Exceto na troca por token entre servidores descrita acima, seu Auth Secret nunca deve ser transmitido a um cliente ou incluído nos parâmetros de requisições à API. POST /token o envia como senha HTTP Basic via HTTPS e deve ser chamado apenas pelo seu back-end. Para requisições assinadas, o segredo permanece no seu back-end e é usado como chave do HMAC. Isso impede que um agente mal-intencionado intercepte uma requisição assinada e forje requisições à sua conta. Mantenha 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.

Em que ordem as chaves do corpo precisam estar?

A ordem que você escolher para as chaves do corpo pode ser arbitrária, mas é importante observar que, seja qual for essa ordem, ela 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 sua requisição será negada.