# Autenticazione

> Come una chiave identifica un workspace, che cosa consente e come proteggerla.

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

Una chiave identifica un workspace e un membro, e porta l'elenco di ciò che può fare. Questa pagina spiega come inviarla, che cosa consente, quali sono i suoi limiti e come proteggerla.

## Inviare la chiave

Ogni route si aspetta la chiave nell'header `Authorization`, tranne `GET /api/v1` e `GET /api/v1/openapi.json`, che sono pubblici:

```http
Authorization: Bearer piq_live_…
```

L'header `x-api-key: piq_live_…` è accettato per i client che non possono impostare `Authorization`.

Una chiave inizia con `piq_live_`, seguito da 38 caratteri. Le impostazioni mostrano i primi 6 caratteri dopo il prefisso, così puoi riconoscerla. Il resto non viene più mostrato.

## Che cosa rappresenta una chiave

Una chiave agisce a nome del membro che l'ha creata, nel suo workspace, con il suo ruolo. Le regole della dashboard si applicano senza modifiche: una chiave non vede mai un altro workspace e smette di funzionare quando il suo creatore lascia il workspace.

Solo owner e admin creano le chiavi, in [Impostazioni → API e MCP](/settings/api). Un workspace può avere al massimo 25 chiavi attive.

## Scope

Uno scope apre una famiglia di tool. Ogni tool richiede il proprio, indicato nel [catalogo](/it/docs/api/tools#catalogo).

| Scope | Che cosa apre |
| --- | --- |
| `read` | Leggere il corpus e il workspace: fonti, elementi, argomenti, segnali, entità, board, tabelle, pipeline Upwork. |
| `explore` | Leggere in diretta il web, i social network, i registri e gli archivi. Consuma crediti del workspace. |
| `write` | Scrivere nel workspace: board, tabelle, entità seguite, contratti di monitoraggio, profilo, bozze Upwork. |
| `act` | Agire sul monitoraggio: iscriversi a una fonte o annullare l'iscrizione, impostare una regola di segnale, avviare un'indagine, seguire una campagna. |
| `agents` | Far rispondere gli agenti Piqline, Requête, Facebook, LinkedIn, Upwork e onboarding. Consuma crediti del workspace. |

Scegli il minimo. `read` basta per leggere il corpus; aggiungi `agents` perché un agente risponda. Un agente eseguito con la tua chiave usa solo i tool che la chiave potrebbe chiamare direttamente.

## Scadenza e revoca

Una chiave può non scadere mai, oppure scadere dopo 90 giorni o dopo un anno. Per revocarla, apri [Impostazioni → API e MCP](/settings/api), clicca su **Revoca**, poi su **Revoca chiave**. Le chiamate che la usano ricevono un `401` entro un minuto.

## Limiti

| Limite per chiave | Valore predefinito | In caso di superamento |
| --- | --- | --- |
| Richieste al minuto | 120 | 429 `rate_limited`, con `Retry-After` |
| Turni di agente al minuto | 10 | 429 `rate_limited`, con `Retry-After` |
| Richieste al giorno | 20.000 | 429 `quota_exceeded` |

Ogni risposta contiene `RateLimit-Limit` (la raffica consentita al minuto) e `RateLimit-Remaining` (ciò che resta). Il limite al minuto rallenta le raffiche: si applica per istanza del server e può lasciar passare qualcosa in più del valore indicato. `GET /api/v1/workspace` restituisce i limiti della chiave e il numero di richieste effettuate oggi.

## Utilizzo e cronologia

Impostazioni → API e MCP mostra gli ultimi 30 giorni di utilizzo per tool e per agente, e la cronologia di ogni richiesta: ora, operazione, stato, durata, errore, estratto dell'input, client e rete di origine. La cronologia viene conservata per 30 giorni.

Non contiene né la chiave né il corpo completo della richiesta: l'estratto dell'input è troncato a 300 caratteri, i campi che sembrano segreti (password, token, chiave) sono mascherati e viene conservato solo il prefisso di rete (/24 per IPv4, /48 per IPv6), mai l'indirizzo IP completo.

## Proteggere una chiave

- Conservala in un gestore di segreti o in una variabile d'ambiente. Mai in un repository, in una pagina web o in un'app mobile.
- Crea una chiave per ogni uso (uno script, un agente, un collega) e dalle un nome che riconoscerai: potrai revocarne una senza toccare le altre.
- Dai alle chiavi di test una scadenza.
- Revoca subito una chiave esposta. Piqline conserva solo la sua impronta: non può restituirtela, può solo crearne una nuova.
- Una chiave mantiene i diritti del suo creatore e si ferma se questi lascia il team. Per un uso duraturo, creala da un account dedicato all'integrazione.
