Chaves da API Admin

Uma chave da API Admin é uma credencial de longa duração para a API Admin. Ela se autentica como a conta que a criou, possui seu próprio conjunto de ACL e autentica apenas solicitações para caminhos abaixo de /v1/admin.

Todas as operações nesta página exigem admin_api_key:manage. Uma operação bem-sucedida registra uma entrada de auditoria Admin com o tipo de alvo admin_api_key e o cabeçalho X-Audit-Log-Reason como seu motivo. Uma solicitação que retorna um erro não registra nenhuma entrada. Uma operação que aborda uma chave retorna 404 ADMIN_API_KEY_NOT_FOUND quando qualquer um destes casos for verdadeiro:

Nenhuma chave possui esse identificador.
Outra conta criou a chave.
A chave expirou.

Objeto Admin API key

Uma chave pertence à conta que a criou e armazena seu próprio conjunto de ACL. Remover uma ACL da conta proprietária e remover uma ACL da chave são alterações separadas.

O Decoding Chat verifica ambos os conjuntos quando uma solicitação apresenta uma chave. Uma solicitação é aprovada quando todas estas condições são verdadeiras:

A conta proprietária possui admin:authenticate ou *.
A conta proprietária possui a ACL que a operação exige, ou *.
A própria chave possui essa ACL, ou *.

Portanto, uma chave nunca tem uma permissão mais ampla do que a conta por trás dela.

Estrutura

Campo	Tipo	Descrição
key_id	snowflake	O ID da chave
name	string	O nome dado à chave (1-100 caracteres)
acls¹	array[string]	As ACLs armazenadas na chave
created_by_user_id²	snowflake	O ID da conta que criou a chave e cuja identidade a chave assume
created_at	ISO8601 timestamp	Momento em que a chave foi criada
last_used_at³	?ISO8601 timestamp	Momento em que a chave autenticou uma solicitação pela última vez, ou nulo quando nunca o fez
expires_at⁴	?ISO8601 timestamp	Momento em que a chave expira, ou nulo quando a chave não expira

¹ Limitado ao tamanho do registro de ACL. Todo valor gravado por meio desta API é um membro do registro

² Nunca muda, portanto, uma chave não pode ser transferida para outra conta

³ Gravado em cada autenticação bem-sucedida, incluindo quando a operação autenticada é uma leitura

⁴ Uma chave expirada está ausente de todas as listagens e é relatada como não encontrada

Exemplo

{
  "key_id": "1501314428688998182",
  "name": "moderation-tooling",
  "acls": ["user:lookup", "report:view", "report:resolve"],
  "created_by_user_id": "1489200013322551296",
  "created_at": "2026-05-14T09:12:44.183000+00:00",
  "last_used_at": "2026-06-02T18:40:11.902000+00:00",
  "expires_at": null
}

Objeto Admin API key creation

Apenas Create Admin API key retorna este objeto. Ele possui a credencial bruta e omite last_used_at e created_by_user_id.

Estrutura

Campo	Tipo	Descrição
key_id	snowflake	O ID da chave
key¹	string	A credencial bruta com a qual a chave se autentica
name	string	O nome dado à chave (1-100 caracteres)
created_at	ISO8601 timestamp	Momento em que a chave foi criada
expires_at²	?ISO8601 timestamp	Momento em que a chave expira, ou nulo quando a chave não expira
acls³	array[string]	As ACLs armazenadas na chave

¹ Uma chave opaca, apresentada como Admin <token> no cabeçalho Authorization

² Derivado de expires_in_days no instante em que a chave é criada e nulo quando esse campo é omitido

³ Reflete o conjunto armazenado, portanto, um valor repetido na solicitação aparece uma vez

Exemplo

{
  "key_id": "1501314428688998182",
  "key": "fa_1501314428688998182_7Qk2ZbW9xLmR4TnP0vAeJdCyHs6UgF1B",
  "name": "moderation-tooling",
  "created_at": "2026-05-14T09:12:44.183000+00:00",
  "expires_at": "2026-08-12T09:12:44.183000+00:00",
  "acls": ["user:lookup", "report:view"]
}

List Admin API keys

GET/v1/admin/api-keys

Audit reason

Retorna todos os objetos Admin API key criados pela conta em ação, como um array JSON bruto sem garantia de ordem. Exige admin_api_key:manage.

Uma chave após o seu vencimento nunca é retornada.

Resposta

Status	Corpo	Condição
200¹	array[objeto Admin API key]	As chaves foram retornadas

¹ Uma conta que não criou nenhuma chave recebe um array vazio

Efeitos colaterais

A operação registra uma entrada de auditoria Admin com a ação list_admin_api_keys, tipo de alvo admin_api_key, ID de alvo 0 e chave de metadados result_count.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.

Create Admin API key

POST/v1/admin/api-keys

Audit reason

Cria uma chave e retorna um objeto Admin API key creation que possui a credencial bruta, com HTTP 200, não 201. Exige admin_api_key:manage.

A credencial em ação já deve possuir todos os valores em acls, a menos que tenha *. A chave autentica imediatamente, e sua permissão efetiva é a interseção descrita em Objeto Admin API key.

Corpo JSON

Campo	Tipo	Descrição
name¹	string	O nome dado à chave (1-100 caracteres)
expires_in_days?²	integer	O número de dias até a chave expirar (1-365)
acls³	array[string]	As ACLs armazenadas na chave, cada uma um valor do registro (no máximo 111)

¹ Um valor que fica vazio após remover os espaços nas extremidades é rejeitado, portanto, apenas espaço em branco não é um nome

