# Como gerenciar múltiplas chaves de API para diferentes ambientes (dev, staging, prod) > Aprenda a gerenciar múltiplas chaves de API de CPF para ambientes de desenvolvimento, staging e produção com segurança e organização. **Publicado:** 17/04/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/gerenciar-multiplas-chaves-api-diferentes-ambientes --- Gerenciar múltiplas chaves de API por ambiente — dev, staging e prod — evita que testes consumam cota de produção, mantém métricas separadas por contexto e garante que uma chave comprometida em desenvolvimento nunca afete o ambiente de produção. ## Introdução Usar a mesma chave de API em desenvolvimento, staging e produção é uma das práticas mais comuns e mais perigosas em projetos de software. Além de comprometer a segurança, essa prática mistura métricas de consumo, dificulta a auditoria e pode causar esgotamento de cota por testes realizados no ambiente errado. --- ## Por que separar chaves por ambiente A separação de chaves não é burocracia, é proteção: - **Isolamento de cota** -- testes no desenvolvimento não consomem a cota de produção - **Segurança** -- se uma chave de dev vazar, a produção não é afetada - **Métricas limpas** -- cada ambiente tem seus próprios números de uso para análise precisa - **Auditoria** -- é possível rastrear exatamente qual ambiente gerou cada consulta - **Revogação segura** -- revogar uma chave comprometida não afeta outros ambientes --- ## Estrutura recomendada de ambientes Organize suas chaves seguindo esta estrutura: | Ambiente | Finalidade | Tipo de chave | Cota recomendada | |---|---|---|---| | Development | Desenvolvimento local | Gratuita/sandbox | 100 req/dia | | Testing | Testes automatizados | Gratuita/sandbox | 50 req/dia | | Staging | Pré-produção | Mesmo plano de prod | 500 req/dia | | Production | Aplicação real | Paga com SLA | Conforme demanda | | CI/CD | Pipeline de integração | Gratuita/limitada | 20 req/dia | --- ## Implementação com variáveis de ambiente em Python ```python import os import requests from enum import Enum from dataclasses import dataclass class Ambiente(Enum): DEVELOPMENT = "development" TESTING = "testing" STAGING = "staging" PRODUCTION = "production" @dataclass class ConfigAPI: api_key: str base_url: str timeout: int max_retries: int cache_ttl: int class CPFAPIManager: CONFIGS = { Ambiente.DEVELOPMENT: ConfigAPI( api_key=os.environ.get("CPFHUB_DEV_KEY", ""), base_url="https://api.cpfhub.io/cpf", timeout=10, max_retries=1, cache_ttl=86400 ), Ambiente.TESTING: ConfigAPI( api_key=os.environ.get("CPFHUB_TEST_KEY", ""), base_url="https://api.cpfhub.io/cpf", timeout=5, max_retries=0, cache_ttl=0 ), Ambiente.STAGING: ConfigAPI( api_key=os.environ.get("CPFHUB_STAGING_KEY", ""), base_url="https://api.cpfhub.io/cpf", timeout=10, max_retries=2, cache_ttl=3600 ), Ambiente.PRODUCTION: ConfigAPI( api_key=os.environ.get("CPFHUB_PROD_KEY", ""), base_url="https://api.cpfhub.io/cpf", timeout=5, max_retries=3, cache_ttl=3600 ), } def __init__(self): env_name = os.environ.get("APP_ENV", "development") self.ambiente = Ambiente(env_name) self.config = self.CONFIGS[self.ambiente] self._validar_configuracao() def _validar_configuracao(self): if not self.config.api_key: raise ValueError( f"Chave de API não configurada para o ambiente {self.ambiente.value}. " f"Defina a variável de ambiente correspondente." ) def consultar_cpf(self, cpf: str) -> dict: cpf_limpo = cpf.replace(".", "").replace("-", "") response = requests.get( f"{self.config.base_url}/{cpf_limpo}", headers={"x-api-key": self.config.api_key}, timeout=self.config.timeout ) if response.status_code == 200 and response.json()["success"]: d = response.json()["data"] return { "cpf": d["cpf"], "nome": d["name"], "nascimento": d["birthDate"], "ambiente": self.ambiente.value } return None def info(self): chave_mascarada = self.config.api_key[:8] + "..." if self.config.api_key else "N/A" print(f"Ambiente: {self.ambiente.value}") print(f"Chave: {chave_mascarada}") print(f"Timeout: {self.config.timeout}s") print(f"Max retries: {self.config.max_retries}") print(f"Cache TTL: {self.config.cache_ttl}s") # Uso manager = CPFAPIManager() manager.info() resultado = manager.consultar_cpf("12345678909") ``` --- ## Configuração com arquivos .env Organize as chaves em arquivos .env específicos por ambiente: ```bash # .env.development APP_ENV=development CPFHUB_DEV_KEY=cpfhub_dev_abc123def456 # .env.staging APP_ENV=staging CPFHUB_STAGING_KEY=cpfhub_stg_ghi789jkl012 # .env.production APP_ENV=production CPFHUB_PROD_KEY=cpfhub_prod_mno345pqr678 # .gitignore (NUNCA commitar arquivos .env) .env* !.env.example ``` --- ## Boas práticas de segurança para gestão de chaves Proteja suas chaves em todos os ambientes: - **Nunca commitar chaves** -- adicione todos os arquivos .env ao .gitignore sem exceção - **Rotacionar periodicamente** -- troque chaves de produção a cada 90 dias como medida preventiva - **Princípio do menor privilégio** -- cada ambiente deve ter apenas as permissões estritamente necessárias - **Secrets manager** -- em produção, utilize AWS Secrets Manager, HashiCorp Vault ou Azure Key Vault - **Auditoria de acesso** -- registre quem acessou ou modificou chaves para rastreabilidade completa O [OWASP API Security Top 10](https://owasp.org/www-project-api-security/) lista exposição de chaves de API como um dos riscos mais críticos em integrações — reforçando a importância de nunca hardcodar credenciais no código-fonte. --- ## Automação no CI/CD Integre a gestão de chaves ao pipeline de CI/CD de forma segura: - **Variáveis secretas do CI** -- configure as chaves como secrets no GitHub Actions, GitLab CI ou Jenkins - **Injeção em runtime** -- as chaves devem ser injetadas no momento da execução, nunca no build da imagem - **Testes com chave de teste** -- o pipeline deve usar uma chave dedicada para testes automatizados - **Validação de ambiente** -- inclua um step que verifica se a chave corresponde ao ambiente correto antes do deploy - **Alertas de expiração** -- configure notificações para chaves que estão próximas da data de rotação --- ## Perguntas frequentes ### Quantas chaves de API posso criar na CPFHub.io? A CPFHub.io permite criar múltiplas chaves de API em [app.cpfhub.io/settings/billing](https://app.cpfhub.io/settings/billing), o que viabiliza a separação por ambiente sem custo adicional. Cada chave pode ser revogada individualmente — se a chave de staging for comprometida, a de produção continua intacta. O consumo de todas as chaves é somado para fins de faturamento dentro do mesmo plano contratado. ### O que acontece se a cota de produção for esgotada por testes no ambiente errado? Se testes realizados com a chave de produção consumirem toda a cota mensal, as consultas seguintes são cobradas automaticamente a R$ 0,15/unidade — sem bloqueio da API. Por isso, separar chaves por ambiente não é apenas uma questão de organização: é uma proteção direta contra custos inesperados. O consumo pode ser monitorado em [app.cpfhub.io/settings/billing](https://app.cpfhub.io/settings/billing). ### Como implementar rotação automática de chaves de API? O processo recomendado é: (1) gerar uma nova chave no painel; (2) atualizar os secrets do ambiente alvo (AWS Secrets Manager, GitHub Secrets, etc.); (3) fazer o deploy da aplicação com a nova chave; (4) confirmar que a nova chave está operacional nas métricas; (5) revogar a chave antiga. Esse processo elimina qualquer janela de indisponibilidade e pode ser automatizado com scripts de rotação agendados a cada 90 dias. ### É possível usar uma única chave de sandbox para desenvolvimento e testes automatizados? Tecnicamente sim, mas não é recomendado. Testes automatizados em CI/CD podem gerar picos de consumo que consomem a cota da chave de dev, quebrando o ambiente de desenvolvimento local. A boa prática é ter uma chave exclusiva para CI/CD com limite diário baixo (20 requisições), garantindo que o pipeline de testes não interfira no desenvolvimento manual. ### Leia também - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Quando migrar de API gratuita para versão paga](https://cpfhub.io/blog/quando-migrar-api-gratuita-versao-paga) - [Como monitorar consumo e cotas de APIs gratuitas de CPF](https://cpfhub.io/blog/monitorar-consumo-cotas-apis-gratuitas-cpf) --- ## Conclusão Gerenciar múltiplas chaves de API por ambiente é uma prática essencial de segurança e organização que protege sua produção, mantém métricas limpas e facilita a auditoria. Com a estrutura apresentada neste artigo — ambientes separados, variáveis de ambiente, secrets no CI/CD e rotação periódica — você elimina os riscos mais comuns de exposição e consumo indevido de cota. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e configure suas chaves por ambiente desde o início do projeto.