SKEEN-Proyecto/docs/producto/api-terceros.md

API de terceros gestionable (claves de API)

La API pública /skeen/api/v1/* (consumida por Hermes) se autentica con el método auth='api_key', implementado en skeen_plataforma/models/ir_http.py. Acepta dos tipos de credencial:

1. Clave legacy de Hermes — ir.config_parameter 'skeen.api.legacy_key', sembrada con el valor histórico skeen_api_key_2026. Tiene todos los alcances (compatibilidad total).
2. Claves del modelo skeen.api.key — con alcances (scopes), vencimiento y revocación.

Formato de autenticación

Authorization: Bearer <clave>
X-API-Key: <clave>
?api_key=<clave>            (query/form)

Modelo skeen.api.key

Campo	Descripción
name	Nombre de la clave
prefijo	Prefijo visible (los primeros 14 caracteres)
hash	SHA-256 de la clave (nunca se guarda en claro)
activo	Habilitada
scopes	Lista JSON de alcances; vacío = todos
vence	Fecha de vencimiento (opcional)
ultimo_uso, usos	Uso registrado en cada autenticación
notas, creado_por_login	Metadatos
revocada_at, revocada_por	Revocación

La clave se muestra una sola vez al crearla (solo se guarda el hash; la comparación es en tiempo constante).

Alcances por endpoint

Endpoint	Alcance
POST /skeen/api/v1/available_slots	citas.read
POST /skeen/api/v1/create_appointment	citas.write
POST /skeen/api/v1/cancel_appointment	citas.write
POST /skeen/api/v1/patient_balance	pacientes.read
POST /skeen/api/v1/wallet_redeem	monedero.write
GET/POST /skeen/api/v1/services	servicios.read

Una clave sin el alcance recibe HTTP 403 con mensaje claro. La clave legacy no tiene restricción de alcance.

Las respuestas son JSON plano (no JSON-RPC): códigos 200 correctos, 401/403 para clave ausente/inválida o sin alcance.

Endpoints de gestión

Método	Ruta	Acceso
GET	/skeen/frontend/v1/api_keys	permiso api.claves (admin)
POST	/skeen/frontend/v1/api_keys	permiso api.claves (admin)
PUT	/skeen/frontend/v1/api_keys/<id>	permiso api.claves (admin)
POST	/skeen/frontend/v1/api_keys/<id>/revocar	permiso api.claves (admin)

UI

Configuración → pestaña API (admin): lista de claves (nombre, prefijo, alcances, último uso, usos, estado), botón "nueva clave" con modal que muestra la clave una vez y botón de copiar, editar y revocar; y documentación breve de los endpoints y del formato de autenticación.