Crear clave de API
Crea una clave de API.
POST/v1/workspaces/{regionId}/api-keys
Cuerpo
labelstringObligatorioEtiqueta legible, p. ej. "Agente de facturación - prod".
procurementRole"administrator" | "read-only" | "contracts-and-suppliers" | "relationships" | "requisitions" | "finance"Solo claves de comprador (se ignora para una clave de proveedor): qué puede hacer la clave, con los mismos roles de compras que tienen las personas. Por defecto, read-only. Por ejemplo, requisitions puede crear y editar órdenes de compra, y finance puede trabajar con facturas. Sea cual sea el rol, una clave nunca aprueba, rechaza, registra un pago (salvo mediante RecordPayments, con el ámbito payments:record) ni cambia flujos de aprobación, autonomía ni reglas de automatización.
scopesArray<"invoices:feed" | "payments:record">Solo de un administrador, cada uno para un lado. invoices:feed (claves de proveedor) permite a la clave enviar facturas mediante SubmitFeedInvoice; payments:record (claves de comprador) le permite registrar pagos mediante RecordPayments. Omítelo para una clave sin ámbitos.
Devuelve
201 Created con el objeto que se muestra en la respuesta.
Más detalles
Crea una nueva clave de API limitada al propio rol del llamador en este espacio de trabajo: un proveedor no puede crear una clave de comprador, ni al revés. La clave en texto plano solo se devuelve en esta respuesta; solo se guarda su resumen HMAC. Solo un administrador puede crear una clave: en el lado del comprador, cualquier otra persona recibe 403 ("Only an administrator of this workspace can manage its API keys."), y en el lado del proveedor, 403 ("Only a supplier administrator can create API keys for this workspace."). Una clave de comprador actúa con el procurementRole con el que se creó, read-only salvo que elijas otro. Un administrador de proveedor puede agregar el ámbito invoices:feed, que permite a la clave llamar a SubmitFeedInvoice además de todo lo que ya hace una clave de proveedor; un administrador de comprador puede agregar el ámbito payments:record, que permite a la clave llamar a RecordPayments y requiere un procurementRole que pueda editar facturas (si no, 400 API_KEY_SCOPE_ROLE_MISMATCH). Quien no es administrador y pide un ámbito recibe 403 API_KEY_SCOPE_FORBIDDEN, y el ámbito del otro lado da 400 API_KEY_SCOPE_INVALID.
Requiere una sesión humana de Cognito (token Bearer): una clave de API existente nunca puede crear ni revocar otra clave. Solo un administrador del espacio de trabajo puede crear, listar o revocar sus claves.
Campos de la respuesta
apiKeystringLa credencial en texto plano, con el formato "<keyId>.<secret>": pásala tal cual en el encabezado X-Api-Key. Solo se muestra una vez; no se puede volver a obtener.
Errores
- 403 Forbidden - El llamador se autenticó con una clave de API en lugar de un token Bearer humano ("This action requires a logged-in user session, not an API key") o, en el caso de llamadores proveedores, no es administrador de proveedor de este espacio de trabajo ("Only a supplier administrator can create API keys for this workspace.").
- 403 Forbidden - El token Bearer o la clave de API del llamador no da acceso a este espacio de trabajo (regionId), o no tiene el rol requerido.
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
}