# Autenticación

URL: https://theelena.me/docs/elena/auth
Text: https://theelena.me/docs/elena/auth.txt
Description: Sesiones del panel, API Keys para integraciones y el catálogo público sin credenciales.
Context: environment=production; apiBaseUrl=https://api.theelena.me; appUrl=https://app.theelena.me

# Autenticación

Las fronteras existentes de Elena permanecen separadas y ninguna es
intercambiable con otra. El [candidate Agent Access](/docs/elena/agent-access)
añade Agent/Admin de producto `elena_sk_` (`x-elena-agent-key`) y Client
`elena_pk_` (`x-elena-client-key`) como contratos independientes: 0.1.0
no publicado, sin afirmar despliegue. No son API Keys legacy ni System Admin;
no reemplazan sesiones, slug, access points o journeys.

## Sesión del panel (Better Auth)

El panel del restaurante usa [Better Auth](https://www.better-auth.com) con
sesiones de usuario. Los endpoints de sesión viven bajo `/api/auth` en el host
de la API y cada request autenticado resuelve el restaurante del usuario en el
contexto del servidor; ningún endpoint del panel acepta un `restaurantId` desde
el cliente.

Los permisos finos (dueño, administrador, staff) se aplican por ruta con RBAC.
Si integras algo que actúa como un usuario del panel, usa su sesión; no
reutilices mecanismos de la API de integración.

## API Key de integración

La API de integración (`/api/v1/integration/catalog/*`) se autentica con un
header:

```http
x-api-key: tu_api_key_de_elena
```

Propiedades del contrato:

- la clave se crea desde el panel en **Ajustes → API Keys** como dueño;
- crearla exige que el plan del restaurante tenga la capacidad `apiAccess`;
- la clave guarda el `restaurantId` en su metadata: el backend resuelve el
  restaurante desde la clave, nunca desde el request;
- se muestra **una sola vez** al crearla; después solo se ve su prefijo;
- acepta expiración (1 semana, 1 mes, 3 meses o 1 año) y se puede revocar;
- el panel muestra conteo de requests, límite de tasa y último uso.

Trátala como un secreto de servidor: no va en apps móviles públicas, bundles
del navegador ni repositorios. Si una clave se filtra, revócala y crea otra.

### Errores comunes

| Estado | Causa                                                                                  |
| ------ | -------------------------------------------------------------------------------------- |
| 401    | Header `x-api-key` ausente o clave inválida                                            |
| 403    | La clave es válida pero el plan no incluye `apiAccess` o la suscripción no está activa |

## Catálogo público (sin autenticación)

Los endpoints `/api/v1/public/catalog/:slug/*` no requieren credencial: el
`slug` público identifica al restaurante. Están pensados para cartas digitales
y tracking de cliente, con límites de tasa por IP y por visitante:

- envía `x-visitor-id` (identidad anónima del navegador) en pedidos y tracking;
- el acceso por punto de venta físico usa una clave pública adicional
  (`/:slug/access/:publicKey`);
- el header `idempotency-key` es opcional al crear pedidos públicos para
  tolerar reintentos.

El catálogo público **no** reemplaza a la API de integración: no expone
operaciones de escritura administrativas y sus respuestas están recortadas al
consumo del cliente final.

## ¿Cuál uso?

- Sistema externo que lee catálogo y crea pedidos → **API Key**.
- Carta web o QR para comensales → **catálogo público**.
- Automatización que actúa como el equipo del restaurante → **sesión del
  panel** (por ejemplo, vía el Swagger autenticado del propio panel).