Como gerenciar múltiplas chaves de API para diferentes ambientes (dev, staging, prod)

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:

Implementação com variáveis de ambiente em 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:

# .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 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, 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.

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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito — e configure suas chaves por ambiente desde o início do projeto.