Clave API vs JWT vs OAuth2: elija la autenticación correcta para su API

Estás creando una API. Los puntos finales funcionan. Los datos fluyen. Ahora necesitas responder una. Pregunta antes del envío: ¿cómo prueban quiénes son las personas que llaman?

Tres enfoques dominan la autenticación API: claves API, JWT y OAuth2. Cada uno resuelve un problema diferente. Elija el incorrecto y diseñará demasiado una integración simple o dejar una brecha de seguridad en uno complejo.

Esta guía compara los tres en siete criterios, con ejemplos de código de trabajo, una decisión tabla y recomendaciones claras basadas en el caso de uso de su API.

Autenticación de clave API: el enfoque directo

Una clave API es una cadena larga y aleatoria que identifica y autoriza a la persona que llama. El cliente envía con cada solicitud, el servidor la busca y, si coincide con una clave válida, la solicitud pasa.

Así es como se ve una llamada de clave API con la 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"}'

Respuesta:

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

La x-api-key El encabezado lleva la credencial. Sin tokens para negociar, sin redirecciones, sin servidores de autorización. Un encabezado, una búsqueda, una respuesta.

Cuando las claves API ganan

• Llamadas de servidor a servidor. Su backend llama a otro backend. Ningún usuario es involucrados. Un trabajo cron consulta una API de geolocalización de IP. Una canalización de CI ejecuta comprobaciones de DNS. la persona que llama Siempre es un servidor de confianza.
• API de utilidad. API que realizan operaciones sin estado (hash, codificación, validación, búsquedas) donde cada solicitud es independiente. botoi usa claves API por este motivo: Más de 150 puntos finales, todos sin estado, todos de servidor a servidor.
• Integración rápida. Un desarrollador copia la clave, agrega un encabezado y comienza llamando. Sin danza OAuth, sin lógica de actualización de token, sin punto final JWKS para configurar.

Aquí está la misma llamada en 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..."

Donde las claves API se quedan cortas

• Sin identidad de usuario. Una clave API identifica la cuenta, no el usuario. si tres desarrolladores comparten una clave, no se puede saber quién realizó cada solicitud.
• La revocación requiere un viaje de ida y vuelta. Revocar una clave significa actualizar la del servidor. almacén de claves. Hasta que se actualice el caché, la clave anterior seguirá funcionando.
• Sin acceso delegado. No puedes darle una aplicación de terceros limitada y temporal acceso a los recursos de un usuario solo con una clave API.

Autenticación JWT: sesiones de usuario sin estado

Un JSON Web Token (JWT) es un objeto JSON firmado que contiene afirmaciones sobre la persona que llama. la autenticacion el servidor lo crea al iniciar sesión; el cliente lo envía con cada solicitud; el servidor de recursos verifica la firma sin volver a llamar al servidor de autenticación.

// 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
)

El servidor verifica la firma con la clave pública. Si la firma se verifica y exp no ha pasado, la solicitud está autorizada. No se necesita búsqueda en la base de datos.

Cuando ganan los JWT

• API orientadas al usuario con mucho tráfico. Una aplicación móvil envía un JWT en cada solicitud. La puerta de enlace API verifica la firma localmente en lugar de consultar un almacén de sesiones en cada llamada. A 10.000 solicitudes por segundo, esa llamada a la base de datos que usted omitió fue importante.
• Arquitecturas de microservicios. El servicio A llama al servicio B con un JWT. Servicio B lo valida localmente y extrae la identificación del usuario y los roles de los reclamos. Sin sesión compartida base de datos entre servicios.
• Autorización de corta duración. Un token de 15 minutos para cargar un archivo. 5 minutos token para una confirmación de pago. La caducidad está incorporada en el propio token.

Aquí está el middleware Express que verifica un 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" });
  }
}

Donde las JWT se quedan cortas

