Chave de API vs JWT vs OAuth2: escolha a autenticação certa para sua API

Você está construindo uma API. Os terminais funcionam. Os dados fluem. Agora você precisa responder uma pergunta antes do envio: como os chamadores provam quem são?

Três abordagens dominam a autenticação de API: chaves de API, JWTs e OAuth2. Cada um resolve um problema diferente. Escolha o errado e você irá projetar demais uma integração simples ou deixar uma lacuna de segurança em uma lacuna complexa.

Este guia compara todos os três em sete critérios, com exemplos de códigos funcionais, uma decisão tabela e recomendações claras com base no caso de uso da sua API.

Autenticação de chave API: a abordagem direta

Uma chave de API é uma longa string aleatória que identifica e autoriza o chamador. O cliente envia a cada solicitação, o servidor pesquisa e, se corresponder a uma chave válida, a solicitação passa.

Esta é a aparência de uma chamada de chave de API com a API botoi:

# API key in a custom header
curl -s -X POST https://api.botoi.com/v1/dns/lookup \\
  -H "Content-Type: application/json" \\
  -H "x-api-key: your_api_key_here" \\
  -d '{"domain": "example.com", "type": "A"}'

Resposta:

{
  "success": true,
  "data": {
    "domain": "example.com",
    "type": "A",
    "records": [
      { "type": "A", "value": "93.184.216.34", "ttl": 86400 }
    ]
  }
}

O x-api-key cabeçalho carrega a credencial. Sem tokens para negociar, sem redirecionamentos, sem servidores de autorização. Um cabeçalho, uma pesquisa, uma resposta.

Quando as chaves de API vencem

• Chamadas de servidor para servidor. Seu back-end chama outro back-end. Nenhum usuário é envolvido. Um cron job consulta uma API de geolocalização de IP. Um pipeline de CI executa verificações de DNS. O chamador é sempre um servidor confiável.
• APIs de utilitários. APIs que realizam operações sem estado (hashing, codificação, validação, pesquisas) onde cada solicitação é independente. botoi usa chaves de API por este motivo: Mais de 150 endpoints, todos sem estado, todos de servidor para servidor.
• Integração rápida. Um desenvolvedor copia a chave, adiciona um cabeçalho e inicia ligando. Nenhuma dança OAuth, nenhuma lógica de atualização de token, nenhum endpoint JWKS para configurar.

Aqui está a mesma chamada em Node.js:

const response = await fetch("https://api.botoi.com/v1/hash", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.BOTOI_API_KEY,
  },
  body: JSON.stringify({ text: "hello world", algorithm: "sha256" }),
});

const result = await response.json();
// result.data.hash = "b94d27b9934d3e08..."

Onde as chaves de API ficam aquém

• Sem identidade de usuário. Uma chave de API identifica a conta, não o usuário. Se três desenvolvedores compartilham uma chave, você não pode dizer quem fez qual solicitação.
• A revogação requer uma viagem de ida e volta. Revogar uma chave significa atualizar o servidor armazenamento de chaves. Até que o cache seja atualizado, a chave antiga ainda funciona.
• Sem acesso delegado. Você não pode fornecer recursos limitados e temporários a um aplicativo de terceiros acesso aos recursos de um usuário apenas com uma chave de API.

Autenticação JWT: sessões de usuário sem estado

Um JSON Web Token (JWT) é um objeto JSON assinado que carrega declarações sobre o chamador. A autorização o servidor cria no login; o cliente envia com cada solicitação; o servidor de recursos verifica a assinatura sem chamar o servidor de autenticação novamente.

// Header
{
  "alg": "RS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "user_12345",
  "email": "dev@example.com",
  "role": "admin",
  "iat": 1775000000,
  "exp": 1775000900   // 15 minutes
}

// Signature
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

O servidor verifica a assinatura com a chave pública. Se a assinatura for verificada e exp não passou, a solicitação está autorizada. Nenhuma pesquisa no banco de dados é necessária.

Quando os JWTs vencem

• APIs voltadas para o usuário com alto tráfego. Um aplicativo móvel envia um JWT a cada pedido. O gateway de API verifica a assinatura localmente em vez de consultar um armazenamento de sessão em cada chamada. A 10.000 solicitações por segundo, aquela chamada de banco de dados que você ignorou é importante.
• Arquiteturas de microsserviços. O serviço A chama o serviço B com um JWT. Serviço B valida-o localmente e extrai o ID e as funções do usuário das declarações. Nenhuma sessão compartilhada banco de dados entre serviços.
• Autorização de curta duração. Um token de 15 minutos para upload de arquivo. 5 minutos token para uma confirmação de pagamento. A expiração está inserida no próprio token.

Aqui está o middleware Express que verifica um JWT:

import jwt from "jsonwebtoken";

