# Autenticación

> Cómo una clave identifica un workspace, qué permite y cómo protegerla.

Source: https://piqline.com/es/docs/api/authentication

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](/settings/api). 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](/es/docs/api/tools#catalogo).

| 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](/settings/api), 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.
