Scopes

Endpoints 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 completo e a lista de recursos, veja a página Escopos.

O catálogo em si é read-only: os escopos são semeados a partir das rotas do FastAPI e não podem ser criados nem editados por API. Além do catálogo, este domínio expõe endpoints restritos a perfil administrador ou diretoria para consultar e atribuir escopos a um usuário.

Catálogo read-only protegido por api_keys

Os endpoints de catálogo (GET /scopes/ e GET /scopes/available) não são protegidos por scopes:* - esse escopo não existe. Eles exigem o escopo api_keys:read: só quem administra API Keys precisa consultar o catálogo de permissões disponíveis para montá-las. Não há operação de escrita sobre o catálogo.

Base path

/api/v1/scopes

A URL completa em produção é https://api.contabilidadealcance.com.br/api/v1/scopes.

Escopos necessários

Endpoint	Proteção
`GET /scopes/`	escopo `api_keys:read`
`GET /scopes/available`	escopo `api_keys:read`
`GET /scopes/users/{user_id}`	perfil `administrador`/`diretoria` (`require_perfil`)
`PUT /scopes/users/{user_id}`	perfil `administrador`/`diretoria` (`require_perfil`)

O catálogo é protegido por api_keys:read (não por scopes:*), porque ler o catálogo é uma tarefa de quem administra API Keys. Não existe api_keys:write neste domínio - não há escrita no catálogo. Já a gestão de escopos de um usuário não usa o modelo recurso:acao: é restrita a perfil administrador ou diretoria via require_perfil.

Endpoints

`GET /scopes/`

Lista o catálogo completo de escopos cadastrados. Cada item traz codigo, recurso, acao, descricao e tag_openapi. O catálogo é read-only, semeado a partir das rotas do FastAPI.

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

{
  "success": true,
  "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

{
  "success": true,
  "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 - restrito a perfil administrador ou diretoria.

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

{
  "success": true,
  "message": "Escopos do usuario listados com sucesso.",
  "data": [
    { "id": 1, "codigo": "customers:read", "recurso": "customers", "acao": "read" }
  ]
}

Escopo: perfil administrador/diretoria (require_perfil) - não usa escopo recurso:acao.

`PUT /scopes/users/{user_id}`

Substitui (não incrementa) o conjunto de escopos de um usuário pelos IDs informados. Endpoint restrito a perfil administrador ou diretoria.

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 []) e escopo_global (opcional, default false).

Request

{
  "escopo_global": false,
  "scope_ids": [1, 2, 3]
}

Response 200 OK

{
  "success": true,
  "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: perfil administrador/diretoria (require_perfil) - não usa escopo recurso:acao.

Schemas

`ScopeRead`

Campo	Tipo	Notas
`id`	`int`	Identificador interno 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 `[]`.
`escopo_global`	`bool`	não	Preparação para o futuro (virará `role='admin'`). Default `false`.

Notas

Catálogo é read-only

Não há endpoints de criação, atualização ou exclusão de escopos. O catálogo é semeado a partir das rotas do FastAPI (schema ScopeSeedItem), garantindo que todo escopo recurso:acao documentado exista de fato como uma rota protegida.

Gestão de usuário é restrita a perfil administrador/diretoria

GET /scopes/users/{user_id} e PUT /scopes/users/{user_id} não usam o modelo de escopos recurso:acao - são protegidos por require_perfil("administrador", "diretoria"). Uma API Key comum (mesmo com api_keys:read) não consegue ler nem alterar escopos de terceiros, e um usuário com perfil funcionario recebe 403 Forbidden.

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O campo escopo_global em ScopeAssignRequest é aceito hoje, mas ainda não altera comportamento - está reservado para a futura noção de role='admin'.
Para entender como os escopos são consumidos ao emitir e validar uma API Key, veja Escopos e Autenticação.