API-Schlüssel erzeugen
Erzeugt einen API-Schlüssel.
POST/v1/workspaces/{regionId}/api-keys
Body
labelstringPflichtLesbare Bezeichnung, z. B. "Billing agent - prod".
procurementRole"administrator" | "read-only" | "contracts-and-suppliers" | "relationships" | "requisitions" | "finance"Nur Käuferschlüssel (bei einem Lieferantenschlüssel ignoriert): was der Schlüssel darf, nach denselben Einkaufsrollen, die Personen haben. Standardmäßig nur lesend. So kann requisitions zum Beispiel Bestellungen anlegen und bearbeiten, und finance kann Rechnungen bearbeiten. Unabhängig von der Rolle gibt ein Schlüssel nie frei, lehnt nie ab, erfasst nie eine Zahlung (außer über RecordPayments mit dem Scope payments:record) und ändert nie Freigabeabläufe, Autonomie- oder Automatisierungsregeln.
scopesArray<"invoices:feed" | "payments:record">Nur von einem Administrator, jeweils für eine Seite. invoices:feed (Lieferantenschlüssel) erlaubt dem Schlüssel, Rechnungen über SubmitFeedInvoice einzureichen; payments:record (Käuferschlüssel) erlaubt ihm, Zahlungen über RecordPayments zu erfassen. Für einen Schlüssel ohne Scopes weglassen.
Rückgabe
201 Created mit dem in der Antwort gezeigten Objekt.
Weitere Details
Erzeugt einen neuen API-Schlüssel, der auf die eigene Rolle des Aufrufers in diesem Workspace beschränkt ist - ein Lieferant kann keinen Schlüssel mit Käuferrolle erzeugen und umgekehrt. Der Klartextschlüssel wird nur in dieser Antwort zurückgegeben; gespeichert wird nur sein HMAC-Digest. Nur ein Administrator kann einen Schlüssel erzeugen: Auf Käuferseite erhalten alle anderen 403 ("Only an administrator of this workspace can manage its API keys."), auf Lieferantenseite 403 ("Only a supplier administrator can create API keys for this workspace."). Ein Käuferschlüssel handelt mit der procurementRole, mit der er erzeugt wurde, standardmäßig nur lesend. Ein Lieferantenadministrator kann den Scope invoices:feed hinzufügen, mit dem der Schlüssel zusätzlich zu allem, was ein Lieferantenschlüssel ohnehin kann, SubmitFeedInvoice aufrufen darf; ein Käuferadministrator kann den Scope payments:record hinzufügen, mit dem der Schlüssel RecordPayments aufrufen darf und der eine procurementRole braucht, die Rechnungen bearbeiten kann (sonst 400 API_KEY_SCOPE_ROLE_MISMATCH). Ein Nicht-Administrator, der einen Scope anfordert, erhält 403 API_KEY_SCOPE_FORBIDDEN, und der Scope der anderen Seite ergibt 400 API_KEY_SCOPE_INVALID.
Erfordert eine Cognito-Sitzung einer Person (Bearer-Token) - ein vorhandener API-Schlüssel kann nie einen weiteren Schlüssel erzeugen oder widerrufen. Nur ein Administrator des Workspace kann dessen Schlüssel erzeugen, auflisten oder widerrufen.
Antwortfelder
apiKeystringDie Zugangsdaten im Klartext, im Format "<keyId>.<secret>" - übergeben Sie sie unverändert im Header X-Api-Key. Werden nur einmal angezeigt; sie können nicht erneut abgerufen werden.
Fehler
- 403 Forbidden - Der Aufrufer hat sich mit einem API-Schlüssel statt mit dem Bearer-Token einer Person authentifiziert ("This action requires a logged-in user session, not an API key") oder ist, bei Aufrufern mit Lieferantenrolle, kein Lieferantenadministrator dieses Workspace ("Only a supplier administrator can create API keys for this workspace.").
- 403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.
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
}