Authentication

Como funciona la autenticacion en Rivelko / How authentication works in Rivelko

Public Endpoints (No Auth Required)

The following endpoints are used by the embeddable widget and require no authentication. They are secured by domain validation instead.

Los siguientes endpoints no requieren autenticacion. Se validan por dominio.

Domain validation: The Origin (or Referer) header is checked against the form's allowedDomains list. Requests from unauthorized domains are rejected with 403.

These are the endpoints you'll use most when integrating Rivelko into your website or app.

Session-Based Auth (Dashboard)

All management endpoints (forms CRUD, conversations, webhooks, billing) accept NextAuth session cookies. This is the authentication method used by the Rivelko dashboard.

When you're logged in to the dashboard, your browser automatically sends the session cookie with every request. For programmatic access from external applications, use an API key instead (see below).

API Key Auth

API keys are accepted today on all management endpoints (forms, pipelines, deals, tickets, conversations, usage, subscription, webhooks) as an alternative to the session cookie. This is the recommended way to call Rivelko from external applications and scripts.

Las API keys ya se aceptan en todos los endpoints de gestion (forms, pipelines, deals, tickets, conversations, usage, subscription, webhooks) como alternativa a la cookie de sesion. Es la forma recomendada de llamar a Rivelko desde aplicaciones externas y scripts.

How it works

1. Generate an API key in Settings > API Key or via POST /api/users/me/api-key
2. Include it in the Authorization header on every request:

Authorization: Bearer rvk_a1b2c3d4e5f6...

authenticateRequest() checks the Authorization header first; if it's a valid Bearer rvk_... key it authenticates via the key, otherwise it falls back to the NextAuth session cookie. An invalid API key returns 401 Unauthorized immediately -- it does not fall through to session auth.

Key format

• Prefix: rvk_ (Rivelko Key)
• Length: rvk_ + 64 hex characters (32 random bytes)
• Example: rvk_a1b2c3d4e5f6789012345678abcdef0123456789abcdef0123456789abcdef01

Key management & security

• Generate a new key: POST /api/users/me/api-key. The full key is returned once, at generation time -- store it securely, it cannot be retrieved again.
• Keys are stored hashed (SHA-256) at rest; the plaintext key is never persisted.
• View your key: GET /api/users/me and the dashboard only ever show the prefix (e.g. rvk_a1b2c3d4...), never the full key.
• Each user has one key at a time. Generating a new key invalidates the previous one immediately.
• Treat API keys like passwords -- do not commit them to version control; use environment variables in your application.

Las claves se generan una vez y se muestran completas solo en ese momento; a partir de ahi se almacenan hasheadas (SHA-256) y el dashboard solo ensena el prefijo (rvk_xxxxxxxx...). Una clave por usuario: regenerarla invalida la anterior de inmediato.