Criar um token bearer

Troca as credenciais da Auth Key por um bearer token com escopo definido.

Este é o endpoint de token OAuth 2.0. Clientes sem interface gráfica trocam sua Auth Key e seu Auth Secret por um token Bearer de curta duração com a concessão client_credentials, processada diretamente pela API da Transloadit. Clientes MCP que se conectaram por URL resgatam o código de autorização da tela de consentimento do Console com a concessão authorization_code (PKCE S256, sem credenciais HTTP Basic) e rotacionam o token de atualização resultante com a concessão refresh_token.

Em /token, os erros de concessão OAuth para authorization_code e refresh_token usam o corpo padrão com error e error_description. Os 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 de credenciais de cliente são emitidos no servidor usando sua Auth Key e seu Auth Secret. Se você expuser a criação de tokens por meio de uma interface, chame /token a partir do seu backend (nunca diretamente do navegador).

Workspaces cancelados não podem criar novos tokens bearer. Para endpoints cuja documentação permite explicitamente leituras após o cancelamento, use o procedimento de leitura com assinatura com uma Auth Key ativa existente. O faturamento tem seu próprio procedimento de faturamento com assinatura.

As solicitações devem usar application/x-www-form-urlencoded; a concessão client_credentials também precisa de autenticação HTTP Basic:

Em um shell confiável no servidor com curl e jq, defina TRANSLOADIT_KEY e TRANSLOADIT_SECRET com os valores de sua Auth Key e de seu Auth Secret. Mantenha em segredo as duas credenciais e o token resultante; nunca execute essa configuração em código de navegador.

Este exemplo solicita acesso de leitura e gravação a Assemblies e salva o access_token retornado como TRANSLOADIT_TOKEN para solicitações subsequentes no mesmo shell. Para outro endpoint, use os escopos listados para ele; a Auth Key já deve concedê-los. Endpoints autenticados por uma Auth Key ou um token bearer incluem a configuração de token apropriada em seus exemplos de solicitação.

if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
  --request POST \
  --url 'https://api2.transloadit.com/token' \
  --user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'aud=api2' \
  --data-urlencode 'scope=assemblies:read assemblies:write')"; then
  printf '%s\n' "$TOKEN_RESPONSE" >&2
  exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
  jq -er '.access_token | strings | select(length > 0)')" || exit 1

A autenticação HTTP Basic com sua Auth Key e seu Auth Secret é obrigatória para os seguintes valores de grant_type: client_credentials. Os outros valores aceitos não exigem credenciais da conta. Não envie um cabeçalho Authorization nessas requisições; a comprovação específica da concessão continua sendo obrigatória.

Tipo de conteúdo: application/x-www-form-urlencoded

Os seguintes campos podem ser enviados no máximo uma vez: aud, client_assertion, client_assertion_type, client_id, code, code_verifier, grant_type, redirect_uri, refresh_token, resource, scope.

Usar o token

Envie o token como Authorization: Bearer <access_token> nas solicitações à 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ó é exigida para solicitações com chave/segredo. As verificações de escopo continuam se aplicando. O público-alvo padrão api2 é aceito pelos endpoints regulares da API2 e é válido por 21.600 segundos por padrão. O público-alvo mcp é aceito pelo servidor MCP, que o encaminha à API2 com uma credencial de serviço; ele é rejeitado pelos endpoints regulares da API2 quando apresentado diretamente e é válido por 604.800 segundos por padrão. Considere o valor de expires_in da resposta como o valor de referência.