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.

Tipos de credencial

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

Se obtiene con POST /v1/auth/register o POST /v1/auth/login y dura 24 horas. Pensada para apps con usuarios que inician 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-08T00:00:00Z",
  "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.

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"
  }'

{
  "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",
  "status": "active",
  "kyc_status": "approved",
  "created_at": "2026-06-01T12:00:00Z"
}

PATCH /v1/me acepta display_name, tax_id, phone y country (envía solo los que cambian). El email, status y kyc_status no se autogestionan: los resuelve el administrador.

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.

​Tipos de credencial

​Nivel de acceso

​Tu perfil de cuenta

​Miembros de una empresa

​Buenas prácticas

Tipos de credencial

Nivel de acceso

Tu perfil de cuenta

Miembros de una empresa

Buenas prácticas