API keys

Autenticación programática per-tenant. Para integraciones, scripts, backends de cliente.

Formato

Las keys siguen el formato vx_live_<prefix><random>:

• Prefijo público: 12 hex chars (e.g. vx_live_a1b2c3d4e5f6) — visible en UI para identificar la key
• Body: 24 bytes random base64url — secreto, solo se muestra al crear
• Almacenamiento: SHA-256 hash de la key completa en api_keys.key_hash

Crear una key

1. Superadmin abre tenant detail → tab API keys
2. Form: name, scopes (CSV o *), expiresInDays (opcional)
3. Submit → response muestra la key COMPLETA una sola vez
4. Guardar en gestor de secretos antes de cerrar el modal

Scopes

Granularidad acción:recurso. Ejemplos:

• read:contacts — listar/leer contactos
• write:appointments — crear/modificar citas
• read:* — todas las lecturas
• * — todas las acciones (cuidado)

Verificación: hasScope(grantedScopes, required) en @vertix/core/api-keys.

Usar la key

Header HTTP:

Authorization: Bearer vx_live_a1b2c3d4e5f6...

El backend resuelve tenant_id + scopes via verifyApiKey(rawKey). Si key revocada, expirada, o no encontrada → 401.

Revocar

UI tenant API keys page → Revocar. Setea revoked_at = NOW(). Las verificaciones futuras fallan inmediatamente (no cache de keys activas).

Best practices

• Una key por integración (no compartir)
• Scopes mínimos necesarios — principio de menor privilegio
• Set expiresInDays para keys de scripts efímeros
• Rotar keys periódicamente (90 días recomendado)
• Nunca commitear keys en git — usa env vars

Limit + tracking

Cada uso actualiza last_used_at (best-effort, async). El audit log registra api_key.create, api_key.revoke.

Ver también

• Webhooks — eventos push complementarios
• Glosario — términos