Créer une clé API
Crée une clé API.
POST/v1/workspaces/{regionId}/api-keys
Corps
labelstringObligatoireLibellé lisible, par exemple "Billing agent - prod".
procurementRole"administrator" | "read-only" | "contracts-and-suppliers" | "relationships" | "requisitions" | "finance"Clés acheteur uniquement (ignoré pour une clé fournisseur) : ce que la clé peut faire, selon les mêmes rôles achats que les personnes. Lecture seule par défaut. Par exemple, requisitions peut créer et modifier des bons de commande, et finance peut traiter les factures. Quel que soit le rôle, une clé ne valide jamais, ne rejette jamais, n’enregistre jamais de paiement (sauf via RecordPayments, avec le scope payments:record), et ne modifie jamais les circuits de validation, l’autonomie ni les règles d’automatisation.
scopesArray<"invoices:feed" | "payments:record">Uniquement par un administrateur, chacun pour un côté. invoices:feed (clés fournisseur) permet à la clé de soumettre des factures via SubmitFeedInvoice ; payments:record (clés acheteur) lui permet d’enregistrer des paiements via RecordPayments. Omettez-le pour une clé sans scope.
Retour
201 Created avec l’objet présenté dans la réponse.
Plus de détails
Génère une nouvelle clé API limitée au rôle de l’appelant dans cet espace de travail - un fournisseur ne peut pas générer de clé acheteur, et inversement. La clé en clair n’est renvoyée que dans cette réponse ; seule son empreinte HMAC est conservée. Seul un administrateur peut générer une clé : côté acheteur, toute autre personne reçoit 403 (« Only an administrator of this workspace can manage its API keys. »), et côté fournisseur 403 (« Only a supplier administrator can create API keys for this workspace. »). Une clé acheteur agit avec le procurementRole avec lequel elle est générée, en lecture seule sauf si vous en choisissez un autre. Un administrateur fournisseur peut ajouter le scope invoices:feed, qui permet à la clé d’appeler SubmitFeedInvoice en plus de tout ce que fait déjà une clé fournisseur ; un administrateur acheteur peut ajouter le scope payments:record, qui permet à la clé d’appeler RecordPayments et exige un procurementRole autorisé à modifier les factures (sinon 400 API_KEY_SCOPE_ROLE_MISMATCH). Un non-administrateur qui demande un scope reçoit 403 API_KEY_SCOPE_FORBIDDEN, et le scope de l’autre côté donne 400 API_KEY_SCOPE_INVALID.
Nécessite une session Cognito humaine (jeton Bearer) : une clé API existante ne peut jamais générer ni révoquer une autre clé. Seul un administrateur de l’espace de travail peut générer, lister ou révoquer ses clés.
Champs de la réponse
apiKeystringL’identifiant en clair, au format "<keyId>.<secret>" : transmettez-le tel quel dans l’en-tête X-Api-Key. Affiché une seule fois ; il ne peut pas être récupéré ensuite.
Erreurs
- 403 Forbidden - L’appelant s’est authentifié avec une clé API plutôt qu’avec un jeton Bearer humain (« This action requires a logged-in user session, not an API key ») ou, pour les appelants fournisseurs, n’est pas administrateur fournisseur de cet espace de travail (« Only a supplier administrator can create API keys for this workspace. »).
- 403 Forbidden - Le jeton Bearer ou la clé API de l’appelant ne donne pas accès à cet espace de travail (regionId), ou n’a pas le rôle requis.
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.supplier/api-keys" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "label": "Billing agent - prod" }'{
"apiKey": "5b1c2e90-....-9a3f.9f2c7a1e8b6d4c0a2f1e3d5b7a9c8e6f",
"keyId": "5b1c2e90-....-9a3f",
"regionId": "reg_01k5x8p9j3q7vn2mhb4tzc6rde",
"role": "supplier",
"label": "Billing agent - prod",
"createdAt": "2026-02-03T09:00:00.000Z",
"revoked": false
}