# 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.