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 =
readpara métodosGET/HEAD/OPTIONS;writeparaPOST/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.
| Escopo | O que permite |
|---|---|
customers:read | Listar e consultar clientes (GET /api/v1/customers/) |
customers:write | Criar, atualizar e remover clientes |
certidao_negativa:read | Listar certidões e baixar PDFs |
certidao_negativa:write | Solicitar nova certidão e disparar workers |
lembretes:read | Consultar lembretes / notificações agendadas |
lembretes:write | Criar, atualizar e remover lembretes |
worker_automation:read | Consultar status de execuções assíncronas |
worker_automation:write | Disparar e cancelar workers de automação |
users:read | Consultar usuários (a gestão exige permissão adicional) |
users:write | Criar, atualizar, redefinir senha e excluir usuários (exige permissão adicional) |
api_keys:read | Listar API Keys e seus escopos, e ler o catálogo de escopos |
api_keys:write | Criar, atualizar e revogar API Keys |
dctfweb:read | Listar 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:write | Registrar/editar/remover guias e recibos, disparar a emissão em lote e transmitir/simular a declaração |
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:
- Abra um chamado descrevendo o caso de uso da integração - qual sistema vai consumir, com que frequência e quais dados precisa acessar.
- 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. - A chave é criada pelo TI Alcance, atrelada a um usuário emissor e a uma data de expiração (recomendado: 90 dias).
- A chave em texto plano é entregue uma única vez ao solicitante por canal seguro (cofre interno, não e-mail).
- 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.