OAuth 2.1 — Visión general | Whatalo Developer Platform

Cómo OAuth permite que aplicaciones de terceros actúen en nombre de comerciantes en Whatalo.

OAuth 2.1 es el mecanismo correcto cuando tu aplicación necesita acceder a la API de Whatalo en nombre de un comerciante. A diferencia de una API Key que identifica una integración única, un token OAuth está vinculado a un usuario que autorizó tu app y a la tienda específica que eligió en el momento del consentimiento.

¿Cuándo usar OAuth vs. API Keys?

Criterio	API Key	OAuth 2.1
Quién autorizó el acceso	El propio comerciante, manualmente	El comerciante via flujo de consentimiento
Vinculado a	Una tienda (configuración manual)	La tienda que el usuario selecciona al autorizar
Soporte multitenant	No (una key por tienda)	Sí (un app para muchas tiendas)
Acceso delegado	No	Sí
Ideal para	Scripts internos, servidor a servidor	Apps de terceros, clientes MCP, integraciones SaaS
Revocación	Manual desde el dashboard	Por el usuario desde ajustes, o al expirar el token

Flujo de alto nivel

Tu app                       Whatalo AS                  Tienda del comerciante
   │                              │                               │
   │── POST /oauth/register ─────►│                               │
   │◄── client_id ───────────────│                               │
   │                              │                               │
   │── GET /oauth/authorize ─────►│                               │
   │                              │◄── usuario selecciona tienda ─│
   │◄── ?code=AUTH_CODE ─────────│                               │
   │                              │                               │
   │── POST /oauth/token ────────►│                               │
   │◄── access_token + refresh ──│                               │
   │                              │                               │
   │── Authorization: Bearer ────►│ (API v1)                      │

Conformidad con estándares RFC

Whatalo implementa los siguientes estándares como Authorization Server:

RFC	Nombre	Soporte
OAuth 2.1 (draft)	Marco base actualizado	Completo
RFC 7591	Dynamic Client Registration	Completo
RFC 7662	Token Introspection	Completo
RFC 7009	Token Revocation	Completo
RFC 8414	Authorization Server Metadata	Completo
RFC 8707	Resource Indicators	Parcial — política de valor único
RFC 6749 §4.1	Authorization Code Flow	Completo (con PKCE obligatorio)

Base URL del Authorization Server

https://app.whatalo.com

Todos los endpoints OAuth se sirven desde esta base. Nunca escribas las URLs de endpoint manualmente — usa el endpoint de Discovery para resolverlas en tiempo de ejecución.

Formato del access_token

Whatalo emite tokens opacos (no JWT). Esta decisión arquitectónica afecta directamente cómo tu Resource Server valida los tokens:

El access_token es una cadena aleatoria de 32 bytes codificada en base64url. No contiene información decodificable del lado del cliente.
No se firma con claves públicas, por lo que el endpoint de Discovery no expone jwks_uri.
Para validar un token, tu Resource Server debe llamar al endpoint de Introspección en cada request (con caché opcional, TTL ≤ 60 s).

Implicaciones para tu Resource Server

Tema	Tokens opacos (Whatalo)	Tokens JWT firmados
Validación	Round-trip a `/oauth/introspect`	Verificación local con JWKS
Latencia añadida	~50–100 ms (mitigable con caché)	Cero
Revocación instantánea	Sí — efectiva al expirar el caché	Difícil — requiere denylist
Privacidad del token	Cero metadata expuesta	Claims visibles si se decodifica

Es una decisión deliberada. Los tokens opacos permiten revocación inmediata cuando un comerciante revoca el acceso de una app desde sus ajustes — todos los tokens activos se invalidan al instante. Con JWTs firmados, este caso requeriría una denylist distribuida adicional.

Caché recomendado

Cachea respuestas active: true de Introspección con TTL máximo 60 segundos por token. No caches respuestas active: false — un token puede ser revocado en cualquier momento por el usuario, y un caché agresivo retrasaría la revocación efectiva.

Páginas de referencia

Página	Descripción
Discovery	Metadata del Authorization Server (RFC 8414)
Registro de clientes	Registro dinámico de tu app (RFC 7591)
Flujo de autorización	Authorization Code + PKCE paso a paso
Token endpoint	Intercambio de código y renovación de tokens
Introspección	Validación de Bearer tokens (RFC 7662)
Revocación	Revocar tokens activos (RFC 7009)
Scopes	Tabla completa de los 15 scopes disponibles
Errores OAuth	Códigos de error y cómo manejarlos

OAuth 2.1 — Visión general

On this page