Saltar al contenido

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:

HTTP
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.

ScopeQué abre
readLeer el corpus y el workspace: fuentes, elementos, temas, señales, entidades, tableros, tablas, pipeline de Upwork.
exploreLeer en directo la web, las redes sociales, los registros y los archivos. Consume créditos del workspace.
writeEscribir en el workspace: tableros, tablas, entidades seguidas, contratos de vigilancia, perfil, borradores de Upwork.
actActuar 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.
agentsHacer 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 claveValor por defectoAl superarlo
Peticiones por minuto120429 rate_limited, con Retry-After
Turnos de agente por minuto10429 rate_limited, con Retry-After
Peticiones por día20.000429 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.

¿Tienes una pregunta sobre la API o has encontrado un error en esta página? Escríbenos.