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/scopes

Escopos necessários

EndpointProteção
GET /scopes/escopo api_keys:read
GET /scopes/availableescopo 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âmetroTipoLocalObrigatórioDescrição
user_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
user_idintpathsimID 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

CampoTipoNotas
idintIdentificador do escopo.
codigostrO escopo no formato recurso:acao (ex.: customers:read).
recursostrRecurso protegido (ex.: customers).
acaostrAção: read (leitura) ou write (escrita).
descricaostr | nullDescrição legível do escopo.
tag_openapistr | nullTag OpenAPI do recurso - usada no agrupamento para UI.
criado_emdatetime | nullTimestamp de criação do registro.

ScopeGrouped

Agrupamento de escopos por tag OpenAPI, retornado por GET /scopes/available.

CampoTipoNotas
tag_openapistrTag do recurso que dá nome ao grupo.
scopesList[ScopeRead]Escopos pertencentes a essa tag.

ScopeAssignRequest

Payload de PUT /scopes/users/{user_id}.

CampoTipoObrigatórioObservações
scope_idsList[int]nãoIDs 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.