• La revocación de tokens es difícil. Un JWT es válido hasta que caduque. Si un usuario inicia sesión o necesita revocar el acceso, necesita una lista de bloqueo del lado del servidor, que devuelve el llamada a la base de datos que estaba tratando de evitar.
• Tamaño de carga útil. Cada reclamo agrega bytes. Un JWT con roles de usuario, permisos, y los metadatos pueden alcanzar 1-2 KB. Eso es de 1 a 2 KB en cada solicitud, en cada encabezado.
• Complejidad de rotación de claves. Cuando rota las claves de firma, se firman tokens antiguos con la clave anterior deben seguir siendo válidos hasta que caduquen. Esto significa servir a múltiples claves públicas a través de un punto final JWKS y manejo de kid reclamo de encabezado.

OAuth2: acceso delegado para terceros

OAuth2 es un marco de autorización, no un protocolo de autenticación. Le permite al usuario otorgar un aplicación de terceros acceso limitado a sus recursos en otro servicio, sin compartir su contraseña.

El ejemplo clásico: un usuario autoriza a una herramienta de gestión de proyectos a leer su GitHub repositorios. El usuario inicia sesión en GitHub, aprueba alcances específicos y la herramienta recibe una token de acceso con alcance a esos permisos.

# 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

Cuando OAuth2 gana

• Integraciones de terceros. Tienes una plataforma y quieres desarrolladores externos. para crear aplicaciones que accedan a los datos de sus usuarios. OAuth2 brinda a los usuarios control sobre lo que hace cada aplicación. puede acceder.
• Alcances de grano fino. read:repos pero no delete:repos. write:issues pero no admin:org. OAuth2 Los ámbitos permiten a los usuarios aprobar permisos específicos.
• "Iniciar sesión con X" fluye. Cuando su aplicación utiliza Google, GitHub o Microsoft para Al iniciar sesión, estás usando OAuth2 (a menudo con OpenID Connect en la parte superior) para obtener un token de identidad.

Donde OAuth2 se queda corto

• Complejidad. OAuth2 tiene cuatro tipos de concesión, tokens de actualización y autorización. servidores, URI de redireccionamiento, PKCE y puntos finales de introspección de tokens. Para una API de utilidad con sin contexto de usuario, esto es una sobrecarga sin ningún beneficio.
• Fricción de integración. Un desarrollador que quiere llamar a su punto final hash no quiere registrar una aplicación OAuth, configurar URI de redireccionamiento ni intercambiar autorización códigos. Quieren una clave y un comando curl.
• Carga de gestión de tokens. Los tokens de acceso caducan. Los tokens de actualización rotan. Los clientes necesitan una lógica de reintento para las respuestas 401. Para llamadas simples de servidor a servidor, esto es maquinaria innecesaria.

tabla comparativa

Criterios	clave API	JWT	OAuth2
tiempo de integración	Minutos	Horas	Días
Identidad de usuario	Nivel de cuenta	Nivel de usuario (reclamaciones)	Nivel de usuario (ámbitos)
Verificación sin estado	No (búsqueda en el servidor)	Sí (verificación de firma)	Depende del formato del token
Velocidad de revocación	Inmediato (tecla eliminar)	Retrasado (hasta el vencimiento)	Inmediata (revocar ficha)
Acceso delegado	No	No	Sí
Soporte de terceros	Pobre	Buena	Excelente
Apta para navegadores	No (exposición clave)	Sí (de corta duración)	Sí (código de autorización + PKCE)

Marco de decisión: elija según su caso de uso

Deja de preguntar "¿cuál es más seguro?" Los tres son seguros cuando se usan correctamente. el derecho pregunta: "¿quién llama a mi API y por qué?"