² A expiração armazenada é o instante da solicitação mais essa quantidade de dias. Omitir o campo cria uma chave que não expira

³ Um array vazio produz uma chave que não atende a nenhuma operação. O Decoding Chat compara as acls com as próprias ACLs da chave de apresentação, portanto, uma chave não pode emitir uma chave mais ampla

O Decoding Chat rejeita a solicitação com 403 MISSING_ACL no primeiro valor não concedível. Uma solicitação que nomeia várias ACLs não concedíveis relata apenas essa.

Resposta

Status	Corpo	Condição
200	objeto Admin API key creation	A chave foi criada
400	resposta de erro	A validação do corpo falha, incluindo um valor em `acls` fora do registro de ACL, retornado como `INVALID_FORM_BODY`
403	resposta de erro	O tipo de credencial é recusado, `admin_api_key:manage` está ausente, ou `acls` nomeia um valor que a credencial em ação não possui

Efeitos colaterais

A operação registra uma entrada de auditoria Admin com a ação create_admin_api_key, tipo de alvo admin_api_key, ID de alvo igual ao novo key_id, e chaves de metadados acls e expires_in_days. acls é o conjunto de ACL armazenado unido por vírgulas. expires_in_days está presente apenas quando a solicitação o forneceu. A entrada não possui nome e não possui credencial bruta.

Limite de taxa

30 solicitações por minuto para cada usuário autenticado, no bucket admin:code:generation.

Get Admin API key

GET/v1/admin/api-keys/{key_id}

Audit reason

Retorna um objeto Admin API key. Exige admin_api_key:manage.

Esta operação nunca retorna a credencial bruta.

Parâmetros de caminho

Campo	Tipo	Descrição
key_id	snowflake	O ID da chave

Resposta

Status	Corpo	Condição
200	objeto Admin API key	A chave foi retornada
404	resposta de erro	`ADMIN_API_KEY_NOT_FOUND`, que também abrange uma chave expirada e uma chave criada por outra conta

Efeitos colaterais

A operação registra uma entrada de auditoria Admin com a ação get_admin_api_key, tipo de alvo admin_api_key, ID de alvo igual a key_id, e sem metadados.

Limite de taxa

200 solicitações por minuto para cada usuário autenticado, no bucket admin:lookup.

Update Admin API key

PATCH/v1/admin/api-keys/{key_id}

Audit reason

Renomeia uma chave ou substitui seu conjunto de ACL e retorna o objeto Admin API key atualizado. Exige admin_api_key:manage.

O Decoding Chat deixa um campo omitido inalterado, e os campos fornecidos entram em vigor na próxima solicitação autenticada da chave. A credencial em ação já deve possuir todos os valores fornecidos em acls, a menos que tenha *. Uma chave com validade a mantém.

Parâmetros de caminho

Campo	Tipo	Descrição
key_id	snowflake	O ID da chave

Corpo JSON

Campo	Tipo	Descrição
name?¹	string	O nome de substituição para a chave (1-100 caracteres)
acls?²	array[string]	O conjunto completo de substituição de ACLs, cada um um valor do registro (no máximo 111)

¹ Um valor que fica vazio após remover os espaços nas extremidades é rejeitado

² Um array vazio deixa a chave sem ACLs, portanto, a chave não atende a nenhuma operação. Um corpo de solicitação vazio é aceito e não altera nada

Resposta

Status	Corpo	Condição
200	objeto Admin API key	A chave foi atualizada
400	resposta de erro	A validação do corpo falha, incluindo um valor em `acls` fora do registro de ACL, retornado como `INVALID_FORM_BODY`
403¹	resposta de erro	O tipo de credencial é recusado, `admin_api_key:manage` está ausente, ou `acls` nomeia um valor que a credencial em ação não possui
404	resposta de erro	`ADMIN_API_KEY_NOT_FOUND`, que também abrange uma chave expirada e uma chave criada por outra conta

¹ A verificação de propriedade é executada antes da verificação de concessão de ACL, portanto, uma chave pertencente a outra conta retorna 404, não 403

Efeitos colaterais

A operação registra uma entrada de auditoria Admin com a ação update_admin_api_key, tipo de alvo admin_api_key, ID de alvo igual a key_id, e chaves de metadados fields e acls. fields lista os nomes dos campos fornecidos unidos por vírgulas, e está vazio para um corpo vazio. acls é o conjunto de ACL armazenado unido por vírgulas, presente apenas quando a solicitação forneceu acls. A entrada não possui nome.

Limite de taxa

100 solicitações por minuto para cada usuário autenticado, no bucket admin:user:modify.

Revoke Admin API key

DELETE/v1/admin/api-keys/{key_id}

Audit reason

Revoga uma chave da API Admin e retorna HTTP 200 com um corpo de resposta. Exige admin_api_key:manage.

A credencial para de autenticar no seu próximo uso. Uma solicitação já em andamento é executada até a conclusão.

Parâmetros de caminho

Campo	Tipo	Descrição
key_id	snowflake	O ID da chave

Corpo da resposta

Campo	Tipo	Descrição
success	boolean	Sempre true

Resposta

Status	Corpo	Condição
200	corpo da resposta	A chave foi revogada
404	resposta de erro	`ADMIN_API_KEY_NOT_FOUND`, que também abrange uma chave expirada e uma chave criada por outra conta

Efeitos colaterais

A operação registra uma entrada de auditoria Admin com a ação revoke_admin_api_key, tipo de alvo admin_api_key, ID de alvo igual a key_id, e sem metadados.

Limite de taxa

100 solicitações por minuto para cada usuário autenticado, no bucket admin:user:modify.