Autenticación y cuenta

Todas las llamadas (salvo registro y login) requieren una credencial en el header Authorization:

Authorization: Bearer <token>

También se acepta X-API-Key: <token> como header alternativo.

Registro y verificación del email

El registro usa verificación primero: nunca crea una sesión directamente. El endpoint público responde 201 pending_verification tanto para un email nuevo como para uno duplicado, por lo que no sirve para enumerar cuentas. El titular recibe un código y completa el flujo con POST /v1/auth/register/confirm.

curl -X POST https://api.qbank.cl/platform/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"org":"cbpay","type":"person","email":"ana@ejemplo.com","password":"una-clave-segura","display_name":"Ana Pérez","country":"CL"}'

{"status":"pending_verification","note":"check your email for the verification code; complete registration with POST /v1/auth/register/confirm"}

Confirma el código para recibir la primera sesión:

curl -X POST https://api.qbank.cl/platform/v1/auth/register/confirm \
  -H "Content-Type: application/json" \
  -d '{"org":"cbpay","email":"ana@ejemplo.com","code":"123456"}'

Un código con forma inválida responde 400 invalid_code; un código incorrecto o vencido responde uniformemente 401 invalid_code. Si no se puede consultar el servicio de verificación, responde 502 otp_check_failed. Una confirmación exitosa devuelve la misma forma de sesión que login (access_token, expires_at, refresh_token, refresh_expires_at y account).

Límites antiabuso de autenticación

Los fallos de login se cuentan por cuenta normalizada (organización/email): después de 8 fallos en 15 minutos, los intentos siguientes responden el mismo 401 invalid_credentials sin ejecutar bcrypt mientras dura la ventana. Los members con registro pendiente también reciben esa respuesta uniforme y no pueden entrar con la clave usada en el registro. La recuperación evita enumeración. POST /v1/auth/password/forgot mantiene el mismo 200 aunque se agote el presupuesto; permite como máximo 5 envíos reales por cuenta por hora. POST /v1/auth/password/reset permite como máximo 8 intentos de código por cuenta en 15 minutos. Un reset exitoso por email verifica el email y elimina register_pending. Los members de una cuenta empresa también pueden recibir un link de recuperación iniciado por su admin. Canjea su token con org y new_password en POST /v1/auth/password/reset-link; el link es de un solo uso y expira en 60 minutos. Este flujo de members es independiente del reset de admins de plataforma.

Tipos de credencial

Sesión JWT (personas con login)
API key (servidor a servidor)

Se obtiene con POST /v1/auth/login (el registro requiere confirmar el email primero, ver abajo) y dura 24 horas. Pensada para apps con usuarios que inician sesión. Junto al access_token recibes un refresh token para renovar la sesión sin pedir la contraseña de nuevo — ver renovación de sesión.

curl -X POST https://api.qbank.cl/platform/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "org": "cbpay", "email": "ana@ejemplo.com", "password": "…" }'

{
  "access_token": "eyJ…",
  "expires_at": "2026-07-14T15:20:49Z",
  "refresh_token": "rt_6a1e6c22-….XXXXXXXX…",
  "refresh_expires_at": "2026-08-12T15:20:49Z",
  "account_id": "…",
  "role": "owner"
}

Las cuentas empresa pueden tener varios miembros con roles — ver miembros de una empresa más abajo.

Si la política de la cuenta exige OTP en el login, la respuesta trae otp_required: true con un pending_token en vez de la sesión: el segundo paso se completa en POST /v1/auth/login/otp con el código recibido por SMS/WhatsApp. Flujo completo en seguridad y 2FA.

También puedes ofrecer registro e inicio de sesión con Google, Apple, Microsoft o Facebook (sin contraseña) — ver login social.

Formato pk_<key_id>.<secret>. No expira y no depende de una sesión. Se emite con:

curl -X POST https://api.qbank.cl/platform/v1/api-keys \
  -H "Authorization: Bearer <token-de-sesion>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "backend-produccion" }'

{
  "api_key_id": "…",
  "key_id": "a1b2c3d4e5f60718",
  "token": "pk_a1b2c3d4e5f60718.XXXXXXXX…",
  "note": "store this token now; it cannot be retrieved again"
}

El token en claro se muestra una sola vez. En el servidor solo se guarda un hash — si lo pierdes, emite una key nueva.

Renovación de sesión (refresh tokens)

El access_token dura 24 horas; el refresh_token (rt_…) permite obtener un par nuevo sin re-login durante 30 días, renovables en cada uso hasta un máximo de 90 días desde el login original. Es de un solo uso: cada canje devuelve un refresh_token nuevo y el anterior queda invalidado (rotación).

curl -X POST https://api.qbank.cl/platform/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "rt_6a1e6c22-….XXXXXXXX…" }'

{
  "access_token": "eyJ…",
  "expires_at": "2026-07-14T15:20:50Z",
  "refresh_token": "rt_9f2b1c30-….YYYYYYYY…",
  "refresh_expires_at": "2026-08-12T15:20:50Z",
  "account_id": "…",
  "role": "owner"
}

Reglas de seguridad que tu front debe conocer:

