Flujo de autorización

Authorization Code con PKCE paso a paso — el único flujo soportado en OAuth 2.1 de Whatalo.

Whatalo implementa el flujo Authorization Code con PKCE conforme a OAuth 2.1. PKCE es obligatorio — no existe ningún flujo implícito ni de credenciales de cliente para acceso en nombre de usuarios.

Prerrequisitos

client_id obtenido via registro dinámico
URI de redirección registrada exactamente como la usarás

Paso 1 — Genera el par PKCE

import { randomBytes, createHash } from "crypto";

// code_verifier: 43–128 caracteres URL-safe aleatorios
const codeVerifier = randomBytes(32).toString("base64url");

// code_challenge: SHA-256 del verifier, codificado en base64url
const codeChallenge = createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

Solo se acepta code_challenge_method=S256. El método plain está explícitamente rechazado conforme a OAuth 2.1.

Paso 2 — Redirige al usuario al endpoint de autorización

Construye la URL y redirige:

GET https://app.whatalo.com/oauth/authorize?
  response_type=code
  &client_id=abc123def456ghi789jkl012
  &redirect_uri=https%3A%2F%2Fmi-app.com%2Foauth%2Fcallback
  &scope=read%3Aproducts%20read%3Aorders
  &state=VALOR_OPACO_ALEATORIO
  &code_challenge=THE_CHALLENGE_B64URL
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.whatalo.com

Parámetros de la solicitud

Parámetro	Requerido	Descripción
`response_type`	Sí	Siempre `code`
`client_id`	Sí	El `client_id` de tu registro
`redirect_uri`	Sí	Debe coincidir exactamente con una URI registrada
`scope`	Sí	Scopes separados por espacio. Ver Scopes
`state`	Sí	Valor opaco aleatorio. Valídalo al recibir el callback para evitar CSRF
`code_challenge`	Sí	SHA-256 del `code_verifier`, en base64url
`code_challenge_method`	Sí	Siempre `S256`
`resource`	No	RFC 8707. Indica el servidor de recurso destino. Política de valor único.

¿Qué ve el usuario?

El usuario ve la pantalla de consentimiento de Whatalo donde:

Inicia sesión (si no lo ha hecho)
Selecciona la tienda que quiere conectar
Revisa los permisos que solicita tu app
Aprueba o rechaza

Vinculación por tienda: el access_token emitido queda vinculado a la tienda que el usuario seleccionó. Si tu app necesita acceder a múltiples tiendas del mismo usuario, inicia un flujo de autorización separado por cada tienda.

Paso 3 — Recibe el código de autorización

Whatalo redirige de vuelta a tu redirect_uri:

GET https://mi-app.com/oauth/callback?code=AUTH_CODE_AQUI&state=VALOR_OPACO_ALEATORIO

Valida que state coincida con el valor que enviaste antes de continuar. Si no coincide, descarta el código — es posible un ataque CSRF.

El código de autorización:

Es de un solo uso
Expira en 10 minutos
Está vinculado a tu code_verifier via PKCE

Paso 4 — Intercambia el código por tokens

Llama al token endpoint con el código y el code_verifier:

POST https://app.whatalo.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_AQUI
&redirect_uri=https%3A%2F%2Fmi-app.com%2Foauth%2Fcallback
&client_id=abc123def456ghi789jkl012
&code_verifier=EL_CODE_VERIFIER_ORIGINAL

Recibirás un access_token y un refresh_token. Ver Token endpoint para el detalle completo.

Requisitos de URI de redirección

Caso	Permitido
`https://` en producción	Sí
`http://localhost` o `http://127.0.0.1`	Sí (solo desarrollo)
`http://` en dominios públicos	No
Substring de una URI registrada	No — debe coincidir exactamente
Múltiples URIs registradas	Sí, hasta 10 por cliente

Siguiente paso

Con los tokens obtenidos, úsalos para llamar a la API de Whatalo con Authorization: Bearer <access_token>. Cuando el access token expire, usa el token endpoint con grant_type=refresh_token.

On this page