function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });

  try {
    const decoded = jwt.verify(token, process.env.JWT_PUBLIC_KEY, {
      algorithms: ["RS256"],
    });
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: "Invalid or expired token" });
  }
}

Onde os JWTs ficam aquém

• A revogação do token é difícil. Um JWT é válido até expirar. Se um usuário fizer logon ou precisar revogar o acesso, você precisa de uma lista de bloqueio do lado do servidor, que traz de volta o chamada de banco de dados que você estava tentando evitar.
• Tamanho da carga útil. Cada declaração adiciona bytes. Um JWT com funções de usuário, permissões, e os metadados podem atingir 1-2 KB. São 1 a 2 KB em cada solicitação, em cada cabeçalho.
• Complexidade de rotação de chave. Quando você alterna as chaves de assinatura, os tokens antigos são assinados com a chave anterior precisam permanecer válidos até expirarem. Isso significa servir vários chaves públicas por meio de um endpoint JWKS e manipulando o kid reivindicação de cabeçalho.

OAuth2: acesso delegado para terceiros

OAuth2 é uma estrutura de autorização, não um protocolo de autenticação. Ele permite que um usuário conceda um aplicativo de terceiros limitou o acesso aos seus recursos em outro serviço, sem compartilhar sua senha.

O exemplo clássico: um usuário autoriza uma ferramenta de gerenciamento de projetos a ler seu GitHub repositórios. O usuário faz login no GitHub, aprova escopos específicos e a ferramenta recebe um token de acesso com escopo para essas permissões.

# Step 1: Redirect user to authorization server
GET https://auth.example.com/authorize?
  response_type=code&
  client_id=your_app_id&
  redirect_uri=https://yourapp.com/callback&
  scope=read:repos+write:issues&
  state=random_csrf_token

# Step 2: Exchange authorization code for tokens
POST https://auth.example.com/token
  grant_type=authorization_code&
  code=AUTH_CODE_FROM_CALLBACK&
  client_id=your_app_id&
  client_secret=your_app_secret&
  redirect_uri=https://yourapp.com/callback

# Step 3: Call the API with the access token
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \\
  https://api.example.com/v1/repos

Quando o OAuth2 vence

• Integrações de terceiros. Você administra uma plataforma e quer desenvolvedores externos para criar aplicativos que acessem os dados dos seus usuários. OAuth2 dá aos usuários controle sobre o que cada aplicativo pode acessar.
• Escopos refinados. read:repos mas não delete:repos. write:issues mas não admin:org. OAuth2 os escopos permitem que os usuários aprovem permissões específicas.
• Fluxos "Entrar com X". Quando seu aplicativo usa Google, GitHub ou Microsoft para login, você está usando OAuth2 (geralmente com OpenID Connect na parte superior) para obter um token de identidade.

Onde o OAuth2 fica aquém

• Complexidade. OAuth2 tem quatro tipos de concessão, tokens de atualização e autorização servidores, URIs de redirecionamento, PKCE e pontos de extremidade de introspecção de token. Para uma API utilitária com sem contexto de usuário, isso é uma sobrecarga sem nenhum benefício.
• Fricção de integração. Um desenvolvedor que deseja chamar seu endpoint hash não deseja registrar um aplicativo OAuth, configurar URIs de redirecionamento e trocar autorização códigos. Eles querem uma chave e um comando curl.
• Carga de gerenciamento de token. Os tokens de acesso expiram. Os tokens de atualização giram. Os clientes precisam de lógica de repetição para respostas 401. Para chamadas simples de servidor para servidor, isso é máquinas desnecessárias.

Tabela de comparação

Critérios	Chave de API	JWT	OAuth2
Tempo de integração	Minutos	Horas	Dias
Identidade do usuário	Nível da conta	Nível do usuário (reivindicações)	Nível do usuário (escopos)
Verificação sem estado	Não (pesquisa de servidor)	Sim (verificação de assinatura)	Depende do formato do token
Velocidade de revogação	Imediato (chave de exclusão)	Atrasado (até o vencimento)	Imediato (revogar token)
Acesso delegado	Não	Não	Sim
Suporte de terceiros	Pobre	Boa	Excelente
Adequado para navegadores	Não (exposição principal)	Sim (de curta duração)	Sim (código de autorização + PKCE)

Estrutura de decisão: escolha com base no seu caso de uso

Pare de perguntar "o que é mais seguro?" Todos os três são seguros quando usados ​​corretamente. A direita pergunta: "quem está chamando minha API e por quê?"

