Saltar al contenido principal

Autenticación

Asegura tus peticiones API con autenticación adecuada.

Autenticación con Clave API​

La API de Partners de LosCenotes utiliza claves API para autenticar las peticiones. Puedes ver y administrar tus claves API en el Portal de Partners.

Métodos de Autenticación​

Bearer Token (Recomendado)​

Incluye tu clave API en el header de Autorización:

Authorization: Bearer sk_test_your_api_key

Ejemplo de Petición​

curl -X GET https://service-gateway.loscenotes.com/v1/cenotes \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json"

Tipos de Clave API​

Claves de Sandbox​

  • Prefijo: sk_test_
  • Propósito: Desarrollo y pruebas
  • Características:
    • Sin transacciones reales
    • Peticiones ilimitadas (10x límite de tasa)
    • Aislamiento de datos de prueba
    • Acceso al simulador de webhooks

Claves de Producción​

  • Prefijo: pk_live_
  • Propósito: Entorno de producción en vivo
  • Características:
    • Transacciones reales
    • Límites de tasa estándar
    • Acceso a datos de producción
    • Eventos webhook reales

Mejores Prácticas de Seguridad​

1. Mantén Seguras tus Claves​

peligro

Nunca expongas tus claves API en:

  • Código del lado del cliente
  • Repositorios públicos
  • Aplicaciones móviles
  • JavaScript del navegador

2. Usa Variables de Entorno​

// Bien ✓
const apiKey = process.env.LOSCENOTES_API_KEY;

// Mal ✗
const apiKey = "sk_test_1234567890abcdef";

3. Rota las Claves Regularmente​

  1. Genera una nueva clave API
  2. Actualiza tu aplicación
  3. Verifica que todo funcione
  4. Revoca la clave antigua

4. Usa Firmas de Webhook​

Siempre verifica las firmas de webhook para asegurar que las peticiones provienen de LosCenotes:

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

OAuth 2.0 (Próximamente)​

Estamos implementando OAuth 2.0 para permisos más granulares:

  • Autenticación a nivel de usuario
  • Permisos con alcance
  • Renovación de tokens
  • Integraciones de terceros

Respuestas de Error​

Clave API Inválida​

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "La clave API proporcionada es inválida",
    "status": 401
  }
}

Autenticación Faltante​

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Se requiere autenticación para este endpoint",
    "status": 401
  }
}

Permisos Insuficientes​

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Tu clave API no tiene permisos para esta acción",
    "status": 403
  }
}

Probando la Autenticación​

Prueba tu configuración de autenticación:

# Endpoint de prueba para verificar tu clave API
curl -X GET https://service-gateway.loscenotes.com/v1/auth/verify \
  -H "Authorization: Bearer sk_test_your_api_key"

Respuesta exitosa:

{
  "success": true,
  "message": "Autenticación exitosa",
  "data": {
    "partner_id": "partner_123",
    "environment": "sandbox",
    "permissions": ["cenotes:read", "reservations:write", "webhooks:manage"]
  }
}

Próximos Pasos​