Vai al contenuto

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:

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

ScopeChe cosa apre
readLeggere il corpus e il workspace: fonti, elementi, argomenti, segnali, entità, board, tabelle, pipeline Upwork.
exploreLeggere in diretta il web, i social network, i registri e gli archivi. Consuma crediti del workspace.
writeScrivere nel workspace: board, tabelle, entità seguite, contratti di monitoraggio, profilo, bozze Upwork.
actAgire sul monitoraggio: iscriversi a una fonte o annullare l'iscrizione, impostare una regola di segnale, avviare un'indagine, seguire una campagna.
agentsFar 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 chiaveValore predefinitoIn caso di superamento
Richieste al minuto120429 rate_limited, con Retry-After
Turni di agente al minuto10429 rate_limited, con Retry-After
Richieste al giorno20.000429 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.

Una domanda sull'API, o un errore in questa pagina? Scrivici.