Autenticación

Las APIs de Migo usan dos esquemas de autenticación distintos según la superficie que estés llamando:

Esquema	Dónde aplica	Header / ubicación
Merchant token (secreto de larga vida)	Payment Links (`POST /transactions`) y Pagos Alternativos (`POST /api/v1/integrations/transactions[/{uid}/payments\|/payment-intents\|/dismiss]`)	Enviado en el header `Authorization` — consulta Formato de header por endpoint abajo
Credenciales en el cuerpo (`privateKey` + `publicKey`)	Solo `POST /transactions-hook` (Payment Links amigables al navegador)	Dentro del cuerpo JSON

Un esquema JWT Bearer aparte lo usan las superficies de Wallet y CMS (flujos de usuario final y de backoffice). Si estás integrando Payment Links o Pagos Alternativos, el merchant token es todo lo que necesitas — no se requiere un round-trip de login. Salta directo a Merchant token abajo.

Formato de header por endpoint

El mismo merchant token autentica ambas superficies. El authorizer compartido de tokens quita un prefijo Bearer opcional antes de buscar el token, por lo que el token se acepta con o sin el prefijo. Los ejemplos a continuación usan el formato convencional de cada superficie.

Familia de endpoint	Ejemplo	Formato del header
Payment Links	`POST /transactions`	`Authorization: <token>` (comúnmente enviado sin prefijo de esquema)
Pagos Alternativos	`POST /api/v1/integrations/transactions`, `POST /api/v1/integrations/transactions/{uid}/payments`, `POST /api/v1/integrations/transactions/{uid}/payment-intents`, `POST /api/v1/integrations/transactions/{uid}/dismiss`	`Authorization: Bearer <token>` (prefijo de esquema Bearer)

Un token, ambas superficies

Es el mismo merchant token en ambas familias de endpoints. El authorizer normaliza un prefijo Bearer opcional antes de hacer match con el token, por lo que puedes conservar el mismo valor y agregar u omitir el prefijo.

Merchant token

El merchant token es un secreto de larga vida emitido por Migo cuando se registra tu aplicación. Un solo token autentica dos familias de endpoints — Payment Links y Pagos Alternativos — pero el formato convencional del header difiere por familia. Consulta Formato de header por endpoint arriba para la matriz canónica.

Payment Links — `Authorization: <token>` (sin prefijo)

El punto de entrada de Payment Link POST /transactions valida Authorization haciendo match contra el registro del comercio (el authorizer quita primero un prefijo Bearer opcional). La forma convencional envía el token como el valor completo del header:

Authorization: <your-merchant-token>

curl -X POST https://sb-mw.migopayments.com/transactions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: b6a615d8...0ba65c1' \
  -d '{ "amount": 1, "userId": "+50224865444", "channel": "wa", "client": "your-client-slug", "ads": [] }'

Pagos Alternativos — `Authorization: Bearer <token>` (prefijo Bearer)

Las rutas de Pagos Alternativos (/api/v1/integrations/transactions[…]) aceptan el mismo merchant token, convencionalmente enviado con un prefijo Bearer :

Authorization: Bearer <your-merchant-token>

# El mismo token de arriba, distinto formato de header
curl -X POST https://sb-mw.migopayments.com/api/v1/integrations/transactions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer b6a615d8...0ba65c1' \
  -d '{ "amount": 50, "channel": "web", "client": "your-client-slug", "userId": "+50224865444" }'

¿Por qué dos convenciones?

Payment Links es anterior al servicio de Pagos Alternativos; cada uno aterrizó con convenciones documentadas distintas, por lo que los ejemplos difieren por superficie. El token en sí es idéntico, y el authorizer compartido lo acepta con o sin un prefijo Bearer . La misma convención se muestra en Crear un Payment Link, en el Cheat sheet de Sandbox y en Pagos Alternativos — Visión general.

Vida útil y rotación

El merchant token es de larga vida. No hay flujo de refresh para comercios.
Trátalo como una contraseña de base de datos: guárdalo en tu gestor de secretos, nunca lo embebas en código del lado cliente y rótalo a través de tu contacto de Migo cada vez que el secreto pueda haberse expuesto.
Los tokens de Sandbox y producción son distintos — no puedes usar un token de Sandbox contra https://mw.migopayments.com.

Alternativa con credenciales en el cuerpo (`/transactions-hook`)

Las integraciones que no pueden mantener un token del lado servidor (single-page apps, widgets embebidos) pueden autenticar POST /transactions-hook enviando privateKey + publicKey en el cuerpo JSON. El endpoint hashea el par para identificar tu aplicación y habilita CORS para que un navegador pueda llamarlo directamente. Consulta Crear un Payment Link → endpoint alternativo.

JWT Bearer (superficies de Wallet y CMS)

Las superficies de Wallet y CMS usan JWTs firmados con Ed25519 en lugar del merchant token. El flujo es similar en ambas, pero cada una tiene su propio endpoint de login y su propio token. Solo necesitas esta sección si estás integrando esas superficies — Payment Links y Pagos Alternativos no la usan.

Flujo de token

Inicia sesión con tus credenciales para recibir un access token + refresh token.
Adjunta el access token como Authorization: Bearer <token> en cada solicitud.
Refresca cuando el access token expire — no vuelvas a iniciar sesión a menos que el refresh token también haya expirado.

Los access y refresh tokens son de corta vida en comparación con el merchant token. La respuesta de login retorna los tokens emitidos. Las vidas útiles de los tokens son configurables; algunas llamadas de login y refresh aceptan campos opcionales accessTokenTtl y refreshTokenTtl (en segundos) para sobrescribir las vidas útiles emitidas. Los tokens se firman con Ed25519; la llave pública es estable por entorno. Contacta a Migo para obtener el par de llaves de tu integración.

