API administrativa

Tudo o que o console faz passa pela API administrativa, então tudo o que você configura na tela também pode ser automatizado: realms, clients, usuários, papéis, webhooks e o resto. É uma API JSON no mesmo host dos endpoints de protocolo, sob /api/v1/admin.

URL base

https://authio.api.hyperio.tech/api/v1/admin

Num ambiente dedicado, use o endereço da API do seu ambiente com os mesmos caminhos, e credenciais criadas no console do próprio ambiente. A versão faz parte do caminho; v1 é a atual.

Nos caminhos, {realm} é o ID do realm (acme), {client} é o ID do client (acme-web), e identificadores como {userId} são GUIDs. Um realm ou client de outra conta responde como se não existisse.

Autenticação

As credenciais dos consumers de um client não são aceitas na API administrativa: elas agem dentro do client delas, e a API administrativa trabalha no nível da conta. A chave de API de um consumer é validada pela sua própria API no endpoint de introspecção do realm com token_type_hint=api_key — veja Chaves de API. Um PUT num consumer nunca muda o tipo dele: sem type o tipo é mantido, e outro tipo é recusado com ValidationFailed em type.

Segredos de API

1. 1

   Crie o segredo

   No console, abra Segredos de API e escolha Novo segredo. Escolha o tipo Chave de API, dê um nome e, se quiser que ele pare de funcionar sozinho, uma data de expiração.

2. 2

   Permita só o que o chamador precisa

   Escolha os papéis e os escopos que o segredo pode usar. Eles são o máximo que ele vai poder fazer, seja o que for que a conta permita.

3. 3

   Copie o valor

   O valor aparece uma única vez, na criação. Guarde-o num gerenciador de segredos e crie um segredo separado para cada integração, para revogar um sem afetar os outros.

curl https://authio.api.hyperio.tech/api/v1/admin/realms/acme \
  -H "x-api-key: $AUTHIO_API_KEY"

Só segredos do tipo chave de API, ativos e dentro da validade, autenticam, e só para realms e clients da conta dona deles. Toda tentativa, aceita ou recusada, vai para o log de acesso. Uma chamada a um realm ou client que a conta não alcança (de outra conta, ou que não existe) recebe 403 com errorCode Forbidden, como receberia uma pessoa logada; um segredo ausente, desconhecido, excluído ou vencido recebe 401 já na próxima chamada.

Uma credencial de máquina da conta não personifica ninguém: uma chave de API, um token de acesso pessoal ou um token trocado pelo segredo de cliente da conta recebe 403 com errorCode ImpersonationActorNotAPerson em POST /api/v1/admin/realms/{realm}/users/{userId}/impersonate, sejam quais forem os papéis que carregue. Personificação é trabalho de suporte, feito por uma pessoa logada no console, cujo nome a trilha de auditoria guarda. A tentativa recusada fica registrada mesmo assim, com a credencial como autora.

Bearer tokens a partir de um segredo da conta

Um script que prefere bearer tokens de vida curta pode trocar um segredo da conta por um. Crie um segredo do tipo Client secret em Segredos de API, com os papéis de que o script precisa, e apresente-o ao endpoint de token do realm da plataforma com o grant client credentials:

curl https://authio.api.hyperio.tech/realms/authio/protocol/openid-connect/token \
  -u "authio:$AUTHIO_ACCOUNT_SECRET" \
  -d grant_type=client_credentials

O access token devolvido leva só os papéis e escopos permitidos no segredo e nunca dura mais do que a validade do próprio segredo. Envie-o como Authorization: Bearer para a API administrativa.

Permissões

Cada endpoint exige uma permissão formada por um recurso — realm, client, user, role, scope, secret, audit, account e alguns outros — e uma ação: read, write (criar), update ou delete. Quem chama tem tudo o que os seus papéis concedem, somado. Credenciais ausentes ou inválidas recebem 401; credenciais válidas sem a permissão recebem 403. Veja os papéis do console em Equipe e acesso.

Envelope de resposta

