Autenticación

Comprende los dos métodos de autenticación en el ecosistema de plugins de Whatalo — API keys para llamadas servidor a servidor, y session tokens para llamadas frontend a backend.

Los plugins de Whatalo utilizan dos métodos de autenticación distintos dependiendo de qué capa realiza la solicitud. Entender la diferencia evita el error de seguridad más común que cometen los desarrolladores de plugins: exponer API keys en el código del navegador.

Dos Métodos de Autenticación

1. API Key (Servidor a Servidor)

Utilizada por el backend de tu plugin para llamar a la API REST de Whatalo.

Header: X-API-Key: wk_live_* (producción) o wk_test_* (desarrollo)
Se emite automáticamente cuando un comerciante instala tu plugin
Credencial de larga duración — trátala como una contraseña
Con alcance a una sola tienda — un comerciante, una key
Nunca debe aparecer en JavaScript del navegador, código frontend, ni bundles del cliente

// Solo lado servidor (Node.js, Edge Runtime, función serverless)
import { WhataloClient } from "@whatalo/plugin-sdk";

const client = new WhataloClient({
  apiKey: process.env.WHATALO_API_KEY!,
});

const products = await client.products.list({ page: 1, per_page: 25 });

2. Session Token (Frontend a Backend)

Utilizado por el frontend de tu plugin (iframe) para autenticar solicitudes a TU backend. El session token prueba que la solicitud proviene de un usuario autenticado dentro del admin de Whatalo.

JWT de corta duración (expiración en 5 minutos)
Emitido por Whatalo cuando el admin carga tu plugin
Contiene el ID de tienda, ID de app, scopes otorgados e información de instalación
Se verifica en tu backend usando WHATALO_CLIENT_SECRET
No puede llamar a la API de Whatalo directamente — es una prueba de identidad, no un token de acceso para la API de Whatalo

// Frontend (iframe del plugin)
import { sessionToken } from "@whatalo/plugin-sdk/bridge";

const { token } = await sessionToken();

const response = await fetch("https://tu-backend.com/api/products", {
  headers: { Authorization: `Bearer ${token}` },
});

Errores Comunes

Exponer la API key en el frontend

// MAL — la API key es visible para cualquiera que abra las DevTools
const client = new WhataloClient({ apiKey: "wk_live_abc123" });
const products = await client.products.list();

Esto es incorrecto incluso si la key se carga desde una variable de entorno en tiempo de build, porque el build inline pone el valor en el bundle de JavaScript que se envía al navegador.

Llamar a la API de Whatalo con un session token

// MAL — los session tokens no pueden autenticar contra la API de Whatalo
const response = await fetch("https://api.whatalo.com/v1/products", {
  headers: { Authorization: `Bearer ${sessionToken}` },
});
// Devuelve 401 — los session tokens son para tu backend, no para la API de Whatalo

Patrón Correcto

// ─── Plugin Frontend (se ejecuta en el iframe) ────────────────────────────

import { sessionToken } from "@whatalo/plugin-sdk/bridge";

async function loadProducts() {
  // Paso 1: Obtener un session token de corta duración desde el App Bridge
  const { token } = await sessionToken();

  // Paso 2: Enviarlo a TU backend, no a la API de Whatalo
  const res = await fetch("/api/products", {
    headers: { Authorization: `Bearer ${token}` },
  });

  return res.json();
}

// ─── Plugin Backend (se ejecuta en tu servidor) ────────────────────────────

import { verifyWhataloSessionToken } from "@whatalo/plugin-sdk/server";
import { WhataloClient } from "@whatalo/plugin-sdk";

export async function GET(request: Request) {
  const authHeader = request.headers.get("Authorization") ?? "";
  const token = authHeader.replace("Bearer ", "");

  // Paso 3: Verificar el session token usando tu client secret
  let claims;
  try {
    claims = verifyWhataloSessionToken(token, process.env.WHATALO_CLIENT_SECRET!);
  } catch {
    return new Response("No autorizado", { status: 401 });
  }

  // Paso 4: Usar tu API key para llamar a la API de Whatalo desde el servidor
  const client = new WhataloClient({ apiKey: process.env.WHATALO_API_KEY! });
  const products = await client.products.list({ page: 1, per_page: 25 });

  return Response.json(products);
}

Variables de Entorno

Ambas credenciales son configuradas por la CLI durante el desarrollo e inyectadas como variables de entorno en producción.

Variable	Descripción	De Dónde Viene
`WHATALO_API_KEY`	API key con alcance de tienda — usada por `WhataloClient`	Emitida al instalar el plugin
`WHATALO_CLIENT_SECRET`	Secreto del plugin — usado para verificar session tokens y firmas de webhooks	Emitido al crear el plugin

Consulta Variables de Entorno para la lista completa y cómo gestionarlas entre entornos.

Páginas Relacionadas

Session Tokens — referencia completa de session tokens, incluyendo auto-refresh y claims
Scopes y Permisos — cómo declarar a qué datos puede acceder tu plugin
Mejores Prácticas de Seguridad — gestión de secretos, verificación de webhooks y validación de entrada

On this page