Autenticación del Dashboard

Estos endpoints impulsan el inicio de sesión en el Dashboard. Un usuario inicia sesión como usuario de merchant o de organization, recibe una sesión y la presenta como token bearer en cada llamada posterior al Dashboard. También cubren el mantenimiento habitual de una sesión: renovar un token próximo a expirar, cambiar o restablecer una contraseña, listar las membresías que tiene un usuario y cambiar cuál es la organization activa.

Esto es distinto de la autenticación por clave de API. Las llamadas de máquina a máquina a la API pública usan claves sk_…/pk_… y nunca tocan estos endpoints; estos existen para el Dashboard humano, basado en navegador. Aceptar una invitación al Dashboard también ocurre aquí — consulta Invitaciones para conocer el ciclo de vida de la invitación.

La respuesta de inicio de sesión

Devuelto por los endpoints de listado y recuperación de esta página.

Endpoints

POST/api/v1/auth/change-password

Permite a los usuarios con contraseñas temporales cambiar su contraseña antes de iniciar sesión. Es obligatorio cuando must_change_password es true.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@tokeflow.com",
    "current_password": "TempPass@2025Xyz",
    "new_password": "NewSecurePass@2025"
  }'

Ejemplo de respuesta — 200

{}

POST/api/v1/auth/forgot-password

Siempre devuelve la misma respuesta 202, esté o no registrada la dirección, por lo que no se puede usar para descubrir cuentas. El límite por correo electrónico se aplica en el servicio; la limitación aquí es una salvaguarda por IP.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/forgot-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@organization.com"
  }'

Ejemplo de respuesta — 202

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST/api/v1/auth/login

Autentica a los usuarios internos de la plataforma (super admin, platform admin, support) con correo electrónico y contraseña. Devuelve un token JWT para las siguientes solicitudes a la API.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/login \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "superadmin@tokeflow.com",
    "password": "SuperAdmin@123"
  }'

Ejemplo de respuesta — 200

{}

POST/api/v1/auth/logout

Invalida el token de actualización actual. El token de acceso expirará de forma natural.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Ejemplo de respuesta — 200

{}

POST/api/v1/auth/merchant/accept-invitation

Establece una contraseña y activa la fila de merchant_users asociada al token de invitación proporcionado. Tras la aceptación, el usuario puede iniciar sesión mediante /auth/merchant/login.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/accept-invitation \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3...e9f0",
    "password": "StrongP@ssw0rd!",
    "name": "Acme Store"
  }'

Ejemplo de respuesta — 200

{
  "message": "Operation completed successfully",
  "email": "jane@example.com"
}

POST/api/v1/auth/merchant/change-password

Consulta únicamente merchant_users. La misma dirección puede ser una identidad independiente en más de una tabla, así que usa el endpoint que corresponda al dashboard al que pertenece la contraseña — este para merchant, organization/change-password para org, change-password para admin. Revoca los tokens de actualización; los tokens de acceso expiran en 15 minutos.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contact@organization.com",
    "current_password": "TempPass@2025Xyz",
    "new_password": "NewSecurePass@2025"
  }'

Ejemplo de respuesta — 200

{
  "message": "Password changed successfully",
  "email": "contact@organization.com",
  "can_login": true
}

POST/api/v1/auth/merchant/forgot-password

Siempre devuelve la misma respuesta 202, esté o no registrada la dirección, por lo que no se puede usar para descubrir cuentas.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/forgot-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@organization.com"
  }'

Ejemplo de respuesta — 202

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST/api/v1/auth/merchant/login

Autentica a los usuarios que han sido asignados a merchants. Devuelve el token JWT y la lista de membresías de merchant para el selector de merchant.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/merchant/login \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@merchant.com",
    "password": "Password@123"
  }'

Ejemplo de respuesta — 200

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@merchant.com",
    "name": "John Doe",
    "merchants": [
      {
        "membership_id": "f0f524fe-d28f-485b-bc3c-2c6acc26d12b",
        "merchant_id": "mrc_abc123",
        "merchant_name": "Store XPTO",
        "status": "active",
        "role": "owner",
        "organization_id": "org_xyz",
        "organization_name": "Acme Corp"
      }
    ],
    "last_login_at": "2026-04-09T10:00:00.000Z"
  },
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900
}

