Invitaciones
Verifica, acepta o rechaza una invitación de organization al Tokeflow Dashboard usando el token firmado del correo de invitación.
Los propietarios y administradores de la Organization agregan compañeros de equipo al Tokeflow Dashboard enviando invitaciones. El invitado recibe un correo con un enlace que lleva un token de invitación firmado y de un solo uso. Los tres endpoints de esta página impulsan ese flujo de aterrizaje: la UI del Dashboard primero verifica el token para mostrar quién está invitando a quién y a qué rol, y luego el invitado acepta (creando antes una cuenta de usuario, si aún no tiene una) o rechaza.
Aceptar una invitación otorga al invitado una membresía en la organization con el rol elegido por quien envió la invitación — owner, admin, o viewer. Los roles y lo que cada uno puede ver se describen en Organizations y Merchants.
Estos endpoints impulsan la interfaz del Tokeflow Dashboard. A diferencia del resto de la superficie del dashboard — que requiere una sesión iniciada (JWT bearer) — los endpoints de invitación son deliberadamente no autenticados: es posible que el invitado aún no tenga una cuenta, por lo que el token de invitación firmado del correo es la única credencial. Nunca aceptan claves de API sk_/pk_.
Cómo funciona el flujo
Verifica siempre antes de renderizar un formulario de aceptación: el flag is_new_user en el resultado de la verificación indica si debes pedirle una contraseña al invitado (cuenta nueva) o solo confirmar (cuenta existente).
El objeto de resultado de la verificación
GET /api/v1/invitations/verify devuelve este objeto. Solo valid está siempre presente; los campos descriptivos son anulables (nullable) y son lo que el Dashboard muestra en la página de aterrizaje de la invitación.
| Field | Type | Description |
|---|---|---|
valid | boolean | Si el token de invitación es válido. |
email | string | null | Dirección de correo electrónico asociada a la invitación. |
organization_name | string | null | Nombre de la organization a la que corresponde la invitación. |
role | string | null | Rol que se asignará al invitado: owner, admin, o viewer. |
inviter_name | string | null | Nombre del usuario que envió la invitación. |
expires_at | string | null | Fecha de expiración de la invitación (ISO 8601 UTC). |
is_new_user | boolean | Si esta invitación es para un usuario nuevo sin cuenta existente. Cuando es true, la llamada de aceptación debe incluir password y confirm_password. |
Endpoints
GET/api/v1/invitations/verify
Auth: Ninguna — el token de invitación es la credencial. No se requiere ninguna Dashboard session.
Verifica un token de invitación y devuelve los detalles necesarios para renderizar la página de aterrizaje de la invitación: quién invitó, a qué organization y rol, cuándo expira la invitación, y si el invitado necesita crear una cuenta.
Parámetros de consulta
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Sí | Token de invitación a verificar (del enlace de invitación). |
Ejemplo de solicitud
curl -G https://api.tokeflow.com/api/v1/invitations/verify \
--data-urlencode "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"Ejemplo de respuesta — 200 OK
{
"valid": true,
"email": "jane@acme.com",
"organization_name": "Acme Digital",
"role": "admin",
"inviter_name": "Carlos Prado",
"expires_at": "2026-08-19T12:00:00.000Z",
"is_new_user": true
}Un token inválido no es un error HTTP. Un token inválido o expirado sigue devolviendo 200 OK con valid: false (y campos descriptivos nulos) — decide según el campo valid, no según el código de estado.
Ejemplo de respuesta — 200 OK, token expirado
{
"valid": false,
"email": null,
"organization_name": null,
"role": null,
"inviter_name": null,
"expires_at": null,
"is_new_user": false
}POST/api/v1/invitations/accept
Auth: Ninguna — el token de invitación en el cuerpo es la credencial. No se requiere ninguna Dashboard session.
Acepta una invitación y otorga al invitado una membresía en la organization. Cuando la invitación es para un usuario nuevo (is_new_user: true en el resultado de la verificación), incluye password y confirm_password — la cuenta de usuario se crea con esa contraseña como parte de la aceptación.
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Sí | Token de invitación del enlace de invitación. |
name | string | No | Nombre para mostrar que el invitado desea usar. |
password | string | Condicional | Contraseña para usuarios nuevos. Si se proporciona, la cuenta de usuario se creará con esta contraseña. Requerido cuando el resultado de la verificación muestra is_new_user: true. |
confirm_password | string | Condicional | Debe coincidir con password. Las contraseñas deben tener entre 12 y 128 caracteres e incluir una letra minúscula, una letra mayúscula y un número. |
Ejemplo de solicitud — usuario nuevo
curl -X POST https://api.tokeflow.com/api/v1/invitations/accept \
-H "Content-Type: application/json" \
-d '{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
"name": "Jane Doe",
"password": "mySecureP@ss123",
"confirm_password": "mySecureP@ss123"
}'Ejemplo de solicitud — usuario existente
curl -X POST https://api.tokeflow.com/api/v1/invitations/accept \
-H "Content-Type: application/json" \
-d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }'Respuesta — 201 Created
Una aceptación exitosa devuelve 201 Created con un cuerpo vacío. El invitado ahora puede iniciar sesión en el Dashboard con su correo electrónico y contraseña.
POST/api/v1/invitations/decline
Auth: Ninguna — el token de invitación en el cuerpo es la credencial. No se requiere ninguna Dashboard session.
Rechaza una invitación. El token se consume y el invitado no se agrega a la organization; quien envió la invitación siempre puede enviar una nueva invitación más adelante.
Campos de la solicitud
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Sí | Token de invitación del enlace de invitación. |
Ejemplo de solicitud
curl -X POST https://api.tokeflow.com/api/v1/invitations/decline \
-H "Content-Type: application/json" \
-d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }'Respuesta — 201 Created
Un rechazo exitoso devuelve 201 Created con un cuerpo vacío.
Errores
Los casos más comunes para estos endpoints:
| HTTP | Causa típica |
|---|---|
400 | Solicitud malformada — falta token, las contraseñas no coinciden, o una contraseña que no cumple las reglas de complejidad. |
401 | El token de invitación es inválido, expiró, o ya fue usado al aceptar o rechazar. Llama a verificar primero para mostrarle al invitado un estado amigable. |
Consulta Errores para el formato general de error usado en toda la API.
Relacionados
- Autenticación del Dashboard — inicia sesión después de aceptar una invitación.
- Organizations y Merchants — cómo encajan las organizations, los roles y los merchants.
- Registros de auditoría — los cambios de membresía aparecen en el registro de auditoría de la organization.