Autenticación

Claves de API (recomendadas para integraciones)

Una clave de API es un token de acceso personal vinculado a un miembro de tu cuenta.

• Créala en Configuración → Plugins → Claves de API de RolChat. El secreto se muestra una vez; después solo son visibles sus diez primeros caracteres, y RolChat almacena únicamente un hash SHA-256.
• Formato: rcp_ seguido de 32 bytes aleatorios en base64url, unos 45 caracteres en total. El prefijo hace que la clave sea reconocible en los registros y se distinga de un token de sesión.
• Ámbitos: se eligen de un catálogo fijo de capacidades al crear la clave. Una clave nunca puede hacer más que el miembro que la creó: en cada llamada se comprueban ambas condiciones, que la capacidad esté en los ámbitos de la clave y que el miembro todavía la tenga. Si restringes el rol del miembro, la clave se restringe con él.
• Duración: las claves no caducan por sí solas. Revoca una clave desde la página del perfil o con DELETE /api/v1/tokens/:id; la revocación surte efecto de inmediato. No hay rotación en el sitio: revoca la clave y crea una nueva.
• La creación y la revocación se anotan en el registro de auditoría.

Envíala como token bearer; no hay una cabecera aparte para la clave de API:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Las peticiones con una clave de API de plugin están limitadas a 300 por minuto.

Sesiones JWT

La aplicación web y los SDK móviles inician sesión con email y contraseña (o con Google o Apple) y reciben un par de tokens.

Token	Duración	Notas
Token de acceso	15 minutos	RS256, verificado frente al JWKS en /.well-known/jwks.json
Token de actualización	30 días	Se rota en cada actualización; reutilizar un token ya rotado revoca toda la cadena

Claims: sub (usuario), acc (cuenta), rl (rol) y, para los roles por sitio, sts (sitios permitidos).

POST /auth/login, /auth/refresh, /auth/swap-company y /auth/logout son los únicos endpoints del flujo de autenticación que no deben llevar la cabecera X-Account-Id descrita a continuación.

La cabecera X-Account-Id

Toda petición autenticada, salvo las cuatro anteriores, debe indicar la cuenta sobre la que actúa:

X-Account-Id: <account uuid>

El servidor comprueba que la cabecera coincide con el claim acc del token (o con la cuenta de la clave de API). Si falta la cabecera, la respuesta es 400 missing_required_header; si no coincide, 403 account_context_mismatch. La cabecera existe para que un error del cliente o un token reutilizado nunca puedan leer en silencio los datos de otro inquilino: la discrepancia se rechaza antes de ejecutar cualquier consulta, y cada línea de registro se puede atribuir a una cuenta sin decodificar el token.

Usuarios con varias empresas

Una persona puede pertenecer a varias empresas. Cada empresa tiene su propio token (su propio claim acc). Para cambiar:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

El destino debe ser una de las available_companies de quien llama (devueltas al iniciar sesión); de lo contrario, 403 forbidden. La respuesta es un nuevo par de tokens de acceso y actualización limitado al destino; el token de actualización anterior se revoca y se escribe un evento de auditoría auth.account.swapped.

Autenticación multifactor

La MFA basada en TOTP se puede activar por miembro y exigir por cuenta. Cuando está activa, POST /auth/login devuelve un desafío y la sesión se completa con POST /auth/mfa/verify. Los códigos de respaldo se emiten al activarla.

Protección del inicio de sesión

• Las rutas de inicio de sesión están limitadas a 10 intentos por IP por minuto y a 5 por email cada 15 minutos.
• Diez inicios de sesión fallidos bloquean el email durante 30 minutos; la respuesta incluye code: account_locked.
• reCAPTCHA se puede activar por acción (registro, inicio de sesión, restablecimiento de contraseña); la configuración pública inicial se sirve desde GET /api/v1/captcha.