Autenticación y credenciales de integración

Estado documental: Implementado y verificado en Producción.

Principio general

Las credenciales privadas de integración son emitidas y administradas por YUPY para un cliente determinado.

YUPY emite Client ID + Client Secret
        ↓
Backend de la empresa los almacena de forma segura
        ↓
Backend solicita un access token temporal
        ↓
Backend usa el Bearer para llamar la API productiva

Regla de seguridad: el client_secret nunca debe llegar al navegador, JavaScript frontend, aplicación móvil sin backend seguro, URL, logs públicos ni analítica de terceros.

Base URL productiva

https://api.yupy.us

Obtener un access token

POST https://api.yupy.us/v1/auth/token
Content-Type: application/json

Solicitud:

{
  "client_id": 1,
  "client_secret": "<YUPY_CLIENT_SECRET>",
  "grant_type": "client_credentials"
}

Ejemplo:

curl --request POST \
  --url 'https://api.yupy.us/v1/auth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": 1,
    "client_secret": "<YUPY_CLIENT_SECRET>",
    "grant_type": "client_credentials"
  }'

Respuesta

{
  "access_token": "<OPAQUE_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in_seconds": 3600,
  "expires_at": "2026-08-26T21:00:00-05:00",
  "environment": "production",
  "scope": [
    "orders:write",
    "orders:read"
  ]
}

La vigencia exacta efectiva debe tomarse siempre de expires_in_seconds y expires_at devueltos por YUPY.

Usar el token

Authorization: Bearer <ACCESS_TOKEN>

El access token es temporal. Cuando vence, el backend solicita uno nuevo utilizando la credencial activa.

Scopes

Los scopes determinan qué operaciones puede ejecutar una credencial. Para Web Checkout, los scopes habituales son:

orders:write
orders:read

Para entornos o credenciales autorizadas de prueba, YUPY puede habilitar además:

payments:simulate

payments:simulate permite que los nuevos Web Checkouts creados con un Bearer que contenga ese scope queden habilitados para simulación de pago desde la experiencia alojada de YUPY.

El scope se administra en la credencial del cliente; no se activa desde JavaScript ni enviando un campo libre en el request de checkout.
Al modificar scopes, los Bearer activos pueden quedar invalidados conforme a la política de seguridad; se debe obtener un access token nuevo.
La capacidad de simulación se fija server-side al crear el checkout. Un checkout creado antes de habilitar payments:simulate no se vuelve simulable retroactivamente.
Quitar el scope impide nuevas simulaciones y los nuevos checkouts vuelven al comportamiento normal.

YUPY puede emitir credenciales con otros scopes según las capacidades habilitadas para el cliente. El caller no puede autoasignarse permisos.

Client ID y Client Secret

client_id identifica al cliente autenticado frente a YUPY. El client_secret demuestra que el backend está autorizado a actuar con esa identidad.

El cliente autenticado se deriva de la credencial. El frontend y los requests públicos de Web Checkout no deben intentar seleccionar otra identidad de cliente.

Uso server-to-server

Navegador del comprador
    ✕ no conoce client_secret
    ✕ no solicita access tokens

Backend de la empresa
    ✓ almacena client_secret
    ✓ solicita access_token
    ✓ crea checkouts

YUPY
    ✓ autentica la integración
    ✓ aplica scopes
    ✓ deriva client_id

Separación de credenciales

client_secret
≠ access_token
≠ checkout_url
≠ checkout token
≠ secretos internos de YUPY
≠ futuras firmas de webhook

La checkout_url es una credencial temporal limitada a una experiencia de checkout específica. No permite utilizar la API privada como una credencial general.

Rotación y revocación

YUPY permite administrar el ciclo de vida de credenciales mediante sus herramientas administrativas autorizadas.

Un secreto perdido no se recupera en texto claro: se reemplaza mediante rotación.
Una credencial revocada deja de poder obtener nuevos tokens.
Los tokens asociados pueden invalidarse conforme a la política de seguridad aplicada.
La rotación puede admitir una transición controlada cuando corresponda.

Contexto administrativo de cliente

La consola administrativa interna de YUPY permite que un system_admin opere bajo el contexto de un cliente seleccionado sin impersonar a un usuario de ese cliente.

La identidad del administrador permanece como system_admin.
Seleccionar un cliente solo establece un contexto operativo para filtrar y administrar recursos de ese tenant.
Volver a la vista global elimina ese contexto y recupera la administración de todos los clientes.
Este contexto administrativo no modifica el client_id derivado de credenciales API ni permite que un integrador seleccione otra identidad mediante requests públicos.

Separación de identidades: el contexto administrativo interno y la identidad autenticada de una integración API son conceptos distintos. No existe impersonación ni una credencial maestra de cliente.

Almacenamiento recomendado

Guardar el client_secret en un gestor de secretos, variable protegida del servidor o almacén cifrado equivalente.

No incluirlo en:

JavaScript frontend
HTML
repositorios Git
URLs
capturas
documentación pública
logs de aplicación
herramientas de analítica

Flujo productivo para Web Checkout

Backend empresa
  → POST /v1/auth/token
  → recibe Bearer

Backend empresa
  → POST /v1/checkouts
  → Authorization: Bearer ...
  → Idempotency-Key: ...

YUPY
  → crea checkout
  → devuelve checkout_url

Frontend empresa
  → recibe únicamente checkout_url
  → abre la experiencia con el SDK

Criterios de aceptación

La autenticación productiva utiliza POST /v1/auth/token.
El request usa client_id, client_secret y grant_type = client_credentials.
YUPY devuelve un Bearer temporal.
La respuesta informa vigencia, ambiente y scopes.
El client_secret permanece exclusivamente en backend.
El navegador no obtiene tokens privados de integración.
Los scopes limitan las operaciones permitidas.
El cliente se deriva de la credencial autenticada.
Un secreto perdido se rota, no se recupera.
Una credencial puede revocarse.

Changelog

2026-08-27 — Payment Simulation: se documentó el scope productivo payments:simulate, su activación server-side por credencial, la necesidad de obtener un Bearer nuevo tras cambios de scopes y que la capacidad aplica a checkouts creados después de habilitarla.

2026-08-27 — Producción: se documentó la separación entre la identidad permanente de system_admin y el contexto administrativo temporal de cliente utilizado por la consola interna de YUPY. Este contexto no altera la identidad API derivada de credenciales.

2026-08-26 — Producción: se reemplazó el contrato propuesto por el contrato productivo verificado de POST /v1/auth/token; se documentaron grant_type = client_credentials, environment = production, scopes, separación backend/frontend y el flujo real previo a POST /v1/checkouts.

API Technical Docs