API Keys

Endpoints administrativos da WebApiAlcance para gerenciar API Keys - as credenciais de integração com a API. Cobrem geração de novas chaves, listagem geral, listagem das chaves do usuário logado, detalhamento por ID, atualização, exclusão e o gerenciamento dos escopos associados a cada chave.

Acesso restrito

Este domínio é administrativo: governa a emissão e a revogação de credenciais. Além do escopo, algumas operações exigem permissão adicional; sem ela, a resposta é 403. Não conceda api_keys:read nem api_keys:write a credenciais de integração.

Todos os endpoints exigem autenticação. Veja Autenticação.

Base path

/api/v1/api-keys

Escopos necessários

  • api_keys:read - listagem, detalhamento e leitura de escopos
  • api_keys:write - geração, atualização, exclusão e substituição de escopos

O escopo é derivado da rota, com uma normalização: o prefixo da URL é /api-keys (com hífen), porém o recurso de escopo é api_keys (com underscore). A ação segue o método HTTP: read para GET e write para POST/PUT/PATCH/DELETE. Portanto os escopos corretos são api_keys:read e api_keys:write, não api-keys:read.

Controles de privilégio

Além dos escopos, alguns endpoints aplicam regras extras: a listagem geral é restrita a usuários com permissão adicional, e ninguém pode criar ou atribuir a uma chave escopos além dos seus próprios (princípio do menor privilégio). O acesso a uma chave específica exige que ela pertença ao usuário, salvo para quem tem permissão adicional.

Endpoints

POST /api-keys/

Gera uma nova API Key para o usuário logado. Retorna a chave criada com o segredo no campo api_key - exibido uma única vez. Só é possível informar scope_ids que o usuário já possua; escopos além dos seus geram 403.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ApiKeyCreate): nome (obrigatório), expiracao (default "nunca") e scope_ids (default []).

Request

{
  "nome": "Integração Exemplo",
  "expiracao": "nunca",
  "scope_ids": [3, 8]
}

Response 200 OK

{
  "status": "success",
  "message": "API Key gerada com sucesso! Guarde a chave, ela nao sera exibida novamente.",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "nome": "Integração Exemplo",
    "key_prefix": "ak_exemplo",
    "expiracao": "nunca",
    "data_expiracao": null,
    "ativo": true,
    "criado_em": "2026-07-03T09:15:00-03:00",
    "ultimo_uso": null,
    "scopes": [],
    "api_key": "ak_exemplo_..."
  }
}

O segredo aparece só uma vez

O campo api_key (o segredo) é retornado exclusivamente nesta resposta de criação. Ele não é recuperável e nunca volta a ser exibido - nem em GET /api-keys/me, nem em GET /api-keys/{api_key_id}, que só devolvem o key_prefix. Copie e guarde o valor com segurança no momento da criação; se perder, a única saída é revogar a chave e gerar outra.

Escopo: api_keys:write

GET /api-keys/

Lista todas as API Keys de todos os usuários. O segredo nunca é incluído.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz um array de ApiKeyRead.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "API Keys listadas com sucesso!",
  "data": [
    {
      "id": 42,
      "usuario_id": 7,
      "nome": "Integração Exemplo",
      "key_prefix": "ak_exemplo",
      "expiracao": "nunca",
      "data_expiracao": null,
      "ativo": true,
      "criado_em": "2026-07-03T09:15:00-03:00",
      "ultimo_uso": null,
      "scopes": []
    }
  ]
}

Escopo: api_keys:read

Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /api-keys/me

Lista as API Keys do usuário logado. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz um array de ApiKeyRead.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Suas API Keys listadas com sucesso!",
  "data": [
    {
      "id": 42,
      "usuario_id": 7,
      "nome": "Integração Exemplo",
      "key_prefix": "ak_exemplo",
      "expiracao": "nunca",
      "data_expiracao": null,
      "ativo": true,
      "criado_em": "2026-07-03T09:15:00-03:00",
      "ultimo_uso": "2026-07-05T14:22:00-03:00",
      "scopes": []
    }
  ]
}

Escopo: api_keys:read

GET /api-keys/{api_key_id}

Detalha uma API Key pelo ID inteiro. A chave deve pertencer ao usuário logado, salvo para quem tem permissão adicional. Quando não encontrada, retorna 404 Not Found.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
api_key_idintpathsimID interno da chave

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "API Key encontrada!",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "nome": "Integração Exemplo",
    "key_prefix": "ak_exemplo",
    "expiracao": "nunca",
    "data_expiracao": null,
    "ativo": true,
    "criado_em": "2026-07-03T09:15:00-03:00",
    "ultimo_uso": "2026-07-05T14:22:00-03:00",
    "scopes": []
  }
}

Escopo: api_keys:read

Restrita a usuários com permissão adicional quando a chave pertence a outro usuário; sem ela, a resposta é 403.

PUT /api-keys/{api_key_id}

Atualiza uma API Key existente. O body é um ApiKeyUpdate com campos parciais - somente o que vier preenchido é alterado. Permite renomear (nome) e ativar/desativar (ativo) a chave.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
api_key_idintpathsimID da chave

Request (ApiKeyUpdate - todos os campos opcionais)

{
  "nome": "Integração Exemplo (produção)",
  "ativo": false
}

Response 200 OK

