Visão Geral da API Admin

A API Admin é a superfície privilegiada para administrar uma instância: suas contas, guildas, mensagens e configurações. Todas as rotas estão sob /v1/admin e compartilham a estrutura JSON e o envelope de erro da API HTTP. Ela aplica sua própria política de credenciais, avaliação de ACL e limites de taxa.

Autenticação

Toda operação do Admin aceita um token de sessão de usuário como um valor Authorization básico, um token de acesso emitido pelo aplicativo OAuth2 Admin integrado do Decoding Chat como Bearer <token>, ou uma chave de API do Admin como Admin <token>. O Decoding Chat resolve um valor na forma de token de sessão mesmo sob o prefixo Bearer. A Autenticação HTTP define a sintaxe das credenciais.

O Decoding Chat avalia a credencial em uma ordem fixa.

1. Uma requisição que não resolve nenhuma conta é recusada com 401 UNAUTHORIZED.
2. Uma credencial apresentada com o esquema Bot é recusada com 401 UNAUTHORIZED.
3. Qualquer token de acesso emitido para um aplicativo OAuth2 que não seja o aplicativo Admin integrado é recusado com 403 ACCESS_DENIED.
4. Uma conta que não possui admin:authenticate nem o curinga * é recusada com 403 MISSING_PERMISSIONS.
5. Uma conta que passa por todas as verificações acima, mas não satisfaz nenhuma das ACLs que a operação exige é recusada com 403 MISSING_ACL.

Uma recusa não nomeia o requisito

O corpo de MISSING_ACL é uma frase fixa sem nome de ACL e sem lista de requisitos, portanto, uma recusa nunca diz qual requisito falhou.

Nenhuma operação Admin declara um escopo OAuth2, um requisito MFA ou um requisito sudo, portanto, nenhuma consome o cabeçalho X-Decoding-Chat-Sudo-Mode-JWT. Uma credencial aceita junto com as ACLs necessárias é o limite completo de autorização.

Uma chave de API Admin é autenticada como a conta que a criou, e o Decoding Chat a lê apenas em um caminho abaixo de /v1/admin. Uma requisição que apresenta uma chave em qualquer outro caminho é tratada como uma requisição sem credencial. O Decoding Chat autoriza uma requisição autenticada por chave duas vezes. O próprio conjunto de ACLs da chave deve satisfazer a operação e, a menos que a conta proprietária possua *, a própria conta deve possuir uma das ACLs que a operação nomeia. Quando uma ACL é removida de uma chave ou da conta proprietária da chave, a chave não passa mais em uma verificação para essa ACL em sua próxima solicitação. A chave não precisa ser rotacionada.

A configuração inicial é a única exceção. Enquanto app_public.setup.configured for falso, uma credencial de sessão alcança as operações de configuração de instância sem manter nenhuma ACL. A sessão que muda a configuração para configurado recebe * imediatamente. Após app_public.setup.configured se tornar verdadeiro, essas operações requerem uma credencial aceita e as ACLs que nomeiam.

A autorização Admin é executada antes da validação da requisição em todas as operações, exceto Enfileirar trabalho em lote, cujo corpo é validado primeiro porque sua ACL é selecionada desse corpo. Uma conta sem a ACL necessária é, portanto, recusada com 403 mesmo quando sua string de consulta ou corpo também está malformado.

Avaliação de ACL

Uma operação nomeia uma ou mais ACLs e admite a solicitação quando o chamador possui pelo menos uma delas. O curinga * satisfaz todos os requisitos por si só.

Onde uma operação empilha vários requisitos, o Decoding Chat avalia cada um separadamente e o chamador deve satisfazer todos eles. Criar relatório NCMEC é o exemplo mais amplo e empilha csam:submit_ncmec, message:delete, user:delete e archive:trigger:user como requisitos independentes.

O conjunto efetivo de ACLs de uma sessão ou credencial de portador Admin OAuth2 é o conjunto armazenado na conta. O conjunto efetivo de uma chave de API Admin é o conjunto armazenado na chave, sujeito à verificação de proprietário acima. Definir ACLs do usuário grava o conjunto de uma conta. Segurar admin:authenticate ou * é toda a definição de uma conta que pode acessar a API Admin.

As operações abaixo derivam suas ACLs necessárias a partir do corpo da solicitação validado.

Atualizar guilda mapeia cada campo presente no corpo para uma ACL e requer todas as ACLs desse conjunto.

• name mapeia para guild:update:name.
• vanity_url_code mapeia para guild:update:vanity.
• new_owner_id mapeia para guild:transfer_ownership.
• add_features e remove_features mapeiam para guild:update:features.
• fields junto com todas as configurações restantes mapeia para guild:update:settings.

Um corpo com nenhum desses campos resolve em nenhuma ACL e não aplica nenhuma mudança. A rota também nomeia essas ACLs como um requisito qualquer de, avaliado antes do corpo ser lido.

Enfileirar trabalho em lote mapeia seu discriminador de tarefa para uma ACL e exige essa.

• update_user_flags mapeia para bulk:update:user_flags.
• update_suspicious_activity_flags mapeia para bulk:update:suspicious_activity.
• update_guild_features mapeia para bulk:update:guild_features.
• add_guild_members mapeia para bulk:add:guild_members.
• schedule_user_deletion mapeia para bulk:delete:users.

O Decoding Chat verifica cada ACL que um Admin concede em relação às ACLs que o Admin possui. Definir ACLs do usuário e Criar chave de API Admin recusam gravar uma ACL que o Admin atuante não possui, com 403 MISSING_ACL. Um detentor de curinga é isento. Definir ACLs do usuário também recusa a conta do próprio Admin atuante com 403 ACCESS_DENIED, e procura a conta de destino antes de verificar as ACLs concedidas, de forma que um ID desconhecido falhe primeiro com 404 UNKNOWN_USER.

Definir ACLs do usuário, Criar chave de API Admin e Atualizar chave de API Admin aceitam no máximo 111 ACLs e validam cada entrada em relação ao registro, portanto, um valor fora dele retorna 400 INVALID_FORM_BODY.

* satisfaz toda ACL presente e futura

Uma chave cuja conta proprietária detém * ignora a verificação do proprietário. Um Admin com * pode conceder qualquer ACL.

O Registro de ACLs abaixo lista todos os valores reconhecidos pela instância.

Erros e limites de taxa

Resposta de erro

Uma falha do Admin usa o mesmo envelope que a Resposta de erro da API HTTP. O status HTTP está na linha de status e o identificador de requisição no cabeçalho de resposta X-Request-ID.

Estrutura

Campo	Tipo	Descrição
code	string	O código de erro da API estável legível por máquina
message1	string	A descrição legível desta falha
errors?2	array[Objeto validation error]	Os campos da solicitação que falharam na validação

¹ O texto varia por localidade e não é um valor estável para correspondência programática ² Presente em uma resposta INVALID_FORM_BODY, e em qualquer outra falha que tenha detalhe de campo