Per iniziare
Autenticazione
Come una chiave identifica un workspace, che cosa consente e come proteggerla.
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:
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. 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.
| 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, 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.