{
  "status": "success",
  "message": "API Key atualizada com sucesso!",
  "data": {
    "id": 42,
    "usuario_id": 7,
    "nome": "Integração Exemplo (produção)",
    "key_prefix": "ak_exemplo",
    "expiracao": "nunca",
    "data_expiracao": null,
    "ativo": false,
    "criado_em": "2026-07-03T09:15:00-03:00",
    "ultimo_uso": "2026-07-05T14:22:00-03:00",
    "scopes": []
  }
}

Revogar sem apagar

Para desativar uma chave sem removê-la, use ativo: false. É a forma recomendada de revogar uma credencial preservando o histórico de auditoria.

Escopo: api_keys:write

Restrita a usuários com permissão adicional quando a chave pertence a outro usuário; sem ela, a resposta é 403.

DELETE /api-keys/{api_key_id}

Remove permanentemente uma API Key.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
api_key_idintpathsimID da chave

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "API Key removida com sucesso!",
  "data": null
}

Escopo: api_keys:write

Restrita a usuários com permissão adicional quando a chave pertence a outro usuário; sem ela, a resposta é 403.

GET /api-keys/{api_key_id}/scopes

Lista os escopos associados a uma API Key.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
api_key_idintpathsimID da chave

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Escopos da API Key listados com sucesso.",
  "data": {
    "scopes": [
      { "id": 3, "codigo": "customers:read", "recurso": "customers", "acao": "read" },
      { "id": 8, "codigo": "lembretes:write", "recurso": "lembretes", "acao": "write" }
    ]
  }
}

Escopo: api_keys:read

Restrita a usuários com permissão adicional quando a chave pertence a outro usuário; sem ela, a resposta é 403.

PUT /api-keys/{api_key_id}/scopes

Substitui (não incrementa) a lista de escopos de uma API Key numa única transação atômica. Só é possível atribuir scope_ids que o usuário já possua; escopos além dos seus geram 403.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
api_key_idintpathsimID da chave

Corpo da requisição: ScopeAssignRequest com scope_ids (lista completa que substitui a anterior).

Request

{
  "scope_ids": [3, 8]
}

Response 200 OK

{
  "status": "success",
  "message": "Escopos da API Key atualizados com sucesso.",
  "data": {
    "scopes": [
      { "id": 3, "codigo": "customers:read", "recurso": "customers", "acao": "read" },
      { "id": 8, "codigo": "lembretes:write", "recurso": "lembretes", "acao": "write" }
    ]
  }
}

Escopo: api_keys:write

Restrita a usuários com permissão adicional quando a chave pertence a outro usuário; sem ela, a resposta é 403.

Schemas

ApiKeyCreate

CampoTipoObrigatórioObservações
nomestrsimNome descritivo da chave (identifica a integração).
expiracaostrnãoPolítica de expiração. Default "nunca".
scope_idslist[int]nãoIDs dos escopos concedidos. Default []. Limitado aos escopos do próprio usuário.

ApiKeyUpdate

Todos os campos são opcionais; apenas os enviados são atualizados.

CampoTipoObservações
nomestrNovo nome descritivo da chave.
ativoboolAtiva (true) ou revoga (false) a chave.

ApiKeyRead

Objeto de leitura devolvido nas listagens e no detalhamento. Nunca contém o segredo.

CampoTipoNotas
idintIdentificador da chave.
usuario_idintUsuário dono da chave.
nomestrNome descritivo.
key_prefixstrPrefixo público da chave (para identificação; não é o segredo).
expiracaostrPolítica de expiração (ex.: "nunca").
data_expiracaodatetime | nullData de expiração calculada, quando houver.
ativoboolSe a chave está ativa.
criado_emdatetime | nullTimestamp de criação.
ultimo_usodatetime | nullÚltimo uso registrado (null se nunca usada).
scopeslist[ScopeRead]Escopos associados à chave.

ApiKeyCreatedResponse

Estende ApiKeyRead com um único campo adicional, retornado apenas na criação:

CampoTipoNotas
api_keystrO segredo. Exibido uma só vez; não é recuperável depois.

ScopeRead

Usado dentro de ApiKeyRead.scopes e nas respostas de escopos.

CampoTipoNotas
idintIdentificador do escopo.
codigostrCódigo canônico (ex.: customers:read).
recursostrRecurso (ex.: customers).
acaostrAção (read ou write).
descricaostr | nullDescrição legível do escopo.
tag_openapistr | nullTag OpenAPI para agrupamento em telas de UI.
criado_emdatetime | nullTimestamp de criação do escopo.

ScopeAssignRequest

Payload de PUT /api-keys/{api_key_id}/scopes.

CampoTipoObservações
scope_idslist[int]Conjunto completo de escopos (substitui o anterior). Default [].

Notas

Guarde o segredo na criação

O segredo (api_key) só aparece na resposta do POST /api-keys/. Não há endpoint para recuperá-lo. Perdeu? Revogue (PUT com ativo: false) ou apague (DELETE) e gere uma nova.

  • Toda resposta de sucesso segue o envelope { status, message, data }. Erros de regra de negócio vêm como { "status": "error", "message", "details" }, e erros de acesso (403, 404) como { "message": ... }. Validação (422) usa { "detail": [...] }.
  • O PUT /api-keys/{api_key_id}/scopes substitui o conjunto inteiro de escopos - para adicionar um escopo, envie a lista completa desejada, não apenas o novo item.
  • Os escopos disponíveis ficam no domínio Scopes; aqui apenas os associamos a uma chave.