# 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](https://docs.infraio.xyz/es/api-reference/authentication). - 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](https://docs.infraio.xyz/es/webhooks/signature-verification). - 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 práctica porque documenta la intención, pero lee la advertencia abajo antes de tratar el scope como un límite de seguridad. > **Warning:** > > **Los scopes todavía no se aplican.** Una clave `sk_` filtrada de > *cualquier* scope puede llamar a *cualquier* endpoint `/b2b/v1/*` > de tu comerciante. Una clave `read` no está impedida de crear un > reembolso. Los scopes estrechos **no** limitan aún el daño de una > filtración: para planificación de seguridad trata cada clave > secreta como acceso total y apóyate en la rotación y revocación > rápidas (abajo) para contener una filtración. ## Rotación 1. **Genera una nueva clave.** Dashboard → **Developers → API keys** → **+ Add key**. Elige scope. El dashboard muestra el secreto **una vez**: guárdalo inmediatamente. 2. **Cambia tus variables de entorno** al nuevo valor en todos los entornos. Despliega. 3. **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. 4. **Revoca la clave antigua.** Misma pantalla → menú kebab → **Revoke**. > **Warning:** > > **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: 1. **Dashboard → Developers → API keys → [clave] → Revoke now.** El efecto es instantáneo; sin periodo de gracia. 2. Emite un reemplazo y despliega. 3. 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 contact@lartech.xyz 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. - ❌ **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). La rotación es manual. ## Qué sigue - [Autenticación](https://docs.infraio.xyz/es/api-reference/authentication): algoritmo de firma exacto para llamadas B2B. - [Webhooks → Verificación de firma](https://docs.infraio.xyz/es/webhooks/signature-verification): cómo se usa `whsec_` en eventos entrantes.