• Servidor chama servidor, nenhum usuário envolvido: Chave de API. Seu back-end chama um API de utilitário para pesquisas de DNS, hash ou validação de dados. Uma chave, um cabeçalho, pronto.
• Seu próprio aplicativo autentica seus próprios usuários: JWT. Seu aplicativo móvel ou SPA envia solicitações em nome de um usuário logado. Assine um JWT de curta duração no login, verifique-o em cada solicitação sem um armazenamento de sessão.
• Aplicativos de terceiros acessam dados do usuário: OAuth2. Desenvolvedores externos criam integrações com sua plataforma. Os usuários controlam o que cada aplicativo pode acessar por meio de escopo telas de consentimento.

Gerenciando chaves de API em escala com Unkey

As chaves de API parecem simples até que você precise fazer hash, impor limites de taxa, definir expiração datas, rastreie o uso por chave e alterne-as sem tempo de inatividade. Construindo tudo isso a partir zero leva semanas.

Deschavear é um aberto serviço de gerenciamento de chaves de API de origem que lida com criação, verificação, limitação de taxa e análise. botoi usa Unkey para gerenciar todas as chaves de API em seus mais de 150 endpoints.

Crie uma chave com escopo com limitação de taxa integrada:

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

// Create a scoped API key with built-in rate limiting
const key = await unkey.keys.create({
  apiId: "api_your_api_id",
  prefix: "botoi",
  meta: { userId: "user_12345", plan: "pro" },
  expires: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days
  ratelimit: {
    type: "fast",
    limit: 100,
    refillRate: 10,
    refillInterval: 1000,
  },
});

// key.result.key = "botoi_3xK9m2..."

Verifique em seu middleware:

import { verifyKey } from "@unkey/api";

async function authMiddleware(req, res, next) {
  const apiKey = req.headers["x-api-key"];
  if (!apiKey) return res.status(401).json({ error: "Missing API key" });

  const result = await verifyKey(apiKey);

  if (!result.result.valid) {
    return res.status(result.result.code === "RATE_LIMITED" ? 429 : 403)
      .json({ error: result.result.code });
  }

  req.keyMeta = result.result.meta; // { userId, plan }
  next();
}

Unkey armazena chaves com hash (nunca em texto simples), impõe limites de taxa na borda e fornece você tem um painel de análise mostrando o uso por chave. Quando uma chave precisar de rotação, crie uma nova e defina uma expiração para o antigo. Sem tempo de inatividade, sem alterações de código.

Lista de verificação de segurança para cada abordagem

Chaves de API

• Envie apenas por HTTPS. Nunca incorpore chaves em URLs ou strings de consulta.
• Armazene o hash no servidor. Nunca registre chaves brutas.
• Chaves de escopo para permissões específicas (somente leitura, gravação, administrador).
• Defina datas de expiração. Forçar a rotação a cada 90 dias.
• Use um cabeçalho personalizado (x-api-key) em vez de Authorization para evite o cache de credenciais do navegador.

JWTs

• Use assinatura assimétrica (RS256 ou ES256). Nunca use HS256 com um segredo compartilhado em sistemas distribuídos.
• Mantenha a vida útil do token curta: 5 a 15 minutos para tokens de acesso.
• Validar iss, aud, e exp reivindicações em cada pedido.
• Publique chaves públicas por meio de um endpoint JWKS. Gire as chaves de assinatura de acordo com uma programação.
• Nunca armazene dados confidenciais na carga útil. JWTs são codificados, não criptografados.

OAuth2

• Use o fluxo do código de autorização com PKCE para todos os clientes, incluindo SPAs e dispositivos móveis aplicativos.
• Nunca use o fluxo implícito. Está obsoleto no OAuth 2.1 por um bom motivo.
• Armazene segredos do cliente apenas no servidor. Nunca os envie em aplicativos móveis ou front-end código.
• Validar state parâmetros para evitar ataques CSRF no URL de retorno de chamada.
• Use tokens de acesso de curta duração com rotação de token de atualização.

Pontos-chave

• Chaves de API são a escolha certa para APIs de utilitários de servidor para servidor. Eles são rápido de integrar, fácil de gerenciar e suficiente quando nenhuma identidade de usuário é necessária. botoi usa-os em mais de 150 endpoints com Unkey para gerenciamento.
• JWTs são a escolha certa para sessões de usuário sem estado. Eles eliminam pesquisas de armazenamento de sessão em alta escala, mas a revogação de token precisa de infraestrutura extra.
• OAuth2 é a escolha certa quando aplicativos de terceiros precisam de acesso com escopo para recursos do usuário. A complexidade é justificada pelo modelo de segurança que proporciona.
• Escolha com base no chamador, não no hype. Uma API utilitária com OAuth2 tem engenharia excessiva. Um A API da plataforma com apenas chaves de API não pode conceder acesso delegado.
• Combine abordagens quando seu produto exigir. Chaves de API para integrações diretas, OAuth2 para parceiros de mercado, JWTs para sessões de usuários logados.