Saltar al contenido principal

API Keys

En /dashboard/api la organización gestiona las claves de API. Cada clave pertenece a una organización, tiene un conjunto de alcances (scopes) y puede revocarse en cualquier momento.

:::caution La API pública ya no usa clave de API La /api/v1 pasó a aceptar solo el access token del Authorization Server de Kobana (Authorization: Bearer <token>), verificado contra la clave pública que este publica. Una clave creada aquí no autentica la API pública.

El motivo es que la clave era al mismo tiempo la credencial y lo que la verificaba: quien leyera el repositorio de claves actuaba como cualquier organización, y cada rotación era una conversación con un cliente. Con el token, quien emite es el Authorization Server y la plataforma solo puede verificar. :::

Tipos de clave​

  • Live (sk_live_...) — se usan en producción. Operan contra datos reales y generan cobros reales.
  • Test (sk_test_...) — apuntan al sandbox; ideales para la integración inicial y las pruebas automatizadas.

Crear una clave​

  1. Haz clic en Nueva clave.
  2. Dale un nombre descriptivo (ej.: "Backend producción", "Worker de importación").
  3. Selecciona los alcances:
    • subscriptions:read / subscriptions:write
    • invoices:read / invoices:write
    • payments:read / payments:write
    • customers:read / customers:write
    • nfes:read / nfes:write
    • webhooks:manage
  4. Opcionalmente, restringe por IP (lista de prefijos CIDR).
  5. La clave se muestra una única vez después de crearla. Cópiala y guárdala en un gestor de secretos.

Buenas prácticas​

  • Una clave por aplicación — facilita revocar el acceso sin afectar otros sistemas.
  • Alcances mínimos — concede solo lo que la aplicación necesita.
  • Rotación periódica — genera una clave nueva, actualiza la aplicación y revoca la anterior.
  • Nunca hagas commit — las claves deben vivir en variables de entorno o en un gestor de secretos.

Rate limits​

Cada clave respeta los límites configurados en Rate Limiting. Los excesos devuelven 429 Too Many Requests con el header Retry-After.

Auditoría y uso​

La página muestra:

  • Status — active o revoked
  • Último uso — fecha, IP y endpoint llamado
  • Volumen — solicitudes en las últimas 24 h y en los últimos 30 días

Toda creación o revocación queda registrada en Auditoría.

Documentación de la API​

La referencia completa de los endpoints está disponible en la sección API del menú lateral.

Captura de pantalla​

Lista de API keys con nombre, alcances, último uso y status