Creare una chiave API
Crea una chiave API.
POST/v1/workspaces/{regionId}/api-keys
Corpo
labelstringObbligatorioEtichetta leggibile, ad es. "Billing agent - prod".
procurementRole"administrator" | "read-only" | "contracts-and-suppliers" | "relationships" | "requisitions" | "finance"Solo chiavi acquirente (ignorato per una chiave fornitore): cosa può fare la chiave, con gli stessi ruoli procurement delle persone. Valore predefinito: read-only. Ad esempio, requisitions può creare e modificare ordini d’acquisto, e finance può gestire le fatture. Qualunque sia il ruolo, una chiave non approva, non rifiuta, non registra un pagamento (se non tramite RecordPayments, con l’ambito payments:record) e non modifica i flussi di approvazione, l’autonomia o le regole di automazione.
scopesArray<"invoices:feed" | "payments:record">Solo da un amministratore, ciascuno per una parte. invoices:feed (chiavi fornitore) permette alla chiave di inviare fatture tramite SubmitFeedInvoice; payments:record (chiavi acquirente) le permette di registrare pagamenti tramite RecordPayments. Omettilo per una chiave senza ambiti.
Restituisce
201 Created con l’oggetto mostrato nella risposta.
Più dettagli
Genera una nuova chiave API limitata al ruolo del chiamante in questo workspace: un fornitore non può generare una chiave con ambito acquirente, e viceversa. La chiave in chiaro viene restituita solo in questa risposta; viene memorizzato solo il suo digest HMAC. Solo un amministratore può generare una chiave: sul lato Acquirente chiunque altro riceve 403 ("Only an administrator of this workspace can manage its API keys."), e sul lato Fornitore 403 ("Only a supplier administrator can create API keys for this workspace."). Una chiave acquirente agisce con il procurementRole con cui è stata generata, read-only se non ne scegli un altro. Un amministratore fornitore può aggiungere l’ambito invoices:feed, che permette alla chiave di chiamare SubmitFeedInvoice oltre a tutto ciò che una chiave fornitore già fa; un amministratore acquirente può aggiungere l’ambito payments:record, che permette alla chiave di chiamare RecordPayments e richiede un procurementRole che possa modificare le fatture (altrimenti 400 API_KEY_SCOPE_ROLE_MISMATCH). Un non amministratore che chiede un ambito riceve 403 API_KEY_SCOPE_FORBIDDEN, e l’ambito dell’altra parte restituisce 400 API_KEY_SCOPE_INVALID.
Richiede una sessione Cognito di una persona (token Bearer): una chiave API esistente non può mai generare o revocare un’altra chiave. Solo un amministratore del workspace può generare, elencare o revocare le sue chiavi.
Campi della risposta
apiKeystringLa credenziale in chiaro, nel formato "<keyId>.<secret>": passala così com’è come header X-Api-Key. Mostrata una sola volta; non può essere recuperata di nuovo.
Errori
- 403 Forbidden - Il chiamante si è autenticato con una chiave API invece che con un token Bearer di una persona ("This action requires a logged-in user session, not an API key"), oppure, per i chiamanti Fornitore, non è un amministratore fornitore di questo workspace ("Only a supplier administrator can create API keys for this workspace.").
- 403 Forbidden - Il token Bearer o la chiave API del chiamante non dà accesso a questo workspace (regionId), oppure non ha il ruolo richiesto.
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
}