# Qual a Importância de Controle de Acesso Granular para APIs de CPF > Entenda por que o controle de acesso granular é essencial para APIs de CPF e como implementá-lo para proteger dados pessoais e atender à LGPD. **Publicado:** 01/05/2024 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/controle-acesso-granular-apis-cpf --- ## Introdução Nem todo colaborador ou sistema precisa do mesmo nível de acesso a dados de CPF. Um operador de atendimento pode precisar verificar se um CPF é válido, enquanto o sistema de compliance precisa acessar o nome completo e a data de nascimento. O controle de acesso granular garante que cada ator no sistema tenha acesso apenas aos dados estritamente necessários para sua função, seguindo o princípio do menor privilégio. Este artigo explora como implementar esse controle para chamadas a APIs de CPF, reduzindo riscos de vazamento e garantindo conformidade com a LGPD. --- ## O que é controle de acesso granular O controle de acesso granular vai além do simples "tem acesso" ou "não tem acesso". Ele permite definir permissões específicas por recurso, operação e contexto: | Nível de Granularidade | Exemplo | Benefício | |------------------------|---------|-----------| | Por endpoint | Acesso apenas a /cpf/validate, não a /cpf/{id} | Limita operações disponíveis | | Por campo de resposta | Visualizar apenas campo "success", sem "name" | Minimiza exposição de dados | | Por volume | Máximo de 100 consultas por dia | Previne abusos e exfiltração | | Por horário | Apenas durante horário comercial (8h-18h) | Reduz superfície de ataque | | Por IP de origem | Apenas da rede corporativa (VPN) | Restringe acesso físico | | Por finalidade | Apenas para "validação de cadastro" | Documenta base legal LGPD | --- ## Modelos de controle de acesso Existem diferentes modelos que podem ser aplicados dependendo da complexidade da sua organização: - **RBAC (Role-Based Access Control)** -- atribui permissões a papéis (roles) e associa usuários a esses papéis, ideal para organizações com funções bem definidas - **ABAC (Attribute-Based Access Control)** -- define políticas baseadas em atributos do usuário, recurso e contexto, oferecendo maior flexibilidade - **PBAC (Policy-Based Access Control)** -- centraliza decisões de acesso em um motor de políticas, facilitando auditorias e mudanças - **DAC (Discretionary Access Control)** -- o proprietário do recurso define quem pode acessá-lo, menos adequado para dados regulados Para APIs de CPF, a combinação de RBAC com restrições ABAC é geralmente a mais equilibrada. ```javascript // Definição de roles e permissões para API de CPF const roles = { operador_atendimento: { endpoints: ["GET /cpf/:cpf"], campos_permitidos: ["success"], limite_diario: 50, horario: { inicio: "08:00", fim: "18:00" }, ips_permitidos: ["10.0.0.0/8"] }, analista_cadastro: { endpoints: ["GET /cpf/:cpf"], campos_permitidos: ["success", "cpf", "name", "gender"], limite_diario: 200, horario: { inicio: "07:00", fim: "20:00" }, ips_permitidos: ["10.0.0.0/8", "172.16.0.0/12"] }, sistema_compliance: { endpoints: ["GET /cpf/:cpf"], campos_permitidos: [ "success", "cpf", "name", "birthDate", "gender" ], limite_diario: 1000, horario: null, // sem restrição ips_permitidos: ["10.0.1.50/32"] } }; // Middleware de controle de acesso function verificarAcesso(role, campo) { const permissoes = roles[role]; if (!permissoes) return false; return permissoes.campos_permitidos.includes(campo); } // Filtrar resposta da API baseado na role async function consultarCPFComFiltro(cpf, userRole) { const response = await fetch( `https://api.cpfhub.io/cpf/${cpf}`, { headers: { "x-api-key": process.env.CPFHUB_API_KEY } } ); const resultado = await response.json(); if (!resultado.success) return resultado; const dadosFiltrados = {}; const permissoes = roles[userRole]; for (const campo of permissoes.campos_permitidos) { if (campo in resultado.data) { dadosFiltrados[campo] = resultado.data[campo]; } else if (campo === "success") { dadosFiltrados[campo] = resultado.success; } } return { success: true, data: dadosFiltrados }; } ``` --- ## Implementação com API gateway Um API Gateway centraliza o controle de acesso e elimina a necessidade de cada microsserviço implementar sua própria lógica de autorização: - **Autenticação centralizada** -- valide tokens JWT ou API keys em um único ponto antes de rotear para o serviço backend - **Rate limiting por identidade** -- aplique limites diferentes para cada usuário ou sistema consumidor - **Filtragem de resposta** -- remova campos sensíveis da resposta antes de devolvê-la ao consumidor, baseado em suas permissões - **Logging unificado** -- registre todas as chamadas com identificação do consumidor para auditoria - **Revogação instantânea** -- bloqueie acessos comprometidos imediatamente no gateway sem alterar serviços internos --- ## Auditoria de acessos O controle de acesso granular só é eficaz se acompanhado de auditoria contínua. Cada acesso a dados de CPF deve gerar um registro que responda: - **Quem acessou** -- identificação inequívoca do usuário ou sistema que realizou a consulta - **Quando acessou** -- timestamp preciso da requisição e da resposta - **O que acessou** -- quais campos foram retornados ao consumidor - **Por que acessou** -- finalidade declarada pelo consumidor no momento da requisição - **De onde acessou** -- IP de origem, user-agent e localização geográfica estimada Esses registros são essenciais para responder a solicitações da [ANPD](https://www.gov.br/anpd) (Autoridade Nacional de Proteção de Dados) e para investigações internas de incidentes. --- ## Perguntas frequentes ### O que é necessário para implementar validação de CPF neste contexto? A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação. ### A API CPFHub.io funciona para todos os volumes de consulta? Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. ### Como garantir conformidade com a LGPD ao usar uma API de CPF? Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade. ### Quanto tempo leva para integrar a API CPFHub.io? A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key`. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## Conclusão O controle de acesso granular transforma a segurança de APIs de CPF de uma abordagem binária para um modelo inteligente que minimiza riscos e atende aos requisitos da LGPD. Ao definir permissões por papel, campo, volume e contexto, você garante que cada ator no sistema acesse apenas o necessário para sua função. A API da [**CPFHub.io**](https://www.cpfhub.io/) se integra a esse modelo por meio de API keys individuais por sistema e logs detalhados de auditoria — comece com 50 consultas gratuitas em [cpfhub.io](https://www.cpfhub.io/).