Escopos de API Key

Toda API Key emitida pela WebApiAlcance carrega uma lista explícita de escopos no formato recurso:acao - por exemplo, customers:read ou certidao_negativa:write. Esse modelo segue o princípio do menor privilégio: cada chave recebe apenas o conjunto mínimo de permissões necessárias para sua tarefa, reduzindo o impacto de um eventual vazamento.

Esta página foca em API Keys, que são o caso de uso dominante em integrações. Além do escopo, algumas rotas exigem permissão adicional do usuário ou login de usuário; nesses casos a resposta sem permissão é 403.

Como funciona

A WebApi deriva o escopo necessário a partir da rota e do método HTTP da requisição:

  • Recurso = primeiro segmento após /api/v1/, com hifens convertidos em underscore. Exemplo: /api/v1/certidao-negativa/... → certidao_negativa.
  • Ação = read para métodos GET/HEAD/OPTIONS; write para POST/PUT/PATCH/DELETE.

Antes de aceitar a requisição, o middleware extrai o token do header Authorization: Bearer, identifica os escopos associados à API Key e verifica se o escopo derivado consta na lista. Sem o escopo, retorna 403 Forbidden com mensagem "Escopo necessario: <recurso>:<acao>".

Catálogo de escopos

A tabela abaixo lista os escopos principais da WebApiAlcance. O catálogo completo, sempre atualizado conforme novas rotas são adicionadas, pode ser solicitado ao TI Alcance.

EscopoO que permite
customers:readListar e consultar clientes (GET /api/v1/customers/)
customers:writeCriar, atualizar e remover clientes
certidao_negativa:readListar certidões e baixar PDFs
certidao_negativa:writeSolicitar nova certidão e disparar workers
lembretes:readConsultar lembretes / notificações agendadas
lembretes:writeCriar, atualizar e remover lembretes
worker_automation:readConsultar status de execuções assíncronas
worker_automation:writeDisparar e cancelar workers de automação
users:readConsultar usuários (a gestão exige permissão adicional)
users:writeCriar, atualizar, redefinir senha e excluir usuários (exige permissão adicional)
api_keys:readListar API Keys e seus escopos, e ler o catálogo de escopos
api_keys:writeCriar, atualizar e revogar API Keys
dctfweb:readListar guias e recibos da DCTFWeb, baixar seus PDFs, ler os catálogos, consultar o histórico de transmissões e a situação da declaração
dctfweb:writeRegistrar/editar/remover guias e recibos, disparar a emissão em lote e transmitir/simular a declaração

Escopos administrativos

users:*, api_keys:* e o catálogo em Scopes pertencem a domínios administrativos: além do escopo, exigem permissão adicional do usuário e, sem ela, a resposta é 403. Não os conceda a credenciais de integração. Detalhes em Users e API Keys.

Escopos novos exigem token novo

dctfweb:read e dctfweb:write nasceram com a consolidação da superfície DCTFWeb sob /api/v1/dctfweb. O escopo entra no token no momento em que ele é emitido: credenciais anteriores à mudança não os carregam e recebem 403 nos caminhos novos. Relogue (JWT de login) ou peça a atualização da API Key. Detalhes e mapa de migração em DCTFWeb: visão geral.

`dctfweb:write` NÃO basta para transmitir

As rotas POST de /api/v1/dctfweb/transmissao (transmitir, simular, reconciliar, marcar e desmarcar transmissão externa) exigem login de usuário (sessão), independentemente do escopo; credenciais de integração recebem 403. A mesma regra vale para os atos irreversíveis do Integra Contador (entrega do PGDAS-D, transmissão da DEFIS, opção de regime e encerramento do MIT) e para as mutações da EFD-Reinf que transmitem ao fisco.

Consequência prática: automação sem usuário não transmite DCTFWeb. Ver DCTFWeb: Transmissão.

Escopos adicionais

Verifique com TI Alcance se há escopos adicionais não listados acima.

Solicitando uma API Key

A emissão de API Keys é administrada pelo TI Alcance. O fluxo padrão:

  1. Abra um chamado descrevendo o caso de uso da integração - qual sistema vai consumir, com que frequência e quais dados precisa acessar.
  2. O TI Alcance avalia a solicitação e define a lista mínima de escopos necessária. Por exemplo: um job de relatório lê clientes e lembretes → customers:read + lembretes:read.
  3. A chave é criada pelo TI Alcance, atrelada a um usuário emissor e a uma data de expiração (recomendado: 90 dias).
  4. A chave em texto plano é entregue uma única vez ao solicitante por canal seguro (cofre interno, não e-mail).
  5. O solicitante armazena a chave em variável de ambiente - nunca em código-fonte.

Para revogar, basta desativar a chave no Hub ou deletá-la. A revogação é aplicada em poucos instantes.

Chaves de integração recebem apenas os escopos necessários.