Transloadit

Autenticação

Auth Keys

Para requisiçõ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 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 com a Transloadit a partir de um ambiente não confiável (como o navegador com 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 de 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 poderia calcular uma assinatura que abrangesse apenas determinados parâmetros, usuários autenticados e um período que considerasse de uso legítimo. Por exemplo, ele se recusaria a gerar uma assinatura para usuários que não estivessem conectados. Você poderia 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 é autenticada com sua Auth Key.

Para exigir Signature Authentication nas requisições à API autenticadas com 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 de Workspace e 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 Assembly Status, cancelamento ou URLs de upload retomável. Mantenha Assembly IDs e URLs de capacidade privados e siga as orientações de autenticação de cada endpoint.

Como gerar assinaturas

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 essa requisição, é necessário adicionar o campo extra auth.expires. Isso o adiciona ao 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ê assinou um payload diferente daquele que recebemos. Se a assinatura corresponder, naturalmente compararemos a data e rejeitaremos a requisição com base nela, conforme instruído. Dessa forma, fica muito difícil para um terceiro que tenha obtido esse payload repetir as requisições indefinidamente. Isso porque, embora nosso HTTPS com classificação A+ já deva ajudar bastante a impedir isso, o cache do navegador pode ser mais fácil de espionar.

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 dessa 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 apropriadas para garantir que era uma requisição genuína 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",
}

Quando a Transloadit recebe a requisição, 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, passando a assinatura 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 poderia 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 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, que gerenciam a geração de assinaturas automaticamente e são bem testados.

Exemplos de código em diferentes linguagens

Os exemplos abaixo demonstram a criação de Assemblies usando nossos SDKs oficiais. Os SDKs gerenciam 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)

Se você precisar calcular uma assinatura separadamente (por exemplo, para uso no front-end), pode usar calcSignature:

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

console.log(signature, params)

Ver o código-fonte da implementação de assinatura

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 regulares da API. Um digest HMAC é calculado sobre uma string derivada da URL do Smart CDN, usando 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 período 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é qui., 01 ago. 2024 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 de Auth Key mais antigo habilitado para Smart CDN foi usado para a assinatura. Definir o parâmetro auth_key permite fazer a rotação da sua Auth Key sem interromper seus usuários e, 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, de acordo com 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 o nome do algoritmo em letras minúsculas e dois-pontos como prefixo à assinatura hexadecimal, 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

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 elegível para cache.

  • Valores menores de exp reduzem a janela de repetição e tornam o controle de acesso mais restrito.
  • Valores maiores de exp 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 validade restante da assinatura.

Isso significa que a relação de compromisso é direta:

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

Escolha o período de expiração de acordo com a sensibilidade do conteúdo e o quanto você quer reutilizar o cache. Para muitos casos de uso de imagens e prévias, um período de expiração moderado oferece um bom equilíbrio. Para conteúdo altamente sensível, use um período 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. Endpoints que permitem explicitamente o acesso após o cancelamento têm 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 no 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 quaisquer parâmetros de caminho pelos valores do seu recurso. Mantenha ambas as credenciais, a URL assinada e a resposta em sigilo. 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 novo nonce para evitar a reutilização de assinaturas. Se sua chave usa outro algoritmo de assinatura, passe-o como segundo argumento de calcSignature. Coloque quaisquer filtros do endpoint dentro do objeto passado como primeiro argumento, junto com o nonce. O SDK não chama /token neste procedimento.

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

Tokens bearer (credenciais do cliente)

Se você precisar de um token de curta duração para comunicação entre servidores ou clientes sem interface, 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.

Como 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 ignora a validação de assinatura. A Signature Authentication é exigida apenas para requisições com chave/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 regulares 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 seus Steps /ai/chat chamarem um servidor MCP hospedado pela Transloadit, a API2 poderá emitir e injetar um token Bearer de curta duração automaticamente (autenticação automática). Isso exige ativação explícita 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çalho Authorization estiver presente, a API2 emitirá um token e injetará Authorization: Bearer <token>.
  • Se Authorization já tiver sido fornecido em mcp_servers[].headers, ele não será alterado.
  • A autenticação automática só funciona por 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 MCP seguros: assemblies:write, assemblies:read, templates:read.
  • O token emitido é restrito à interseção desses escopos MCP seguros 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 requisições à API enviadas à Transloadit.

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

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

Em que ordem as chaves do corpo precisam estar?

A ordem que você escolher para as chaves no corpo pode ser arbitrária, mas é importante observar que, qualquer que seja a ordem escolhida, 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.