GET/api/v1/auth/merchant/memberships

Devuelve todas las membresías de merchant del usuario autenticado. Lo usa el frontend para mostrar un selector de contexto de merchant.

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/auth/merchant/memberships \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Ejemplo de respuesta — 200

{
  "memberships": [
    {
      "membership_id": "f0f524fe-d28f-485b-bc3c-2c6acc26d12b",
      "merchant_id": "mrc_abc123",
      "merchant_name": "Store XPTO",
      "status": "active",
      "role": "owner",
      "organization_id": "org_xyz",
      "organization_name": "Acme Corp"
    }
  ]
}

POST/api/v1/auth/organization/change-password

Consulta únicamente organization_users. Permite que un usuario de organization con una contraseña temporal la cambie antes de iniciar sesión; es obligatorio cuando must_change_password es true. Las identidades de merchant usan merchant/change-password — la misma dirección puede existir de forma independiente en ambas tablas.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "contact@organization.com",
    "current_password": "TempPass@2025Xyz",
    "new_password": "NewSecurePass@2025"
  }'

Ejemplo de respuesta — 200

{}

POST/api/v1/auth/organization/forgot-password

Siempre devuelve la misma respuesta 202, esté o no registrada la dirección, por lo que no se puede usar para descubrir cuentas.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/forgot-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@organization.com"
  }'

Ejemplo de respuesta — 202

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

POST/api/v1/auth/organization/login

Autentica a los usuarios de organization (contactos principales y miembros de la organization) con correo electrónico y contraseña. Devuelve el token JWT con las membresías de organization.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/login \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@company.com",
    "password": "OrgPass@123"
  }'

Ejemplo de respuesta — 200

{}

POST/api/v1/auth/organization/logout

Invalida el token de actualización actual de un usuario de organization. El token de acceso expirará de forma natural.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Ejemplo de respuesta — 200

{}

GET/api/v1/auth/organization/memberships

Devuelve todas las organizations a las que pertenece el usuario autenticado. La respuesta de inicio de sesión incluye la misma lista, pero los clientes solo conservan la organization activa, así que así es como un selector se vuelve a poblar después de una recarga.

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/auth/organization/memberships \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

Ejemplo de respuesta — 200

{
  "memberships": [
    {
      "membership_id": "f0f524fe-d28f-485b-bc3c-2c6acc26d12b",
      "organization_id": "org_abc123",
      "organization_name": "Acme Corp",
      "role": "owner"
    }
  ]
}

POST/api/v1/auth/organization/switch

Vuelve a emitir esta sesión para otra organization a la que pertenece quien llama, devolviendo un nuevo par de tokens. Autenticado en lugar de público: la organization que se devuelve es aquella a la que queda restringida cada solicitud posterior, por lo que quien llama debe ser un sujeto verificado, no simplemente quien posea un token de actualización. 403 si quien llama no tiene membresía en el destino.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/organization/switch \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_abc123"
  }'

Ejemplo de respuesta — 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

POST/api/v1/auth/password-reset/confirm

Consume el token, establece la contraseña, elimina cualquier bloqueo y revoca los tokens de actualización para que las sesiones existentes finalicen. Los tokens de acceso ya emitidos siguen siendo válidos hasta que expiran (15 minutos).

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/password-reset/confirm \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "V-9nQ2h1c2VyLXRva2VuLWV4YW1wbGUtdmFsdWU",
    "new_password": "CorrectHorse1Battery"
  }'

Ejemplo de respuesta — 200

{
  "message": "Password reset successfully",
  "email": "user@organization.com",
  "can_login": true
}

POST/api/v1/auth/refresh

Intercambia un token de actualización válido por un nuevo par de token de acceso y token de actualización (rotación de tokens).

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/auth/refresh \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Ejemplo de respuesta — 200

{}

Errores

Los errores usan el sobre estándar. Los casos más comunes aquí:

Relacionados

• Invitaciones
• Autenticación
• Equipo de la Organization