Autenticación, integración y configuración

Estado documental: Implementado y verificado en Producción para autenticación e identidad de integración.

Objetivo: Referencia rápida del contrato productivo usado por una integración para autenticarse frente a YUPY y obtener permisos efectivos.

Endpoint productivo de autenticación

Base URL productiva

https://api.yupy.us

Obtener token

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

{
  "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"
  ]
}

Los valores de tiempo y scopes dependen de la credencial activa. El integrador debe usar lo que YUPY devuelve y no asumir valores fijos.

Uso del Bearer

Authorization: Bearer <ACCESS_TOKEN>

El Bearer se utiliza únicamente desde backend para acceder a operaciones protegidas.

Scopes

Los scopes definen las operaciones permitidas para la credencial.

Para Web Checkout, los scopes habituales son:

orders:write
orders:read

YUPY administra y asigna esos permisos. El caller no puede solicitar scopes arbitrarios ni elevar privilegios desde el request.

Identidad del cliente

El client_id forma parte de la credencial de autenticación y determina la identidad canónica del cliente frente a YUPY.

Una vez autenticado, el caller no debe intentar seleccionar otro cliente mediante campos de infraestructura dentro de operaciones como Web Checkout.

credencial activa
    ↓
client_id
    ↓
cliente autenticado
    ↓
políticas y configuración aplicables

Separación entre identidad y configuración interna

La autenticación identifica al cliente y aplica scopes. No expone ni permite administrar directamente:

• Counters;
• slots o capacidad runtime;
• instrumentos de pago;
• QR concretos;
• policy_config;
• metadata operativa interna;
• resolución de master_data.

Esas capacidades pertenecen a la configuración y administración interna de YUPY.

Flujo con Web Checkout

POST /v1/auth/token
    ↓
Bearer temporal
    ↓
POST /v1/checkouts
    ↓
YUPY deriva cliente y contexto
    ↓
checkout_url

Credenciales y navegador

client_secret
→ backend solamente

access_token
→ backend solamente

checkout_url
→ puede llegar al frontend

checkout token
→ limitado a una experiencia de checkout

El navegador no debe recibir client_secret ni Bearer.

Rotación y revocación

El ciclo de vida de credenciales se administra mediante las herramientas administrativas autorizadas de YUPY.

• Un secreto perdido se rota; no se recupera en claro.
• Una credencial revocada deja de poder obtener nuevos tokens.
• Los tokens pueden invalidarse conforme a la política aplicada.

Errores de autenticación

Una solicitud puede ser rechazada cuando:

• las credenciales son inválidas;
• la credencial está revocada o inactiva;
• el token temporal venció;
• el scope requerido no está presente;
• el ambiente no corresponde.

El integrador debe corregir credenciales o solicitar un token nuevo según corresponda; no debe reintentar indefinidamente con datos inválidos.

Qué no está expuesto por este contrato

Esta página no documenta como API pública activa endpoints administrativos para crear perfiles, administrar Counters, metadata, payment method policies o instruments.

Esas capacidades siguen bajo ownership de YUPY y no forman parte del contrato público de autenticación del integrador.

Criterios de aceptación

1. El endpoint productivo de Auth es POST /v1/auth/token.
2. El request usa client_id, client_secret y grant_type = client_credentials.
3. La respuesta contiene Bearer temporal, vigencia, ambiente y scopes.
4. El Bearer se usa únicamente desde backend.
5. El navegador no recibe secretos privados.
6. Los scopes limitan las operaciones permitidas.
7. El cliente se deriva de la credencial.
8. Auth no administra infraestructura interna de pago.

Changelog

2026-08-26 — Producción: se retiró de esta referencia el inventario de endpoints administrativos propuestos y se dejó únicamente el contrato público verificado de autenticación e identidad: /v1/auth/token, client_credentials, Bearer temporal, scopes y separación entre identidad autenticada y configuración interna de YUPY.