Dos flujos de login distintos — elige según el tipo de llamador:

# Login de aplicación (usado por servicios backend que llaman al gateway)
POST https://api.ali.app/rest/auth/login
Content-Type: application/json

{
  "merchant": "YOUR_MERCHANT_SLUG",
  "signature": "<ed25519_sign(merchant) in base64>"
}

La aplicación prueba su identidad con un desafío de firma Ed25519: firma tu identificador de comercio (el string merchant en texto plano) con tu llave privada y envía la firma en base64. El gateway la verifica contra tu llave pública registrada y retorna los tokens de acceso + refresh de la aplicación. No existe un par applicationId/secret.

# Login de usuario final (usado por la app de billetera en representación del titular de tarjeta)
POST https://api.ali.app/rest/users/login
Content-Type: application/json
Authorization: Bearer <application-access-token>

{
  "username": "user@example.com",
  "password": "user-password"
}

El login de usuario final está autenticado por el access token de la aplicación obtenido en /auth/login (enviado como Authorization: Bearer <token>). El cuerpo usa un campo username; un campo opcional merchant soporta el login multi-tenant.

El CMS requiere dos tokens: un JWT de la aplicación más un JWT de usuario del CMS.

# 1. Login de aplicación
POST https://api.ali.app/cms/rest/app/auth/login
Content-Type: application/json

{ "merchant": "your-merchant-slug" }

# 2. Login de usuario del CMS
POST https://api.ali.app/cms/rest/app/users/login
Authorization: Bearer <app-access-token>
Content-Type: application/json

{ "email": "operator@partner.com", "password": "..." }

Ambas llamadas retornan access y refresh tokens. Envía el access token de la aplicación como header Authorization: Bearer para las rutas con alcance de aplicación; el token de usuario del CMS se envía de la misma forma para las rutas con alcance de usuario.

Refresh

Cuando el access token expire, refresca en lugar de volver a iniciar sesión.

POST https://api.ali.app/rest/auth/refresh
Content-Type: application/json

{ "refreshToken": "<refresh-token>" }

La respuesta trae un nuevo access token y refresh token.

/auth/refresh refresca el access token de la aplicación/integración. La sesión de usuario final (billetera) obtenida en POST /users/login tiene su propio endpoint de refresh:

POST https://api.ali.app/rest/users/refresh
Authorization: Bearer <application-access-token>
Content-Type: application/json

{ "refreshToken": "<user-refresh-token>" }

Se pueden proporcionar los campos opcionales merchant, accessTokenTtl y refreshTokenTtl para sobrescribir las vidas útiles de los tokens emitidos. La respuesta retorna un nuevo access token y refresh token de usuario.

OTP (solo flujos de usuario final)

Algunos flujos de usuario final requieren un OTP emitido por email. Todas las llamadas de OTP requieren el JWT de la aplicación (Authorization: Bearer <application-access-token>). El patrón es:

POST /users/auth/otp — solicita un OTP. Cuerpo: { "email": "user@example.com", "purpose": "<purpose>" }.
El usuario ingresa el código de 6 dígitos recibido por email.
PUT /users/auth/otp — envía el código. Cuerpo: { "email": "...", "otp": "123456", "purpose": "<purpose>" }. En caso de éxito, el data de la respuesta lleva el resultado de la verificación; para el propósito password_reset incluye un token que pasas a la llamada de restablecimiento de contraseña.

El campo purpose es un string de formato libre que debe coincidir entre los pasos de solicitud y verificación. El valor documentado para el flujo de restablecimiento de contraseña de abajo es password_reset.

Restablecimiento de contraseña

Restablecer la contraseña de un usuario final es un flujo de dos pasos protegido por OTP. Ambas llamadas requieren el JWT de la aplicación (Authorization: Bearer <application-access-token>).

# 1. Solicita un OTP con el propósito "password_reset"
POST https://api.ali.app/rest/users/auth/otp
Authorization: Bearer <application-access-token>
Content-Type: application/json

{ "email": "user@example.com", "purpose": "password_reset" }

# 2. Verifica el código enviado por email — el data de la respuesta incluye un "token"
PUT https://api.ali.app/rest/users/auth/otp
Authorization: Bearer <application-access-token>
Content-Type: application/json

{ "email": "user@example.com", "otp": "123456", "purpose": "password_reset" }

# 3. Restablece la contraseña usando ese token
POST https://api.ali.app/rest/users/auth/password/reset
Authorization: Bearer <application-access-token>
Content-Type: application/json

{
  "email": "user@example.com",
  "newPassword": "NewStrongP@ssw0rd!",
  "confirmPassword": "NewStrongP@ssw0rd!",
  "token": "<token-from-otp-verification>"
}

Cerrar sesión / finalizar una sesión

Finaliza una sesión de usuario con:

POST https://api.ali.app/rest/users/logout
Authorization: Bearer <application-access-token>

La llamada invalida la sesión activa del usuario. Requiere el JWT de la aplicación.

Formato de header por endpoint​

Merchant token​

Payment Links — Authorization: <token> (sin prefijo)​

Pagos Alternativos — Authorization: Bearer <token> (prefijo Bearer)​

¿Por qué dos convenciones?​

Vida útil y rotación​

Alternativa con credenciales en el cuerpo (/transactions-hook)​

JWT Bearer (superficies de Wallet y CMS)​

Flujo de token​

Login de Wallet​

Login de CMS​

Refresh​

OTP (solo flujos de usuario final)​

Restablecimiento de contraseña​

Cerrar sesión / finalizar una sesión​

Relacionado​