Skip to main content
Las claves de API te permiten acceder a la API REST de Quikly de forma programática. Úsalas con n8n, scripts personalizados, pipelines CI/CD o cualquier cliente HTTP. El mismo tipo de clave autentica la extensión de navegador Discovery Copilot — ver Discovery Copilot.

​
Crear una clave de API

1

Abre la configuración de claves de API

Ve a Configuración → Claves de API en la app de Quikly.
2

Haz clic en Crear Clave de API

Ingresa un nombre descriptivo (ej., “automatización n8n” o “Cursor MCP”) y selecciona los scopes que necesitas.
3

Copia la clave

La clave completa se muestra solo una vez. Cópiala y guárdala en un lugar seguro — no podrás recuperarla después.

​
Scopes

Cada clave de API tiene uno o más scopes que controlan lo que puede hacer:
Sigue el principio de mínimo privilegio. Si una integración solo necesita leer datos, crea una clave con scope read solamente.

​
Autenticar solicitudes

Incluye tu clave de API en el header X-API-Key en cada solicitud:

​
Límites de tasa y cuota

Las llamadas a la API tienen límites de tasa por minuto y un tope mensual dependiendo de tu plan: Cuando excedes la cuota mensual, la API devuelve 402 Payment Required. Cuando excedes el límite por minuto, la API devuelve 429 Too Many Requests e incluye el header Retry-After.

​
Límites por usuario final (X-External-User-Id)

Cuando X-External-User-Id está presente (tras normalización), la API aplica límites adicionales encima de los totales de tu cuenta:
  • Por usuario final por minuto: por defecto 12 solicitudes/minuto por X-External-User-Id distinto (configurable en servidor).
  • Por usuario final por mes calendario UTC: por defecto min(cuota mensual de API de tu plan, 250) llamadas para ese mismo X-External-User-Id.
Si se supera el slice del usuario final, las respuestas usan 402 con error: external_user_quota_exceeded o 429 con error: external_user_rate_limit_exceeded. Estos límites usan contadores en memoria (se reinician al reiniciar el servidor y al cambiar el mes UTC en el contador mensual). Mitigan que un único tenant aguas abajo consuma todo el pool de una API key.

​
Límites por agente / workflow (X-Agent-Id)

Cuando X-Agent-Id está presente (tras normalización), aplica el mismo patrón de forma independiente de X-External-User-Id:
  • Por agente por minuto: por defecto 12 solicitudes/minuto (configurable en servidor).
  • Por agente por mes calendario UTC: por defecto min(cuota mensual de API de tu plan, 250) llamadas para ese X-Agent-Id.
Errores: 402 con error: agent_id_quota_exceeded o 429 con error: agent_id_rate_limit_exceeded. Si van tanto X-External-User-Id como X-Agent-Id, aplican los tres límites: cuenta, usuario final y agente.

​
Headers de trazabilidad para integraciones

Para integraciones externas, envía estos headers en cada solicitud: Las solicitudes sin estos headers pueden ser rechazadas con 400 Bad Request.
Las API keys self-serve son para integraciones propias directas. La reventa multi-tenant o usar Quikly como backend oculto para clientes de terceros está restringido y puede activar suspensión de la key. Consulta Self-serve vs Partner tier para elegir el tier correcto según tu caso.
Consulta tu uso actual con:
También puedes pre-verificar antes de una operación:

​
Headers de respuesta

Cada respuesta de la API pública incluye estos headers de atribución. Los clientes pueden ignorarlos sin problema, pero son útiles para logging, debugging y probar que un dato vino efectivamente de Quikly:
Quitar o enmascarar estos headers antes de reenviar contenido generado por Quikly a usuarios finales es una violación de los Términos de Servicio §5.3.2 en planes self-serve. Las integraciones Partner pueden negociar reglas de atribución en su acuerdo.

​
Gestionar claves existentes

En Configuración → Claves de API, puedes:
  • Renombrar una clave para mantener tu lista organizada
  • Desactivar una clave temporalmente sin eliminarla
  • Revocar una clave permanentemente — las claves revocadas no se pueden reactivar

​
Mejores prácticas de seguridad

Nunca subas claves de API al control de versiones ni las expongas en código del lado del cliente.
  • Usa variables de entorno para almacenar claves en tu entorno de despliegue.
  • Rota claves periódicamente — crea una nueva clave, actualiza tus integraciones, luego revoca la anterior.
  • Usa el scope más restrictivo que tu integración requiera.
  • Establece expiración al crear claves para integraciones temporales. Puedes especificar expires_in_days durante la creación.
  • Monitorea el uso consultando el endpoint de usage o la página de Claves de API en el dashboard. Cada clave muestra su marca de tiempo del último uso.
  • Revoca inmediatamente si una clave se ve comprometida.

​
Formato de clave

Las claves de API de Quikly siguen el formato qk_ seguido de una cadena aleatoria. Cuando ves claves en el dashboard, solo el prefijo es visible (ej., qk_abc1...) — la clave completa solo se muestra al momento de crearla.