Rotación estricta: al canjear, el access token anterior de ese dispositivo queda revocado al instante (solo hay un access token vivo por cadena). Reemplaza siempre AMBOS tokens con los de la respuesta.
Reúso = robo: si un refresh token ya canjeado vuelve a presentarse, la cadena completa del dispositivo se revoca (tokens y sesiones) y queda un evento refresh_token_reuse en GET /v1/me/security/events. El usuario debe iniciar sesión de nuevo.
Muere con la sesión: cerrar sesión (DELETE /v1/me/sessions/{id}), POST /v1/me/sessions/revoke-all o un cambio/reset de contraseña invalidan también los refresh tokens asociados.
Cualquier rechazo responde 401 invalid_refresh_token — ante ese error, manda al usuario al login.
Guarda el refresh token en almacenamiento seguro (Keychain/Keystore en móvil; en web, preferir memoria + re-login o cookie httpOnly de tu backend). Las API keys pk_ no usan refresh: no expiran.

¿Cada cuánto debo refrescar?

Cuando el access token esté por vencer (usa expires_at) o al recibir un 401 en una llamada normal. Evita refrescar en paralelo desde varios lugares: si dos canjes del mismo token llegan a la vez, uno gana y el otro recibe 401 sin castigo — pero un canje de un token YA rotado revoca la cadena.

¿Qué pasa a los 90 días?

El tope absoluto de la cadena es 90 días desde el login original: aunque refresques a diario, al llegar al límite el refresh devuelve 401 y el usuario debe autenticarse de nuevo (con su contraseña, passkey o login social).

¿El refresh funciona con API keys?

No aplica: las API keys pk_ no expiran ni tienen sesión. El refresh es solo para sesiones JWT de usuarios humanos.

Nivel de acceso

Tu credencial (JWT de sesión o API key) opera tu propia cuenta: saldos, payouts, payins, transferencias, crypto, KYC/KYB y webhooks propios. Si un endpoint responde 403 account_required o 403 org_admin_required, esa operación corresponde a otro nivel de credencial — contacta al equipo de CBPay.

Tu perfil de cuenta

# Leer el perfil (incluye kyc_status y type)
curl https://api.qbank.cl/platform/v1/me \
  -H "Authorization: Bearer <token>"

# Actualizar campos del perfil (todos opcionales)
curl -X PATCH https://api.qbank.cl/platform/v1/me \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Comercial Andina SpA",
    "tax_id": "76.543.210-8",
    "phone": "+56 9 1234 5678",
    "country": "CL",
    "locale": "en"
  }'

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "company",
  "display_name": "Comercial Andina SpA",
  "email": "legal@andina.cl",
  "tax_id": "76.543.210-8",
  "phone": "+56 9 1234 5678",
  "country": "CL",
  "locale": "en",
  "status": "active",
  "kyc_status": "approved",
  "created_at": "2026-06-01T12:00:00Z"
}

PATCH /v1/me acepta display_name, tax_id, phone, country y locale (envía solo los que cambian). Un locale vacío guarda en; valores inválidos devuelven 400 invalid_locale. El email, status y kyc_status no se autogestionan: los resuelve el administrador. Ver Idioma y locale.

Miembros de una empresa

Las cuentas empresa pueden tener varios usuarios con login propio y distinto nivel de permiso:

Rol	Permisos
`owner`	Todo: opera, administra miembros y credenciales
`operator`	Opera el día a día (default al crear un miembro)
`viewer`	Solo lectura

# Agregar un miembro (solo cuentas company)
curl -X POST https://api.qbank.cl/platform/v1/members \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "finanzas@andina.cl",
    "password": "una-clave-segura",
    "role": "viewer"
  }'

# Listar miembros
curl "https://api.qbank.cl/platform/v1/members?page_size=50" \
  -H "Authorization: Bearer <token>"

{
  "page": 1,
  "page_size": 50,
  "members": [
    { "id": "…", "email": "legal@andina.cl", "role": "owner", "status": "active" },
    { "id": "…", "email": "finanzas@andina.cl", "role": "viewer", "status": "active" }
  ]
}

En una cuenta persona, POST /v1/members responde 403 company_only.

Buenas prácticas

Guarda las API keys en un gestor de secretos; nunca en el código ni en el navegador.
Usa una key por ambiente/servicio (label descriptivo) para poder rotar sin downtime.

Rotación sin downtime

Emite la key nueva con POST /v1/api-keys (label nuevo).

Despliega

Actualiza tu servicio para usar la key nueva.

Retira la antigua

Pide al equipo de CBPay revocar la key anterior una vez que el tráfico migró.

Las sesiones JWT son para front-ends; para procesos automatizados usa siempre API keys.

Comenzar

Conceptos

Flujos de integración

Productos

Integración

Recursos

Autenticación y cuenta

Registro y verificación del email

Límites antiabuso de autenticación

Tipos de credencial

Renovación de sesión (refresh tokens)

Nivel de acceso

Tu perfil de cuenta

Miembros de una empresa

Buenas prácticas

​Registro y verificación del email

​Límites antiabuso de autenticación

​Tipos de credencial

​Renovación de sesión (refresh tokens)

​Nivel de acceso

​Tu perfil de cuenta

​Miembros de una empresa

​Buenas prácticas

Registro y verificación del email

Límites antiabuso de autenticación

Tipos de credencial

Renovación de sesión (refresh tokens)

Nivel de acceso

Tu perfil de cuenta

Miembros de una empresa

Buenas prácticas