API Keys

Las API keys proporcionan un mecanismo de autenticacion simple para integraciones servidor-a-servidor y flujos de trabajo de automatizacion (n8n, Make, scripts personalizados). Cada clave esta vinculada a un tenant y tiene limites de tasa configurables.

Flujo de Autenticacion

1. Genera una API key a traves del dashboard o del endpoint POST /api-keys.
2. La clave completa (ej. voc_a1b2c3d4...) se devuelve solo una vez en el momento de la creacion. Guardala de forma segura.
3. Incluye la clave en el header X-API-Key en cada solicitud:

curl -H "X-API-Key: voc_a1b2c3d4e5f6..." \
  https://api.usevocals.com/api/v1/agents

4. La API valida la clave hasheandola con SHA-256 y comparandola con el hash almacenado. La clave en si nunca se almacena en texto plano.
5. Los limites de tasa se verifican por clave usando contadores de Redis (solicitudes por minuto y por dia).

Las API keys tienen el prefijo voc_ y constan de 8 caracteres mas un token aleatorio seguro para URLs.

Crear API Key

POST /api-keys

Genera una nueva API key. La clave completa se incluye en la respuesta solo esta vez -- las llamadas posteriores de listado/consulta solo muestran el prefijo.

Cuerpo de la Solicitud

{
  "label": "n8n Production",
  "rate_limit_rpm": 300,
  "rate_limit_rpd": 50000
}

Campos de la Solicitud

Campo	Tipo	Requerido	Por defecto	Descripcion
label	string	Si	--	Etiqueta legible para la clave
rate_limit_rpm	integer	No	300	Solicitudes maximas por minuto
rate_limit_rpd	integer	No	50000	Solicitudes maximas por dia

Respuesta

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "prefix": "voc_a1b2",
  "label": "n8n Production",
  "rate_limit_rpm": 60,
  "rate_limit_rpd": 10000,
  "is_active": true,
  "created_at": "2026-03-01T10:00:00Z",
  "last_used_at": null,
  "key": "voc_a1b2c3d4e5f6g7h8i9j0..."
}

El campo key contiene la API key completa. Guardala inmediatamente -- no se mostrara de nuevo.

Listar API Keys

GET /api-keys

Devuelve todas las API keys del tenant actual, ordenadas por fecha de creacion (mas recientes primero). La clave completa nunca se incluye; solo se muestra el prefix.

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "prefix": "voc_a1b2",
    "label": "n8n Production",
    "rate_limit_rpm": 300,
    "rate_limit_rpd": 50000,
    "is_active": true,
    "created_at": "2026-03-01T10:00:00Z",
    "last_used_at": "2026-03-02T08:15:00Z"
  }
]

Campos de Respuesta

Campo	Tipo	Descripcion
id	uuid	ID de la API key
prefix	string	Primeros 8 caracteres de la clave (para identificacion)
label	string	Etiqueta legible
rate_limit_rpm	integer	Limite de solicitudes por minuto
rate_limit_rpd	integer	Limite de solicitudes por dia
is_active	boolean	Si la clave esta activa
created_at	datetime	Marca de tiempo de creacion
last_used_at	datetime | null	Ultima vez que se uso la clave

Revocar API Key

DELETE /api-keys/{key_id}

Desactiva una API key. La clave no se elimina de la base de datos sino que se marca como inactiva y ya no autenticara solicitudes.

Respuesta

204 No Content

La revocacion es inmediata. Las solicitudes en curso que usen la clave pueden completarse, pero las solicitudes posteriores seran rechazadas con 401 Unauthorized.

Limites de Tasa

Los limites de tasa pueden verse y ajustarse a traves de la API de Rate Limits:

Ver Limites de Tasa

GET /rate-limits

Devuelve la configuracion actual de limites de tasa para todas las API keys activas.

[
  {
    "api_key_id": "550e8400-...",
    "label": "n8n Production",
    "prefix": "voc_a1b2",
    "rate_limit_rpm": 60,
    "rate_limit_rpd": 10000
  }
]

Actualizar Limites de Tasa

PUT /rate-limits/{api_key_id}

Ajusta los umbrales de limite de tasa para una API key especifica.

Cuerpo de la Solicitud

{
  "rate_limit_rpm": 120,
  "rate_limit_rpd": 50000
}

Respuesta

Devuelve la configuracion de limites de tasa actualizada.