Criar uma nova Auth Key
Cria uma Auth Key com escopo para o Workspace autenticado.
https://api2.transloadit.com/ auth_keysA resposta de criação inclui o novo Auth Secret. Armazene-o com segurança ao recebê-lo.
A recuperação posterior fica desabilitada por padrão. Defina can_show_auth_secret como true durante a criação
somente se precisar de uma única exibição posterior por meio de Recuperar o segredo de uma Auth Key.
Uma chave com o Smart CDN habilitado também pode autenticar requisições comuns à API e emitir tokens bearer. Habilitar o Smart CDN não concede escopos adicionais: conceda apenas as permissões de que sua integração precisa. Mantenha o Auth Secret no seu servidor. Você pode usar chaves separadas quando as integrações precisarem de permissões ou revogação independentes.
Exemplo de requisição
Execute esta requisição em um shell no servidor com curl e um token bearer adequado em TRANSLOADIT_TOKEN. Se precisar de um token, expanda a configuração abaixo.
Precisa de um token bearer?
Em um shell confiável no servidor com curl e jq, defina TRANSLOADIT_KEY e TRANSLOADIT_SECRET com sua Auth Key e seu Auth Secret. Mantenha ambas as credenciais e o token resultante em segredo; nunca execute esta configuração em código de navegador.
Primeiro, crie um token com os escopos exigidos por este endpoint. Sua Auth Key já deve conceder esses escopos.
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=auth_keys: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
Mantenha este shell aberto e execute a requisição abaixo. Reutilize o token enquanto ele permanecer válido.
curl --fail-with-body -sS --request POST \
--url "https://api2.transloadit.com/auth_keys" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"scope":"assemblies:read,assemblies:write","description":"Backend Assembly integration"}'
Autenticação
Este endpoint aceita params assinados ou um token bearer. Consulte Autenticação para instruções de configuração.
Escopo necessário para a Auth Key ou o token bearer: auth_keys:write.
Requisições assinadas exigem tanto uma signature quanto um timestamp params.auth.expires no futuro. Tokens Bearer não exigem nenhum dos dois.
Campos do formulário
Tipo de conteúdo: application/x-www-form-urlencoded
params(string JSON), obrigatório. Um objeto codificado em JSON cujas chaves suportadas estão listadas abaixo.signature(string). Obrigatório para requisições assinadas. Omita este campo ao usar um bearer token.
Chaves compatíveis dentro do campo params
Os campos de autenticação desta lista se aplicam a requisições assinadas. Com um bearer token, você pode omitir params.auth e o campo signature separado. Compare os parâmetros de requisição específicos de autenticação abaixo.
Esquema JSON completo
params: Somente os campos listados para este objeto são aceitos.
| Campo | Tipo e descrição |
|---|---|
params.obrigatório para requisições assinadas; opcional com um bearer token | Contém a chave de API da Transloadit e os metadados de autenticação por assinatura para uma requisição de Auth Keys.
|
params.obrigatório | stringTimestamp de expiração no formato ISO 8601 situado no futuro. Obrigatório quando uma requisição é assinada ou exige autenticação por assinatura; requisições autenticadas por bearer podem omiti-lo. |
params.obrigatório | stringChave de API da Transloadit usada para autenticar as requisições |
params. | string | integerValor único e aleatório incluído nos parâmetros da requisição assinada para tornar cada assinatura única e evitar a reutilização acidental de assinaturas. |
params. | string (comprimento máximo: 64)Valor personalizado da Auth Key. A API2 gera um quando omitido. Caracteres fora do Plano Multilíngue Básico do Unicode, incluindo a maioria dos emojis, não são suportados. Padrão de validação (expressão regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
params. | boolean | 0 | 1Se o segredo gerado pode ser revelado uma vez após a criação. O padrão é false. A própria resposta da criação inclui o segredo independentemente dessa configuração; armazene-o com segurança. |
params. | string (comprimento máximo: 255)Descrição legível por humanos da Auth Key. Caracteres fora do Basic Multilingual Plane do Unicode, incluindo a maioria dos emojis, não são suportados. Padrão de validação (expressão regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
params. | boolean | 0 | 1Se esta Auth Key pode autenticar URLs do Smart CDN além de requisições comuns à API e da emissão de tokens bearer. Cada operação ainda exige seu próprio escopo. Na criação, a omissão resulta no valor padrão false. Na atualização, a omissão mantém o valor atual; envie false explicitamente para desativar o uso do Smart CDN. |
params. | string | integerValor único e aleatório incluído nos parâmetros da requisição assinada para tornar cada assinatura única e evitar a reutilização acidental de assinaturas. |
params.obrigatório | stringEscopos da Auth Key separados por vírgula. Escopos duplicados são normalizados pela API2. Padrão de validação (expressão regular)^(?:[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*,)*[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:read|write|auth_keys:write|auth_keys:read|assemblies:write|assemblies:read|assembly_notifications:write|dam:read|dam:write|template_credentials:read|template_credentials:write|billing:read|queues:read|smart_cdn:sign|templates:read|templates:write|storage_grants:write)[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:,[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:(?:read|write|auth_keys:write|auth_keys:read|assemblies:write|assemblies:read|assembly_notifications:write|dam:read|dam:write|template_credentials:read|template_credentials:write|billing:read|queues:read|smart_cdn:sign|templates:read|templates:write|storage_grants:write)[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*)?)*$ |
params. | "sha1" | "sha256" | "sha384" | nullAlgoritmo HMAC usado para assinar requisições com esta Auth Key. Na criação, chaves de API comuns usam |
Parâmetros de requisição por método de autenticação
Com parâmetros assinados
Inclua sua Auth Key como params.auth.key. Ao assinar a requisição, inclua um timestamp futuro em params.auth.expires e envie a assinatura no campo separado signature. As definições de campos abaixo usam caminhos dentro de params.
Esquema JSON completo
params: Somente os campos listados para este objeto são aceitos.
Usa as definições de campo acima: params.auth, params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.scope, params.signature_algo
Com um token bearer
Envie o token bearer no cabeçalho Authorization. Você pode omitir params.auth e o campo signature separado. Os demais parâmetros obrigatórios continuam se aplicando. As definições de campos abaixo usam caminhos dentro de params.
Esquema JSON completo
params: Somente os campos listados para este objeto são aceitos.
Usa as definições de campo acima: params.auth_key, params.can_show_auth_secret, params.description, params.is_allowed_for_smartcdn, params.nonce, params.scope, params.signature_algo
| Campo | Tipo e descrição |
|---|---|
params. | Contém a chave de API da Transloadit e os metadados de autenticação por assinatura para uma requisição de Auth Keys.
|
params. | stringTimestamp de expiração no formato ISO 8601 situado no futuro. Obrigatório quando uma requisição é assinada ou exige autenticação por assinatura; requisições autenticadas por bearer podem omiti-lo. |
params. | stringChave de API da Transloadit usada para autenticar as requisições |
params. | string | integerValor único e aleatório incluído nos parâmetros da requisição assinada para tornar cada assinatura única e evitar a reutilização acidental de assinaturas. |
Resposta
Veja um exemplo de corpo de resposta:
{
"auth_key": {
"auth_key": "example_auth_key",
"auth_secret": "example_secret_store_securely",
"can_show_auth_secret": false,
"created": "2026-09-12T10:00:00.000Z",
"description": "Backend Assembly integration",
"id": "ca7644b763c848e6af4f4ccf3eaea622",
"is_active": true,
"is_allowed_for_smartcdn": false,
"last_used": null,
"modified": "2026-09-12T10:00:00.000Z",
"scope": "assemblies:read,assemblies:write",
"signature_algo": "sha384"
},
"message": "Your auth key was successfully created.",
"ok": "AUTH_KEY_CREATED"
}sucesso 2xx
Corpo da resposta JSON. application/json text/plain; charset=utf-8
Esquema do corpo da resposta
Esquema JSON completo
A resposta pode conter campos adicionais.
| Campo | Tipo e descrição |
|---|---|
auth_keyobrigatório |
|
auth_key.obrigatório | string (comprimento máximo: 64)Padrão de validação (expressão regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obrigatório | string |
auth_key.obrigatório | boolean |
auth_key.obrigatório | string | nullMomento em que a Auth Key foi criada, como um timestamp ISO 8601, ou null quando nenhum timestamp de criação foi registrado. Padrão de validação (expressão regular)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.obrigatório | string (comprimento máximo: 255)Padrão de validação (expressão regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obrigatório | string |
auth_key.obrigatório | boolean |
auth_key.obrigatório | boolean |
auth_key.obrigatório | string | nullHorário aproximado do último uso como um timestamp ISO 8601, ou null quando nenhum timestamp foi registrado. O uso é rastreado de forma assíncrona e persistido em lotes, então esse valor pode ficar defasado em relação às requisições. Ele não é um timestamp de auditoria exato, e null não prova que a chave nunca foi usada. Padrão de validação (expressão regular)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.obrigatório | string | nullHorário da última atualização das configurações da Auth Key, como um timestamp ISO 8601, ou null quando nenhum horário de modificação está registrado. O acompanhamento de uso é informado separadamente em Padrão de validação (expressão regular)^(([0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-((0[13578]|1[02])-(0[1-9]|[12][0-9]|3[01])|(0[469]|11)-(0[1-9]|[12][0-9]|30)|(02)-(0[1-9]|1[0-9]|2[0-8])))T([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9](\.[0-9]+)?)?(Z)$ |
auth_key.obrigatório | string | null (comprimento máximo: 512)Padrão de validação (expressão regular)^[\u0000-\ud7ff\ue000-\uffff]*$ |
auth_key.obrigatório | null | string |
messageobrigatório | string (comprimento mínimo: 1) |
okobrigatório | string (sempre: "AUTH_KEY_CREATED") |
Resposta de erro
Corpo da resposta JSON. application/json text/plain; charset=utf-8
Esquema do corpo da resposta
Esquema JSON completo
A resposta pode conter campos adicionais.
| Campo | Tipo e descrição |
|---|---|
assembly_id | string |
error | string (comprimento mínimo: 1) |
http_code | number | string
|
message | stringExplicação do erro legível por humanos. A redação pode variar; use o código |
reason | null | string | number | boolean | Array<qualquer valor> | objectQualquer um dos esquemas a seguir pode ser aplicado: nullnullstringstringnumbernumberbooleanbooleanArray<qualquer valor>Array<qualquer valor>Esquema do item do arrayqualquer valorobjectobjectEsquema de propriedade adicionalqualquer valor |
HTTP 400
Corpo da resposta JSON. application/json text/plain; charset=utf-8
Esquema do corpo da resposta
Esquema JSON completo
Erros nomeados e o formato geral de erro
error: "AUTH_KEY_NOT_CREATED"
Não foi possível criar sua Auth Key.
A resposta pode conter campos adicionais.