Claves de API

Tres clases de credenciales, tres modelos de amenaza.

`pk_` — Publishable

Diseñada para enviarse al navegador. Se envía como cabecera X-Client-ID en cada petición B2B firmada, también incrustada en el bundle del SDK para aperturas de checkout del lado cliente.
Puede identificar tu cuenta; no puede crear sesiones, leer datos de otros comerciantes ni disparar nada destructivo.
Una clave publishable filtrada es un evento de severidad baja.

`sk_` — Secret (clave de firma HMAC)

La clave de firma HMAC-SHA256 para todas las llamadas a la API B2B: consulta Autenticación.
Nunca viaja por el cable. Solo lo hace su firma derivada por petición. Así que solo tienes que preocuparte por filtraciones en la capa de almacenamiento (variables de entorno, git, logs), no en la capa de transporte.
Solo servidor. Nunca debería aparecer en un bundle de navegador, repo público, captura de pantalla o mensaje de chat.
Una clave secreta filtrada es un evento de severidad alta.

`whsec_` — Secreto de firma de webhook

Se usa para verificar la firma en las entregas de webhook entrantes desde nosotros a tu servidor. Consulta Verificación de firma.
Separado por endpoint de webhook: si tienes 3 endpoints registrados, tienes 3 secretos whsec_ distintos. El entorno está codificado en el prefijo: whsec_live_… / whsec_test_….
Solo servidor. Como sk_, nunca viaja por el cable: solo se usa para verificar HMACs localmente.
La rotación tiene una ventana de gracia de 24 horas. Haz clic en Rotar y el secreto anterior sigue siendo aceptado durante 24h junto con el nuevo (las entregas llevan tanto X-Signature como X-Signature-Prev), así que puedes redesplegar tu verificador sin retener tráfico.
Revelar-secreto-existente está disponible, protegido por 2FA reciente y registrado en el log de auditoría: para el caso en que el secreto se perdió y la rotación no es aceptable. La postura por defecto del dashboard es “rotar, no revelar”.
Un secreto de webhook filtrado deja a un atacante falsificar eventos a tu URL. Severidad media-alta dependiendo de cuánto confíes en el payload del evento.

Scopes

Las claves secretas están con scope. El dashboard te permite emitir claves con uno de estos paquetes de scope:

Scope	Puede hacer	Usado para
`read`	Listar/leer órdenes, sesiones, reembolsos, saldos	Integraciones de solo lectura (analítica, BI)
`write_order`	Todo `read` + crear sesiones, crear órdenes, cancelar órdenes	Backend de tienda
`write_refund`	Todo `read` + crear reembolsos, marcar reembolsos como ejecutados	Herramientas de atención al cliente
`webhook_manage`	Todo `read` + gestionar endpoints de webhook	Tooling de DevOps

Una clave “acceso total” emitida por defecto obtiene los cuatro. Emitir claves por propósito sigue siendo buena higiene: documenta la intención y te prepara para la aplicación cuando llegue, pero lee la advertencia abajo antes de tratar el scope como un límite de seguridad.

Los scopes son consultivos hoy: no se aplican en el gateway. El gateway verifica la firma HMAC de la clave e inyecta tu identidad de comerciante (X-Merchant-ID / X-Merchant-Domain) a los servicios aguas abajo, pero no propaga ni comprueba el scope de la clave. En la práctica eso significa que una sk_ filtrada de cualquier scope puede llamar a cualquier endpoint /b2b/v1/* para tu comerciante: una clave read no está efectivamente impedida de crear un reembolso. Así que los scopes estrechos no limitan el radio de explosión aún: para planificación de breach trata cada clave secreta como acceso total, y apóyate en rotación + revocación rápidas (abajo) como tu contención real. La aplicación por scope está en el roadmap.

Rotación

Genera una nueva clave. Dashboard → Developers → API keys → + Add key. Elige scope. El dashboard muestra el secreto una vez: guárdalo inmediatamente.
Cambia tus variables de entorno al nuevo valor en todos los entornos. Despliega.
Verifica tráfico. El dashboard muestra conteos de peticiones por clave en tiempo real. Espera a que el conteo de la clave antigua caiga a cero.
Revoca la clave antigua. Misma pantalla → menú kebab → Revoke.

No hay ventana de solapamiento automática hoy: una vez que revocas una clave, cualquier petición en vuelo firmada con ella obtiene 401. Planifica tu rotación en consecuencia: despliega primero la nueva clave, drena el tráfico de la antigua, luego revoca.

Revocación de emergencia

Si una clave se ha filtrado (en el historial de git, en un bundle público, en un stack trace logueado, en el reporte de pen-test de un partner): revócala inmediatamente, incluso al coste de algunas peticiones fallidas. Mejor fallar ruidosamente que dejar que un atacante mantenga una credencial válida.

Pasos:

Dashboard → Developers → API keys → [clave] → Revoke now. El efecto es instantáneo; sin periodo de gracia.
Emite un reemplazo y despliega.
Audita la actividad reciente: el dashboard muestra los últimos 30 días de peticiones por clave con IPs y endpoints alcanzados.

Si sospechas que la brecha es más amplia que una clave, contacta [email protected] para:

Obtener una exportación completa del log de auditoría para tu cuenta de comerciante
Rotar secretos de webhook en bulk
Opcionalmente congelar la cuenta mientras investigas

Mejores prácticas de almacenamiento

Solo variables de entorno. Nunca comitees secretos a git, ni siquiera en un .env.example que diga “REPLACE ME”.
Claves por entorno. Distintas sk_test_… y sk_live_… para dev/staging/prod, originadas desde tu gestor de secretos (AWS Secrets Manager, Vault, Doppler, …).
Restringe el acceso a variables de entorno. En Kubernetes, monta como Secret, no ConfigMap. En Vercel/Netlify, usa scoping de variables de entorno, no globales de todo el proyecto.
No loguees peticiones con bodies. Incluso al depurar: tu firma HMAC en X-Signature es de un solo uso pero tu payload de negocio puede incluir PII.

Lo que NO se soporta hoy

❌ Lista blanca de IPs para claves secretas. En el roadmap.
❌ Tokens por usuario con scope estilo OAuth. El modelo de clave actual es por comerciante, no por usuario.
❌ Rotación automática de claves (p. ej. rotación semanal aplicada por la plataforma). Manual hoy.

Qué sigue

Autenticación: algoritmo de firma exacto para llamadas B2B.
Webhooks → Verificación de firma: cómo se usa whsec_ en eventos entrantes.