Scopes
Endpoints administrativos da WebApiAlcance para o catálogo de escopos - a lista canônica de permissões no formato recurso:acao (ex.: customers:read) que podem ser atribuídas a uma API Key. Um escopo combina um recurso (customers, lembretes, grupo_carteira, …) com uma ação (read para leitura, write para escrita). Para o conceito e os principais escopos, veja a página Escopos.
O catálogo em si é read-only: os escopos não podem ser criados nem editados por API. Além do catálogo, este domínio expõe endpoints restritos para consultar e atribuir escopos a um usuário.
Acesso restrito
Este domínio é administrativo. A leitura do catálogo exige o escopo api_keys:read, e a gestão de escopos de um usuário exige permissão adicional; sem ela, a resposta é 403.
Base path
/api/v1/scopesEscopos necessários
| Endpoint | Proteção |
|---|---|
GET /scopes/ | escopo api_keys:read |
GET /scopes/available | escopo api_keys:read |
GET /scopes/users/{user_id} | permissão adicional |
PUT /scopes/users/{user_id} | permissão adicional |
O catálogo é protegido por api_keys:read (não existe um escopo scopes:*), porque ler o catálogo é uma tarefa de quem administra API Keys. Já a gestão de escopos de um usuário não usa o modelo recurso:acao: é restrita a usuários com permissão adicional.
Endpoints
GET /scopes/
Lista o catálogo completo de escopos cadastrados. Cada item traz codigo, recurso, acao, descricao e tag_openapi.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query. A resposta é um array de ScopeRead no campo data.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Catalogo de escopos listado com sucesso.",
"data": [
{
"id": 1,
"codigo": "customers:read",
"recurso": "customers",
"acao": "read",
"descricao": "Leitura de clientes",
"tag_openapi": "customers",
"criado_em": "2026-01-10T12:00:00-03:00"
},
{
"id": 2,
"codigo": "customers:write",
"recurso": "customers",
"acao": "write",
"descricao": "Escrita de clientes",
"tag_openapi": "customers",
"criado_em": "2026-01-10T12:00:00-03:00"
}
]
}Escopo: api_keys:read
GET /scopes/available
Lista os escopos agrupados por tag OpenAPI - formato pensado para telas de UI que montam checkboxes de permissão por recurso ao emitir uma API Key.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query. A resposta é um array de ScopeGrouped no campo data (cada item tem tag_openapi e a lista scopes).
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Escopos disponiveis agrupados por tag.",
"data": [
{
"tag_openapi": "customers",
"scopes": [
{ "id": 1, "codigo": "customers:read", "recurso": "customers", "acao": "read" },
{ "id": 2, "codigo": "customers:write", "recurso": "customers", "acao": "write" }
]
},
{
"tag_openapi": "lembretes",
"scopes": [
{ "id": 3, "codigo": "lembretes:read", "recurso": "lembretes", "acao": "read" },
{ "id": 4, "codigo": "lembretes:write", "recurso": "lembretes", "acao": "write" }
]
}
]
}Escopo: api_keys:read
GET /scopes/users/{user_id}
Retorna os escopos atualmente atribuídos a um usuário. Endpoint de gestão de terceiros.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID interno do usuário |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Escopos do usuario listados com sucesso.",
"data": [
{ "id": 1, "codigo": "customers:read", "recurso": "customers", "acao": "read" }
]
}Escopo: nenhum recurso:acao.
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
PUT /scopes/users/{user_id}
Substitui (não incrementa) o conjunto de escopos de um usuário pelos IDs informados.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID interno do usuário |
O corpo é um ScopeAssignRequest: scope_ids (lista de IDs de escopo, opcional, default []).
Request
{
"scope_ids": [1, 2, 3]
}Response 200 OK
{
"status": "success",
"message": "Escopos do usuario atualizados com sucesso.",
"data": [
{ "id": 1, "codigo": "customers:read", "recurso": "customers", "acao": "read" },
{ "id": 2, "codigo": "customers:write", "recurso": "customers", "acao": "write" }
]
}Escopo: nenhum recurso:acao.
Restrita a usuários com permissão adicional; sem ela, a resposta é 403.
Schemas
ScopeRead
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador do escopo. |
codigo | str | O escopo no formato recurso:acao (ex.: customers:read). |
recurso | str | Recurso protegido (ex.: customers). |
acao | str | Ação: read (leitura) ou write (escrita). |
descricao | str | null | Descrição legível do escopo. |
tag_openapi | str | null | Tag OpenAPI do recurso - usada no agrupamento para UI. |
criado_em | datetime | null | Timestamp de criação do registro. |
ScopeGrouped
Agrupamento de escopos por tag OpenAPI, retornado por GET /scopes/available.
| Campo | Tipo | Notas |
|---|---|---|
tag_openapi | str | Tag do recurso que dá nome ao grupo. |
scopes | List[ScopeRead] | Escopos pertencentes a essa tag. |
ScopeAssignRequest
Payload de PUT /scopes/users/{user_id}.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
scope_ids | List[int] | não | IDs dos escopos a atribuir. Substitui o conjunto atual. Default []. |
Notas
Catálogo é read-only
Não há endpoints de criação, atualização ou exclusão de escopos. O catálogo acompanha as rotas da API: todo escopo recurso:acao documentado corresponde a uma rota protegida.
Gestão de escopos de usuário é restrita
GET /scopes/users/{user_id} e PUT /scopes/users/{user_id} não usam o modelo de escopos recurso:acao - exigem permissão adicional. Sem ela, a resposta é 403 Forbidden, mesmo com api_keys:read.
- Toda resposta de sucesso segue o envelope
{ status, message, data }. Erros de acesso (403) vêm como{ "message": ... }e validação (422) como{ "detail": [...] }. - Para entender como os escopos são consumidos ao emitir e validar uma API Key, veja Escopos e Autenticação.