As respostas são JSON em camelCase, sem os campos vazios. Um sucesso traz o resultado em data:

{
  "statusCode": "OK",
  "success": true,
  "data": {
    "id": "6f1c2a7e-3b4d-4e8f-9a10-5c6d7e8f9a0b",
    "realmId": "acme",
    "name": "Acme",
    "status": "Active"
  }
}

Paginação e filtros

As listas paginadas compartilham os mesmos parâmetros de query e respondem com pagination em vez de data.

curl "https://authio.api.hyperio.tech/api/v1/admin/realms/acme/clients?pageNumber=1&pageSize=20&sortDirection=asc" \
  -H "x-api-key: $AUTHIO_API_KEY"

Limites de taxa

A maioria dos endpoints aceita 300 requisições por minuto por chamador. Os sensíveis — criar ou alterar segredos de API, importações, personificação e alguns outros — aceitam 50. Acima deles, a API aplica tetos gerais por chamador e por realm. Uma requisição recusada recebe 429 com o cabeçalho Retry-After, em segundos, e errorCode TooManyRequests.

IDs de requisição e novas tentativas

Toda resposta traz o cabeçalho X-Request-Id. Envie o seu — até 128 caracteres entre letras, dígitos, -, _, : e . — para acompanhar uma chamada nos seus logs e nos nossos, e informe-o ao falar com o suporte.

A API não aceita chave de idempotência. Se uma criação expirar sem resposta, leia o recurso antes de enviá-la de novo: criar um realm ou client com um ID já usado é recusado com 409 e AlreadyExists.

Rotação de segredos

Dois endpoints geram um novo valor e o devolvem uma única vez: POST /realms/{realm}/clients/{client}/client-secret/rotate para o segredo de um client, e POST /secrets/{id}/rotate para uma credencial da conta — uma chave de API, um token de acesso pessoal ou um client secret da conta. Os dois aceitam um corpo JSON opcional que diz o que acontece com o valor anterior. Sem ele, o valor anterior é recusado na hora e os tokens emitidos com ele continuam valendo até expirar.

Um período acima de 0 e revokeIssuedTokens: true se excluem. Enviar os dois, ou um período fora do intervalo, recebe 400 com errorCode ValidationFailed, e a notificação nomeia o campo recusado (revokeIssuedTokens ou previousValueValidForMinutes).

curl -X POST https://authio.api.hyperio.tech/api/v1/admin/realms/acme/clients/acme-web/client-secret/rotate \
  -H "x-api-key: $AUTHIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"previousValueValidForMinutes": 60}'

A resposta traz o novo valor uma única vez — clientSecret, clientSecretLastFour e clientSecretRotatedAt para um client, o segredo com o seu value para uma credencial da conta — e rotation, que diz o que aconteceu com o anterior. Os horários são em UTC.

As leituras acompanham a última rotação: o clientConfiguration de um client traz previousClientSecretValidUntil e issuedTokensRevokedBefore, e todo segredo de API traz previousValueValidUntil e issuedTokensRevokedBefore. O campo …ValidUntil só vem preenchido enquanto o valor anterior ainda autentica; uma leitura em cache pode durar mais que ele, então compare-o com a hora atual antes de confiar nele.

GET /secrets/rotation-policy responde maxPreviousValueValidForMinutes, o máximo que o ambiente deixa um valor anterior continuar funcionando (hoje 1440, um dia). Ele atende quem tem secret:read, secret:write ou secret:update, e o console só oferece sobreposições dentro dele.

Toda rotação fica registrada na trilha de alterações com details contendo mode, previous_value_valid_until e issued_tokens_revoked_before. A rotação do segredo de um client também dispara admin_resource_updated nos webhooks do realm, com os mesmos details.

Grupos de recursos

Os caminhos são relativos a /api/v1/admin.

As rotas que o console usa para acompanhar e operar um ambiente dedicado ficam na plataforma compartilhada, sob /api/v1/dedicated/instance, e pedem as permissões de ler e de atualizar a conta.

Próximos passos