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-keysEscopos necessários
api_keys:read- listagem, detalhamento e leitura de escoposapi_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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
api_key_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
api_key_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
api_key_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
api_key_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
api_key_id | int | path | sim | ID 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
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome | str | sim | Nome descritivo da chave (identifica a integração). |
expiracao | str | não | Política de expiração. Default "nunca". |
scope_ids | list[int] | não | IDs 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.
| Campo | Tipo | Observações |
|---|---|---|
nome | str | Novo nome descritivo da chave. |
ativo | bool | Ativa (true) ou revoga (false) a chave. |
ApiKeyRead
Objeto de leitura devolvido nas listagens e no detalhamento. Nunca contém o segredo.
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador da chave. |
usuario_id | int | Usuário dono da chave. |
nome | str | Nome descritivo. |
key_prefix | str | Prefixo público da chave (para identificação; não é o segredo). |
expiracao | str | Política de expiração (ex.: "nunca"). |
data_expiracao | datetime | null | Data de expiração calculada, quando houver. |
ativo | bool | Se a chave está ativa. |
criado_em | datetime | null | Timestamp de criação. |
ultimo_uso | datetime | null | Último uso registrado (null se nunca usada). |
scopes | list[ScopeRead] | Escopos associados à chave. |
ApiKeyCreatedResponse
Estende ApiKeyRead com um único campo adicional, retornado apenas na criação:
| Campo | Tipo | Notas |
|---|---|---|
api_key | str | O segredo. Exibido uma só vez; não é recuperável depois. |
ScopeRead
Usado dentro de ApiKeyRead.scopes e nas respostas de escopos.
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador do escopo. |
codigo | str | Código canônico (ex.: customers:read). |
recurso | str | Recurso (ex.: customers). |
acao | str | Ação (read ou write). |
descricao | str | null | Descrição legível do escopo. |
tag_openapi | str | null | Tag OpenAPI para agrupamento em telas de UI. |
criado_em | datetime | null | Timestamp de criação do escopo. |
ScopeAssignRequest
Payload de PUT /api-keys/{api_key_id}/scopes.
| Campo | Tipo | Observações |
|---|---|---|
scope_ids | list[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}/scopessubstitui 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.