Entorno de PRE: solo datos de prueba. Los correos solo llegan al equipo y los cobros son de prueba.
Guilda WorkDevelopers

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

En el servidor de Guilda Work este endpoint está cerrado (responde 403 registro_cerrado): el alta es por invitación de un despacho o por la web, con verificación del correo. Solo responde si el administrador del servidor define GUILDA_REGISTRO_API=1 (instalaciones propias y desarrollo).
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

HTTPCuándo
400Email inválido, contraseña de menos de 8 caracteres, o campos obligatorios ausentes.
401Token ausente, revocado o incorrecto — /auth/login con credenciales erróneas también devuelve 401.
409/auth/registro con un email que ya tiene cuenta.
429Lí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.

Tokens de solo lectura, por áreas y con caducidad

Para una integración que solo debe consultar (un panel, un informe), crea un token con permisos: "solo_lectura": puede hacer GET pero cualquier otro método responde 403 Este token es de solo lectura.. Se crea desde Mis dispositivos en la web o con POST /tokens ({"nombre": "...", "permisos": "completo|solo_lectura"}); el token en claro solo se devuelve en ese momento. GET /tokens los lista (con areas, caduca_en, ultimo_uso_en, ultima_ip y llamadas_30d), GET /tokens/{id}/uso da las llamadas y errores por día y DELETE /tokens/{id} revoca uno.

Principio de mínimo privilegio. Al crear un token puedes limitarlo a áreas con areas (notas, tareas, correo, fiscal, fichaje, tiquets, ia, avisos): fuera de ellas responde 403 con codigo: "token_area_no_permitida". Un token con áreas no puede usar las rutas transversales (/historial, /dashboard, /export, /papelera, /buscar, /sync, que mezclan datos de varias áreas) ni gestionar tokens (no puede crear uno más amplio). Siempre puede leer /auth/me, el perfil y /openapi.json. Con caduca_dias (1-3650) o caduca_en el token caduca solo (401, token_caducado); sin caducidad se desconecta tras 90 días sin uso. Combina con permisos: "solo_lectura": p. ej. un panel que solo lee el calendario fiscal.

Paginación opcional

Los listados de historial, tareas, tiques, clientes y vencimientos fiscales y mensajes de correo aceptan limit (1–1000) y offset. Sin ellos devuelven todo, como siempre. La cabecera X-Total-Count lleva el total sin paginar.