Clave API

Definición

¿Alguna vez has usado una tarjeta de socio en una tienda? Pasas la tarjeta, el sistema te reconoce, y te aplican los descuentos sin tener que dar tu nombre y apellidos cada vez. Una clave API funciona igual - es un identificador único que le dice a la API “esta petición viene de esta aplicación específica” sin necesidad de enviar credenciales completas cada vez.

Una API key es básicamente una contraseña larga y aleatoria que identifica a tu aplicación. Cuando Google Maps te da una API key, esa clave les dice “esta petición viene del proyecto X del desarrollador Y.” Esto permite rastrear uso, aplicar límites de peticiones, y facturar correctamente. Importante: la API key identifica la aplicación, no necesariamente al usuario final - para eso están otros mecanismos como OAuth.

¿Por qué no usar simplemente usuario y contraseña? Porque las API keys están diseñadas para ser usadas programáticamente, pueden tener permisos limitados (solo lectura, por ejemplo), y si se comprometen, puedes revocarlas sin cambiar credenciales de usuario. Además, son fáciles de rotar regularmente - algo impensable si tuvieras que cambiar tu contraseña cada mes.

Ejemplo

APIs de Clima y Mapas: OpenWeatherMap o Google Maps te dan una API key cuando te registras. Incluyes “api_key=abc123…” en cada petición. Ellos saben exactamente cuántas peticiones haces, te muestran estadísticas en tu dashboard, y te cobran o limitan según tu plan. Si alguien roba tu clave, la revocas y generas una nueva en segundos.

Servicios de Email Transaccional: Cuando integras SendGrid o Mailgun en tu aplicación, usas una API key para enviar emails. La clave puede tener permisos específicos - una para enviar, otra para ver estadísticas, otra para gestionar listas. Si un servicio se compromete, solo revocas esa clave específica.

Servicios de Pago: Stripe te da claves separadas para test y producción. La clave de test (pk_test_XXXXX…) solo funciona con tarjetas de prueba. La de producción (pk_live_XXXXX…) procesa dinero real. Esta separación previene errores costosos y permite desarrollar sin riesgo.

APIs de Inteligencia Artificial: OpenAI, Anthropic, y otros proveedores de IA usan API keys para autenticar peticiones. Cada key está asociada a una cuenta con límites de uso y facturación. Puedes crear múltiples keys para diferentes proyectos y monitorear el consumo de cada uno independientemente.

Analogía

El Carné de Socio: Como la tarjeta de tu gimnasio o biblioteca. No es tu identidad oficial (DNI), pero te identifica dentro de ese sistema. Puedes tener varios carnés de diferentes lugares, cada uno con sus privilegios. Si pierdes uno, lo cancelas y te dan otro sin cambiar tu identidad real.

La Llave del Coche de Empresa: Tu empresa te da una llave específica para el coche de trabajo. Esa llave registra quién lo usa y cuándo. Si dejas la empresa o pierdes la llave, se desactiva. No es tu llave personal de casa - es una credencial específica para un propósito.

El Badge de Acceso a la Oficina: Tu tarjeta de acceso te identifica ante el sistema del edificio. Registra tus entradas y salidas, puede tener restricciones de horario o zonas. Si la pierdes, el equipo de seguridad la desactiva inmediatamente y te da una nueva. Tu identidad no ha cambiado, solo el token de acceso.

La Tarjeta de Puntos del Supermercado: Cada vez que compras, pasas la tarjeta. El supermercado sabe qué compras, cuándo, y te ofrece descuentos personalizados. Si alguien encuentra tu tarjeta, lo peor que puede hacer es acumular puntos para ti. Es una identificación de bajo riesgo para un propósito específico.

Code Example

// API Key en header (recomendado)
fetch('https://api.weather.com/v1/forecast', {
  headers: {
    'X-API-Key': 'YOUR-API-KEY-xxxxxxxxxxxxx'
  }
});

// API Key en query (menos seguro, visible en logs)
fetch('https://api.weather.com/v1/forecast?api_key=pk_live_XXXXX...');

// Validación de API Key en el servidor
function validateApiKey(req, res, next) {
  const apiKey = req.headers['x-api-key'];

  if (!apiKey) {
    return res.status(401).json({ error: 'API key requerida' });
  }

  // Buscar la key en la base de datos
  const keyData = await db.apiKeys.findOne({ key: apiKey, active: true });

  if (!keyData) {
    return res.status(403).json({ error: 'API key inválida o revocada' });
  }

  // Verificar rate limits
  if (keyData.requestsToday >= keyData.dailyLimit) {
    return res.status(429).json({ error: 'Límite diario excedido' });
  }

  req.apiKeyData = keyData;
  next();
}

Diagrama

sequenceDiagram
    participant C as App Cliente
    participant S as Servidor API
    participant DB as Base de Datos de Claves

    Note over C: La API Key puede enviarse
en diferentes ubicaciones

    rect rgb(240, 248, 255)
        Note over C,S: Opcion 1: Header (Recomendado)
        C->>S: GET /api/clima
X-API-Key: YOUR-API-KEY-abc123
    end

    rect rgb(255, 248, 240)
        Note over C,S: Opcion 2: Query Parameter (Menos Seguro)
        C->>S: GET /api/clima?api_key=YOUR-API-KEY-abc123
    end

    rect rgb(240, 255, 240)
        Note over C,S: Opcion 3: Cuerpo de la Peticion
        C->>S: POST /api/clima
{"api_key": "YOUR-API-KEY-abc123"}
    end

    S->>DB: Buscar API Key
    DB-->>S: Datos de la Key: propietario,
permisos, limites, estado

    alt Key Valida y Activa
        Note over S: Verificar limites de tasa
Registrar uso para facturacion
        S-->>C: 200 OK + Datos de Respuesta
    else Key Invalida/Revocada
        S-->>C: 401 No Autorizado
    else Limite de Tasa Excedido
        S-->>C: 429 Demasiadas Peticiones
    end

Notas de Seguridad

Estándares y RFCs