Empezar
Autenticación
Cómo una clave identifica un workspace, qué permite y cómo protegerla.
Una clave identifica un workspace y un miembro, y lleva la lista de lo que puede hacer. Esta página explica cómo enviarla, qué permite, sus límites y cómo protegerla.
Enviar la clave#
Todas las rutas esperan la clave en la cabecera Authorization, salvo GET/api/v1 y GET/api/v1/openapi.json, que son públicas:
Authorization: Bearer piq_live_…La cabecera x-api-key: piq_live_… se acepta para los clientes que no pueden definir Authorization.
Una clave empieza por piq_live_, seguido de 38 caracteres. Ajustes muestra los 6 primeros caracteres después del prefijo para que puedas reconocerla. El resto no se vuelve a mostrar.
Qué representa una clave#
Una clave actúa en nombre del miembro que la creó, en su workspace y con su rol. Las reglas del panel se aplican sin cambios: una clave nunca ve otro workspace y deja de funcionar cuando su creador abandona el workspace.
Solo los propietarios (owner) y administradores (admin) crean claves, en Ajustes → API y MCP. Un workspace admite como máximo 25 claves activas.
Scopes#
Un scope abre una familia de herramientas. Cada herramienta exige el suyo, indicado en el catálogo.
| Scope | Qué abre |
|---|---|
read | Leer el corpus y el workspace: fuentes, elementos, temas, señales, entidades, tableros, tablas, pipeline de Upwork. |
explore | Leer en directo la web, las redes sociales, los registros y los archivos. Consume créditos del workspace. |
write | Escribir en el workspace: tableros, tablas, entidades seguidas, contratos de vigilancia, perfil, borradores de Upwork. |
act | Actuar sobre la vigilancia: suscribirse a una fuente o cancelar la suscripción, definir una regla de señal, iniciar una investigación, seguir una campaña. |
agents | Hacer que respondan los agentes Piqline, Requête, Facebook, LinkedIn, Upwork y onboarding. Consume créditos del workspace. |
Elige el mínimo. read basta para leer el corpus; añade agents para que un agente responda. Un agente ejecutado con tu clave solo usa las herramientas que la clave podría llamar por sí misma.
Caducidad y revocación#
Una clave puede no caducar nunca, o caducar a los 90 días o al cabo de un año. Para revocarla, abre Ajustes → API y MCP, haz clic en Revocar y luego en Revocar clave. Las llamadas que la usen reciben un 401 en menos de un minuto.
Límites#
| Límite por clave | Valor por defecto | Al superarlo |
|---|---|---|
| Peticiones por minuto | 120 | 429 rate_limited, con Retry-After |
| Turnos de agente por minuto | 10 | 429 rate_limited, con Retry-After |
| Peticiones por día | 20.000 | 429 quota_exceeded |
Cada respuesta incluye RateLimit-Limit (la ráfaga permitida por minuto) y RateLimit-Remaining (lo que queda). El límite por minuto frena las ráfagas: se aplica por instancia de servidor y puede dejar pasar algo más que el valor indicado. GET/api/v1/workspace devuelve los límites de la clave y el número de peticiones realizadas hoy.
Uso e historial#
Ajustes → API y MCP muestra los últimos 30 días de uso por herramienta y por agente, y el historial de cada petición: hora, operación, estado, duración, error, extracto de la entrada, cliente y red de origen. El historial se conserva 30 días.
No contiene la clave ni el cuerpo completo de la petición: el extracto de la entrada se corta a 300 caracteres, los campos que parecen secretos (password, token, key) se enmascaran y solo se conserva el prefijo de red (/24 en IPv4, /48 en IPv6), nunca la dirección IP completa.
Proteger una clave#
- Guárdala en un gestor de secretos o en una variable de entorno. Nunca en un repositorio, una página web o una aplicación móvil.
- Crea una clave por uso (un script, un agente, un compañero) y dale un nombre que reconozcas: podrás revocar una sin tocar las demás.
- Asigna una caducidad a las claves de prueba.
- Revoca de inmediato una clave expuesta. Piqline solo conserva su huella: no puede devolverte la clave, solo crear una nueva.
- Una clave conserva los permisos de su creador y se detiene si este abandona el equipo. Para un uso duradero, créala desde una cuenta dedicada a la integración.