Claves de API

Las claves de API son el mecanismo con el que se autentica cada solicitud Liqfy de servidor a servidor. Esta página está dirigida a usuarios del panel/administradores que gestionan las claves de su cuenta; si solo necesitas usar una clave, consulta Primeros pasos.

#Formato de la clave

text

lq_live_<24-byte-base64url>      ← production
lq_test_<24-byte-base64url>      ← sandbox / test

El texto en claro se muestra una sola vez, en el momento de la emisión.
En el servidor solo conservamos la huella SHA-256 y un prefijo de 12 caracteres (p. ej., lq_live_xyz) para mostrarlo en el panel.
¿Perdiste una clave? No se puede recuperar: rótala para emitir una nueva.

El prefijo exacto depende de la marca (aquí lq_live_ / lq_test_); lo universal es la forma <prefix>_live_… / <prefix>_test_…. Nunca escribas un prefijo de forma fija en código que clasifique una clave: los SDK oficiales aceptan el prefijo de cualquier marca y exponen helpers isTestKey que, en su lugar, leen el segmento _test_.

#Uso de una clave en la API

Las llamadas de servidor a servidor a /v1/* envían la clave en la cabecera canónica Authorization: Bearer:

text

Authorization: Bearer lq_live_...

La cabecera heredada apikey: lq_live_... se sigue aceptando por compatibilidad (el gateway reescribe Bearer a la forma interna apikey). Las integraciones nuevas deben enviar Bearer y nada más. Si una solicitud incluye ambas cabeceras, se usa la clave de Authorization: Bearer. Las claves ausentes o no válidas devuelven 401.

En cada solicitud, el gateway decide si la clave es de prueba o live comprobando si empieza por el prefijo de prueba de la marca (lq_test_). Cualquier clave que no empiece por el prefijo de prueba se trata como live (producción). Un cliente no puede forzar el enrutamiento al sandbox enviando su propia cabecera de modo: el gateway siempre la sobrescribe a partir de la clave.

La misma clave también desbloquea los portales OpenAPI en /docs/payments y /docs/webhooks; sin una clave, devuelven 401 como cualquier otra ruta protegida.

La limitación de tasa en las rutas autenticadas con clave se contabiliza por cuenta (el consumidor del gateway asociado a la clave), no por IP, por lo que todas las claves de una misma cuenta comparten un único presupuesto. Las respuestas exponen X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset y Retry-After para que puedas reducir el ritmo.

Nunca registres una clave en logs. Ni en los logs de la aplicación, ni en la salida de CI, ni en un informe de errores: el texto en claro es la credencial, y las huellas existen para que puedas hablar de una clave sin citarla.

#Lista de IP permitidas

Una cuenta puede restringir el tráfico con clave de API a una lista de rangos CIDR. En las rutas que cubre esta protección, una solicitud desde una dirección fuera de la lista se rechaza con 403 antes de que se ejecute la ruta —con el mismo sobre permission_error que en Errores— y la clave en sí no tiene la culpa.

Alcance: la lista de permitidas se aplica en las rutas principales de la cuenta: wallets, retiros, transacciones, casos MED, api-keys y rutas afines. Las rutas de movimiento de dinero /v1/charges, /v1/pix/charges, /v1/payments y /v1/webhooks no están cubiertas por la lista de permitidas por cuenta (el ip-restriction del gateway solo protege /v1/admin).

Incluye todas las direcciones de salida que usan tus integraciones: servidores de producción, runners de CI, hosts de failover y las direcciones NAT de tus regiones de nube. Una entrada incorrecta aquí falla en modo cerrado: la solicitud nunca llega a la verificación de la clave, así que un reporte de "clave válida, pero 403 de todos modos" suele deberse a la lista de permitidas.

Pide a soporte (suporte@liqfy.com.br) que añada, cambie o elimine un rango; la lista se mantiene por cuenta.

#Autenticación: estos endpoints usan JWT, no una clave de API

Todos los endpoints /v1/api-keys/* están autenticados con JWT (el mismo token de inicio de sesión del panel que devuelve POST /v1/auth/login). No están protegidos por el plugin apikey de Kong: eso sería el problema del huevo y la gallina.

text

Authorization: Bearer <dashboard JWT>

El claim de cuenta del JWT delimita cada operación: solo puedes gestionar las claves de tu propia cuenta.

Quién puede: cualquier miembro activo de la cuenta puede listar las claves. Emitir, rotar y revocar requieren el rol OWNER o ADMIN de la cuenta; cualquier otro rol recibe 403 con el código API_KEY_ROLE_REQUIRED.

#Endpoints

#Emitir una clave

text

POST /v1/api-keys

bash

curl -X POST https://api.liqfy.com.br/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production-backend", "test": false }'

Campo	Tipo	Obligatorio	Descripción
`label`	string	no	Texto libre, ≤ 64 caracteres. Se muestra en el panel para las personas.
`test`	boolean	no	`true` emite una clave `lq_test_…`. Valor predeterminado: `false`.

Respuesta 201 Created

json

{
  "id": "5b3a9c1d-...",
  "apiKey": "lq_live_F8A2K7M3N9PQRSTUVWXYZAB",
  "fingerprint": "9a3f7e1c5d8b2a40",
  "prefix": "lq_live_F8A",
  "label": "production-backend",
  "createdAt": "2026-04-25T18:32:11.000Z",
  "mode": "live"
}

mode es el entorno de la clave: test (sandbox, el cobro nunca llega a un proveedor real) o live. Es la misma regla que usa el gateway para enrutar el cobro; lee este campo en lugar de comparar el prefijo.

apiKey solo se muestra aquí. Guárdalo en un gestor de secretos de inmediato. El panel no lo muestra en cargas posteriores.

#Listar tus claves

text

GET /v1/api-keys

Devuelve solo metadatos, sin texto en claro.

json

{
  "data": [
    {
      "id": "5b3a9c1d-...",
      "prefix": "lq_live_F8A",
      "label": "production-backend",
      "createdAt": "2026-04-25T18:32:11.000Z",
      "mode": "live"
    },
    {
      "id": "7f1c4e9a-...",
      "prefix": "lq_test_QRX",
      "label": "ci-tests",
      "createdAt": "2026-04-12T09:14:08.000Z",
      "mode": "test"
    }
  ],
  "access": { "canManage": true }
}

access.canManage indica si quien realiza la llamada puede emitir, rotar y revocar (propietario o administrador de la cuenta).

#Rotar una clave

text

POST /v1/api-keys/{id}/rotate

Revoca de forma atómica la clave indicada y emite una nueva. Úsalo con una cadencia regular (cada 90 días es razonable) o siempre que sospeches que la clave está comprometida.

bash

curl -X POST https://api.liqfy.com.br/v1/api-keys/5b3a9c1d-.../rotate \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "label": "production-backend (rotated 2026-04-25)" }'

La forma de la respuesta es idéntica a la de Emitir una clave, incluido el nuevo texto en claro.

La nueva clave conserva el entorno de la anterior: rotar una clave de prueba emite otra clave de prueba, y rotar una clave live emite otra clave live. También se conserva la etiqueta, a menos que envíes un nuevo label. Un id que no pertenezca a tu cuenta devuelve 404, y no se revoca nada.

Nota operativa: la clave anterior deja de funcionar en el momento en que se completa esta llamada. Despliega la nueva clave en tus servidores ANTES de llamar a rotate, o programa un breve solapamiento emitiendo primero una clave paralela y revocando la anterior una vez que la nueva esté en su lugar.

#Revocar una clave

text

DELETE /v1/api-keys/{id}

Es permanente: no se puede deshacer.

bash

curl -X DELETE https://api.liqfy.com.br/v1/api-keys/5b3a9c1d-... \
  -H "Authorization: Bearer $JWT"

Respuesta 200 OK

json

{ "revoked": true }

#Lista de verificación de seguridad

Trata lq_live_… como una contraseña: nunca la subas a un repositorio, nunca la registres en logs, nunca la pegues en Slack.
Guárdala en un gestor de secretos (1Password, Vault, AWS Secrets Manager, secretos de GitHub Actions, etc.).
Usa claves distintas por entorno (lq_live_… para producción, lq_test_… para staging/CI).
Una clave por servicio / una clave por máquina de desarrollador: así es más fácil revocar una sola clave cuando algo se filtra.
Rota las claves según un calendario. Como mínimo trimestralmente; mensualmente para cargas de trabajo de alta sensibilidad.
Revoca de inmediato cuando un empleado se marche.
Configura alertas sobre los eventos de auditoría "clave emitida" / "clave rotada" del panel.

#Qué se almacena y dónde

Almacenamiento	Qué contiene
Kong (plugin `key-auth`)	La clave en texto en claro, usada para autenticar las solicitudes entrantes.
Base de datos Liqfy (registro del comercio)	`kongConsumerUsername`: el slug del comercio, para la búsqueda inversa. Nunca el texto en claro.
Registro de auditoría	Eventos de emisión / rotación / revocación, con el id del usuario emisor y la huella de la clave.
Panel	Solo prefijo + etiqueta.

#Alternativa por CLI

Para operaciones/onboarding desde una estación de trabajo, las mismas operaciones están disponibles a través de una CLI interna de aprovisionamiento (herramienta exclusiva del equipo de operaciones; no forma parte de la API pública ni del SDK). La CLI se comunica directamente con la Admin API de Kong, y las claves que emite son intercambiables con las emitidas por HTTP.

#Preguntas frecuentes

P: ¿Puedo tener varias claves live a la vez? R: Sí; es útil para rotaciones sin tiempo de inactividad y para aislar por servicio. No hay un límite estricto. Ten en cuenta que todas las claves de una misma cuenta comparten el presupuesto de limitación de tasa de la cuenta.

P: Perdí el texto en claro justo después de crearla. R: Ya no se puede recuperar. Rótala (o revócala y emite una nueva): no existe ninguna vía de recuperación, por diseño.

P: ¿Cómo sé qué clave está haciendo cada solicitud? R: Los logs de solicitudes del panel muestran la huella de la clave en cada llamada. Filtra por apiKeyFingerprint para atribuir el tráfico.

P: ¿Puedo restringir una clave a ciertos endpoints / métodos? R: Todavía no. Los permisos por clave están en la hoja de ruta de la Fase 2. Hoy en día, cada clave tiene acceso completo a la cuenta.