EMPEZAR
Autenticación
Consigue un token de API y autentica tus peticiones.
La API REST (/api/v1/*) usa autenticación por token opaco vía cabecera Authorization: Bearer <token> — independiente de la cookie de sesión que usa la propia app web, nunca se mezclan en la misma ruta. El token se obtiene registrando una cuenta nueva o iniciando sesión en una existente.
Por debajo, la contraseña la custodia Ory Kratos (el proveedor de identidad de la instancia) — esta API nunca ve ni guarda la contraseña en texto plano, solo emite un token opaco propio tras validar contra Kratos.
Registrar una cuenta nueva
bash
curl -X POST https://tu-hostname/api/v1/auth/registro \
-H "Content-Type: application/json" \
-d '{
"email": "dev@tuempresa.com",
"contrasena": "una-contrasena-de-8-caracteres-o-mas",
"nombre_dispositivo": "Mi integración"
}'
json
{
"ok": true,
"data": {
"token": "kf83h2n...",
"usuario": { "id": 42, "email": "dev@tuempresa.com" }
}
}Iniciar sesión con una cuenta existente
bash
curl -X POST https://tu-hostname/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "dev@tuempresa.com", "contrasena": "..."}'Cada llamada a /auth/registro o /auth/login emite un token nuevo — puedes tener varios tokens activos a la vez (uno por dispositivo/integración), y revocar uno concreto sin afectar a los demás con POST /api/v1/auth/logout (revoca el token que viaja en la propia petición).
Usar el token
bash
curl https://tu-hostname/api/v1/auth/me \
-H "Authorization: Bearer kf83h2n..."Errores de autenticación
| HTTP | Cuándo |
|---|---|
| 400 | Email inválido, contraseña de menos de 8 caracteres, o campos obligatorios ausentes. |
| 401 | Token ausente, revocado o incorrecto — /auth/login con credenciales erróneas también devuelve 401. |
| 409 | /auth/registro con un email que ya tiene cuenta. |
| 429 | Límite de intentos superado (ver aviso de abajo). |
Los endpoints de
/auth/registro y /auth/login están limitados a 10 peticiones por minuto por IP (protección de fuerza bruta) — si automatizas la creación de cuentas, ten en cuenta ese límite.