Chaves de API: o guia prático para proteger suas integrações

Se você já integrou um sistema com um gateway de pagamento, um serviço de nota fiscal eletrônica ou uma API de WhatsApp Business, provavelmente já usou uma chave de API. É um dos métodos mais comuns de autenticação entre sistemas, principalmente em integrações servidor a servidor.

Uma chave de API é, na prática, uma string longa e aleatória que identifica uma conta ou aplicação. Diferente de um login tradicional, ela não representa uma pessoa específica, e sim "quem tem posse da chave". Por isso, proteger essa chave é tão importante quanto proteger uma senha.

Um cuidado essencial, muitas vezes esquecido, é nunca guardar a chave em texto puro no banco de dados. O ideal é armazenar apenas o hash dela, da mesma forma que se faz com senhas:

<?php
// Gerando uma chave de API segura
function gerarApiKey(): string {
    return bin2hex(random_bytes(32));
}

// Validando a chave recebida em uma requisição
function validarApiKey(): array {
    $chave = $_SERVER['HTTP_X_API_KEY'] ?? null;

    if (!$chave) {
        http_response_code(401);
        exit(json_encode(['erro' => 'Chave de API ausente']));
    }

    $conta = buscarContaPorApiKeyHash(hash('sha256', $chave));

    if (!$conta) {
        http_response_code(403);
        exit(json_encode(['erro' => 'Chave de API invalida']));
    }

    return $conta;
}

Outro ponto prático é sempre permitir a revogação e a rotação das chaves. Se uma chave vazar (por exemplo, publicada acidentalmente em um repositório de código), o ideal é conseguir desativá-la imediatamente e gerar uma nova, sem precisar recriar toda a conta.

Vale também aplicar limite de requisições (rate limiting) por chave, para reduzir o impacto de um possível uso indevido, e nunca reaproveitar a mesma chave para ambientes diferentes, como produção e testes.

Chaves de API são simples de implementar e funcionam muito bem quando o objetivo é apenas identificar uma aplicação, sem necessidade de saber qual usuário específico está por trás da requisição.