Autenticación

Mibizum usa API keys con scope, no OAuth ni sesiones. Cada tenant tiene dos pares de claves (live y test) y dentro de cada par dos roles (publica y privada).

Tipos de clave

Tipo	Prefijo	Donde usarla	Que puede
Publica live	`mb_pk_live_`	Frontend del navegador, widget, SDK JS publico	Solo lectura: `/search`, `/track`, `/widget-bootstrap`
Privada live	`mb_sk_live_`	Backend de tu tienda, scripts de indexación, server-to-server	Lectura + escritura: indexar, gestionar sinónimos, reglas
Publica test	`mb_pk_test_`	Staging del frontend	Igual que la publica live pero contra el tenant test
Privada test	`mb_sk_test_`	Staging del backend	Igual que la privada live pero aislada

Crítico

La clave privada nunca debe aparecer en HTML, JS del navegador, repos publicos, capturas o logs accesibles desde fuera. Si se filtra, rotarla inmediatamente desde Ajustes > API Keys.

Cómo autenticar

Todas las peticiones llevan la cabecera estándar:

http

Authorization: Bearer mb_pk_live_a1b2c3d4...

Ejemplo con curl:

bash

curl https://api.mibizum.io/v1/tu-tienda/search?q=hidratante \
  -H "Authorization: Bearer mb_pk_live_a1b2c3d4..."

Ejemplo con fetch desde el navegador (usar SIEMPRE la publica):

const r = await fetch(
  'https://api.mibizum.io/v1/tu-tienda/search?q=hidratante',
  { headers: { Authorization: `Bearer ${publicKey}` } },
);

Ejemplo con el SDK JS (el SDK maneja la cabecera por ti):

import { Mibizum } from '@mibizum/sdk';
const mb = Mibizum.init({ tenant: 'tu-tienda', publicKey: 'mb_pk_live_...' });
const r = await mb.search('hidratante');

Códigos de respuesta de auth

Código	Significado	Como arreglarlo
401 `unauthorized`	Cabecera ausente o token malformado	Añadir `Authorization: Bearer <key>`
401 `invalid_key`	La clave no existe o esta revocada	Verifica en el panel; regenera si dudas
403 `forbidden_scope`	Usaste publica en endpoint de escritura	Cambia a la privada en tu backend
403 `tenant_mismatch`	La clave pertenece a otro tenant del que llamas	Verifica `tenant_slug` en la URL
429 `rate_limited`	Superado el rate limit	Espera el `Retry-After`

Rotación de claves

Buenas prácticas:

Rota las claves cada 90 días o tras cualquier sospecha de filtración.
Manten dos claves activas durante la rotación para no romper producción: crea la nueva, deploya, revoca la vieja.
Usa claves test para todo lo que no sea prod: el tenant test esta totalmente aislado, no contamina métricas reales.
Audita el uso en Ajustes > API Keys > Actividad: ves IPs, últimas llamadas y posibles abusos.

Restricciones por IP (proximamente)

En la roadmap esta poder restringir cada clave privada a una lista de IPs o rangos CIDR. Mientras tanto, mantente las privadas solo en tu servidor.

Autenticación ​

Tipos de clave ​

Cómo autenticar ​

Códigos de respuesta de auth ​