• El servidor llama al servidor, ninguna usuario involucrada: Clave API. Su backend llama a API de utilidad para búsquedas de DNS, hash o validación de datos. Una clave, un encabezado, listo.
• Su propia aplicación autentica a sus propias usuarios: JWT. Tu aplicación móvil o SPA envía solicitudes en nombre de un usuario que ha iniciado sesión. Firme un JWT de corta duración al iniciar sesión, verifíquelo en cada solicitud sin una tienda de sesión.
• Las aplicaciones de terceros acceden a los datos del usuario: OAuth2. Los desarrolladores externos crean integraciones con su plataforma. Los usuarios controlan a qué puede acceder cada aplicación a través del ámbito pantallas de consentimiento.

Gestión de claves API a escala con Unkey

Las claves API suenan simples hasta que necesitas hacerles un hash, hacer cumplir límites de tasa, establecer el vencimiento fechas, realice un seguimiento del uso por clave y rótelas sin tiempo de inactividad. Construyendo todo esto desde cero lleva semanas.

sin clave es un abierto Servicio de administración de claves API de origen que maneja la creación, verificación, limitación de velocidad y analítica. botoi usa Unkey para administrar todas las claves API en sus más de 150 puntos finales.

Cree una clave de alcance con limitación de velocidad incorporada:

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..."

Verifícalo en tu 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 almacena claves con hash (nunca en texto plano), impone límites de velocidad en el borde y proporciona le ofrece un panel de análisis que muestra el uso por clave. Cuando una clave necesita rotación, crea una nueva y establecer una caducidad para el anterior. Sin tiempo de inactividad, sin cambios de código.

Lista de verificación de seguridad para cada enfoque

Claves API

• Envíe solo a través de HTTPS. Nunca incruste claves en URL o cadenas de consulta.
• Almacenar hash en el servidor. Nunca registre claves sin formato.
• Claves de alcance para permisos específicos (solo lectura, escritura, administrador).
• Establecer fechas de vencimiento. Forzar la rotación cada 90 días.
• Utilice un encabezado personalizado (x-api-key) en lugar de Authorization a Evite el almacenamiento en caché de credenciales del navegador.

JWT

• Utilice firma asimétrica (RS256 o ES256). Nunca utilice HS256 con un secreto compartido en sistemas distribuidos.
• Mantenga corta la vida útil del token: de 5 a 15 minutos para los tokens de acceso.
• Validar iss, aud, y exp reclamaciones en cada solicitud.
• Publicar claves públicas a través de un punto final JWKS. Rote las claves de firma según un cronograma.
• Nunca almacene datos confidenciales en la carga útil. Los JWT están codificados, no cifrados.

OAuth2

• Utilice el flujo del Código de autorización con PKCE para todos los clientes, incluidos SPA y dispositivos móviles aplicaciones.
• Nunca utilice el flujo implícito. Está en desuso en OAuth 2.1 por una buena razón.
• Almacene los secretos del cliente únicamente en el servidor. Nunca los envíes en aplicaciones móviles o frontend. código.
• Validar state parámetros para evitar ataques CSRF en la URL de devolución de llamada.
• Utilice tokens de acceso de corta duración con rotación de tokens de actualización.

Puntos clave

• Claves API son la elección correcta para las API de utilidades de servidor a servidor. ellos son rápido de integrar, fácil de administrar y suficiente cuando no se necesita identidad de usuario. botoi los utiliza en más de 150 puntos finales con Unkey para la administración.
• JWT son la elección correcta para sesiones de usuarios sin estado. ellos eliminan búsquedas en el almacén de sesiones a gran escala, pero la revocación de tokens necesita infraestructura adicional.
• OAuth2 es la elección correcta cuando las aplicaciones de terceros necesitan acceso limitado a recursos del usuario. La complejidad se justifica por el modelo de seguridad que proporciona.
• Elija basándose en la persona que llama, no en las exageraciones. Una API de utilidad con OAuth2 está sobrediseñada. un La API de plataforma con solo claves API no puede otorgar acceso delegado.
• Combine enfoques cuando su producto lo requiera. Claves API para integraciones directas, OAuth2 para socios del mercado, JWT para sesiones de usuarios registrados.