# Authentification

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

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

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](/settings/api). 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](/fr/docs/api/tools#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 du workspace. |
| `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, Requête, Facebook, LinkedIn, Upwork et onboarding. Consomme des crédits du workspace. |

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