Autenticación

Autenticación

Nuestra API utiliza Token Based Authentication sobre HTTPS para la autenticación. Para tener acceso a nuestra API, necesitas crear y utilizar API keys específicas para cada entorno.

Usa HTTPS para todos los requests. Requests hechos mediante HTTP retornarán respuestas HTTP 403. Mantén tus API keys y refresh tokens en secreto.

API Keys

Las API keys son tokens de autenticación que permiten el acceso a los diferentes recursos de la API de Soyio. Cada API key:

• Es específica para un entorno: sandbox o production
• Puede ser creada dinámicamente desde la API
• Tiene un alcance configurable (scopes) para limitar el acceso a endpoints específicos
• Incluye fechas de expiración (90 días por defecto en production, sin expiración en sandbox)
• Incluye un refresh token cuando tiene fecha de expiración, que permite renovar la API key cuando expire

Identificación por Prefijo

Las API keys se identifican por su prefijo según el entorno:

• Sandbox: ak_sandbox_[identificador]
• Production: ak_live_[identificador]

Header de autenticación

Este tiene el siguiente formato:

Authorization: <api_key>

Donde api_key es la API key específica del entorno que deseas utilizar.

Ejemplo para Sandbox

Authorization: ak_sandbox_1B2M2Y8AsgTpgAmY7PhCfg

Ejemplo para Production

Authorization: ak_live_2C3N3Z9BthUpgBnZ8QiDgh

Gestión de API Keys

Puedes gestionar tus API keys tanto desde los siguientes endpoints:

• Crear nueva API key: POST /api_keys
• Listar todas las API keys: GET /api_keys
• Obtener detalles de una API key: GET /api_keys/{id}
• Actualizar una API key: PATCH /api_keys/{id}
• Renovar una API key: PATCH /api_keys/{id}/refresh
• Revocar una API key: DELETE /api_keys/{id}

Renovación de API Keys

Cuando creas una API key con fecha de expiración, recibirás un refresh token junto con la API key. Este refresh token te permite extender el ciclo de vida de la API key cuando esté próxima a expirar o haya expirado.

Período de gracia del refresh token

Los refresh tokens tienen un período de gracia de 60 días después de la expiración de la API key. Si no renuevas la API key dentro de este período, el refresh token dejará de funcionar y deberás crear una nueva API key.

¿Cómo funciona?

1. Creación: Al crear una API key con POST /api_keys, recibirás en la respuesta:
   • secret: El token JWT de autenticación (la API key)
   • refresh_token: Token para renovar la API key (solo si tiene fecha de expiración)
2. Almacenamiento: Guarda ambos tokens de forma segura. El refresh_token es necesario para renovar la API key.
3. Renovación: Cuando la API key esté próxima a expirar o haya expirado, usa el endpoint PATCH /api_keys/{id}/refresh con el refresh_token para obtener:
   • Un nuevo secret (nueva API key extendida)
   • Un nuevo refresh_token para futuras renovaciones

La API key y el refresh token solo se muestran durante la creación y renovación.

Ejemplo de flujo

1. Crear API key

curl -X POST https://api.soyio.com/v1/api_keys \
  -H "Authorization: YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "label": "Backend Service",
      "expires_in_days": 30
    }
  }'

Respuesta:

{
  "api_key": {
    "id": "ak_live_abc123",
    "label": "Backend Service",
    "environment": "production",
    "expires_at": "2024-04-20T15:30:00Z",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "akrt_xyz789",
    "scopes": ["*"],
    "created_at": "2024-03-20T15:30:00Z"
  }
}

2. Renovar API key

curl -X PATCH https://api.soyio.com/v1/api_keys/ak_live_abc123/refresh \
  -H "Authorization: YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "refresh_token": "akrt_xyz789",
      "expires_in_days": 60
    }
  }'

Respuesta:

{
  "api_key": {
    "id": "ak_live_abc123",
    "label": "Backend Service",
    "environment": "production",
    "expires_at": "2024-06-20T15:30:00Z",
    "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "akrt_new456",
    "scopes": ["*"],
    "created_at": "2024-03-20T15:30:00Z"
  }
}

Guarda el nuevo refresh token

Cada vez que renuevas una API key, recibes un nuevo refresh_token. Asegúrate de actualizar el token almacenado con el nuevo valor para futuras renovaciones.

Cuándo renovar

• Antes de expirar: Renueva la API key antes de que expire para evitar interrupciones en el servicio
• Después de expirar: También puedes renovar una API key expirada usando su refresh_token, pero solo dentro del período de gracia de 60 días
• Límite del período de gracia: Si han pasado más de 60 días desde la expiración de la API key, el refresh token dejará de funcionar y deberás crear una nueva API key
• API keys de sandbox: Las API keys de sandbox no expiran por defecto, por lo que no reciben refresh_token a menos que especifiques expires_in_days al crearlas

Buenas Prácticas

• Crea API keys separadas para cada aplicación o servicio
• Utiliza scopes específicos para limitar el acceso solo a los endpoints necesarios
• Rota tus API keys regularmente, especialmente en production
• Revoca inmediatamente las API keys comprometidas
• Guarda los refresh tokens de forma segura junto con las API keys
• Implementa lógica de renovación automática cuando las API keys estén próximas a expirar
• Actualiza siempre el refresh token después de cada renovación