Démarrer

Authentification

Comment une clé identifie un workspace, ce qu’elle autorise et comment la protéger.

Une clé identifie un workspace et un membre, et porte la liste de ce qu’elle peut faire. Cette page décrit comment l’envoyer, ce qu’elle autorise, ses limites et comment la protéger.

Envoyer la clé#

Toutes les routes demandent la clé dans l’en-tête Authorization, sauf GET/api/v1 et GET/api/v1/openapi.json, qui sont publics :

HTTP

Authorization: Bearer piq_live_…

L’en-tête x-api-key: piq_live_… est accepté pour les clients qui ne savent pas poser Authorization.

Une clé commence par piq_live_, suivi de 38 caractères. Settings affiche les 6 premiers caractères après le préfixe pour la reconnaître. Le reste ne se réaffiche jamais.

Ce que la clé représente#

Une clé agit au nom du membre qui l’a créée, dans son workspace, avec son rôle. Les règles du dashboard s’appliquent donc à l’identique : une clé ne voit jamais un autre workspace, et elle cesse de fonctionner quand son créateur quitte le workspace.

Seuls les owners et les admins créent des clés, dans Settings → API and MCP. Un workspace compte 25 clés actives au plus.

Scopes#

Un scope ouvre une famille d’outils. Chaque outil exige les siens, indiqués dans le catalogue.

Scope	Ce qu’il ouvre
`read`	Lire le corpus et le workspace : sources, items, thèmes, signaux, entités, boards, tables, pipeline Upwork.
`explore`	Lire en direct le web, les réseaux sociaux, les registres et les archives. Consomme des crédits fournisseurs.
`write`	Écrire dans le workspace : boards, tables, entités suivies, contrats de veille, profil, brouillons Upwork.
`act`	Agir sur la veille : s’abonner à une source ou s’en désabonner, poser une règle de signal, lancer une enquête, suivre une campagne.
`agents`	Faire répondre les agents Piqline, Facebook, LinkedIn, Upwork et onboarding. Consomme des crédits modèle.

Choisissez le minimum. read suffit pour lire le corpus ; ajoutez agents pour faire répondre un agent. Un agent lancé avec votre clé n’utilise que les outils que la clé pourrait appeler elle-même.

Expiration et révocation#

Une clé peut ne jamais expirer, ou expirer dans 90 jours ou dans un an. Pour la révoquer, ouvrez Settings → API and MCP, cliquez sur Revoke puis sur Revoke key. Les appels qui l’utilisent reçoivent un 401 en moins d’une minute.

Limites#

Limite par clé	Valeur par défaut	Au dépassement
Requêtes par minute	120	429 `rate_limited`, avec `Retry-After`
Tours d’agent par minute	10	429 `rate_limited`, avec `Retry-After`
Requêtes par jour	20 000	429 `quota_exceeded`

Chaque réponse porte RateLimit-Limit (la rafale autorisée par minute) et RateLimit-Remaining (ce qu’il reste). La limite par minute freine les rafales : elle s’applique par instance du serveur et peut laisser passer un peu plus que la valeur indiquée. GET/api/v1/workspace renvoie les limites de la clé et le nombre de requêtes du jour.

Usage et historique#

Settings → API and MCP montre l’usage des 30 derniers jours par outil et par agent, et l’historique de chaque requête : heure, opération, statut, durée, erreur, extrait de l’entrée, client et réseau d’origine. L’historique garde 30 jours.

Il ne contient ni la clé ni le corps complet des requêtes : l’extrait d’entrée est tronqué à 300 caractères, les champs qui ressemblent à des secrets (mot de passe, token, clé) sont masqués, et seul le préfixe du réseau (/24 en IPv4, /48 en IPv6) est conservé, sans l’adresse IP complète.

Protéger une clé#

Rangez-la dans un gestionnaire de secrets ou une variable d’environnement. Jamais dans un dépôt, une page web ou une application mobile.
Créez une clé par usage (un script, un agent, un collègue) et nommez-la pour la reconnaître : vous révoquez l’une sans toucher aux autres.
Donnez une expiration aux clés de test.
Révoquez tout de suite une clé exposée. Piqline ne garde que son empreinte : il ne peut pas vous la redonner, seulement en créer une nouvelle.
Une clé garde les droits de son créateur et s’arrête s’il quitte l’équipe. Pour un usage durable, créez-la depuis un compte dédié à l’intégration.