Criar chave de API
Cria uma chave de API.
POST/v1/workspaces/{regionId}/api-keys
Corpo
labelstringObrigatórioRótulo legível, por exemplo "Billing agent - prod".
procurementRole"administrator" | "read-only" | "contracts-and-suppliers" | "relationships" | "requisitions" | "finance"Só para chaves de comprador (ignorado para uma chave de fornecedor): o que a chave pode fazer, pelas mesmas funções de compras que as pessoas têm. O padrão é read-only. Por exemplo, requisitions pode criar e editar pedidos de compra, e finance pode trabalhar com faturas. Qualquer que seja a função, uma chave nunca aprova, rejeita, registra pagamento (exceto por RecordPayments, com o escopo payments:record) nem altera fluxos de aprovação, autonomia ou regras de automação.
scopesArray<"invoices:feed" | "payments:record">Só por um administrador, cada um para um lado. invoices:feed (chaves de fornecedor) permite à chave enviar faturas por SubmitFeedInvoice; payments:record (chaves de comprador) permite registrar pagamentos por RecordPayments. Omita para uma chave sem escopos.
Retorna
201 Created com o objeto mostrado na resposta.
Mais detalhes
Cria uma nova chave de API com o escopo da própria função de quem chama neste espaço de trabalho - um fornecedor não pode criar uma chave com escopo de comprador, e vice-versa. A chave em texto simples é retornada só nesta resposta; só o digest HMAC dela é armazenado. Só um administrador pode criar uma chave: do lado Comprador, qualquer outra pessoa recebe 403 ("Only an administrator of this workspace can manage its API keys."), e do lado Fornecedor, 403 ("Only a supplier administrator can create API keys for this workspace."). Uma chave de comprador age com a procurementRole com que foi criada, read-only a menos que você escolha outra. Um administrador de fornecedor pode adicionar o escopo invoices:feed, que permite à chave chamar SubmitFeedInvoice além de tudo o que uma chave de fornecedor já faz; um administrador de comprador pode adicionar o escopo payments:record, que permite à chave chamar RecordPayments e exige uma procurementRole que possa editar faturas (caso contrário, 400 API_KEY_SCOPE_ROLE_MISMATCH). Quem não é administrador e pede um escopo recebe 403 API_KEY_SCOPE_FORBIDDEN, e o escopo do outro lado é 400 API_KEY_SCOPE_INVALID.
Exige uma sessão humana do Cognito (token Bearer) - uma chave de API existente nunca pode gerar nem revogar outra chave. Só um administrador do espaço de trabalho pode gerar, listar ou revogar as chaves dele.
Campos da resposta
apiKeystringA credencial em texto simples, no formato "<keyId>.<secret>" - passe-a literalmente no cabeçalho X-Api-Key. Exibida uma única vez; não pode ser recuperada depois.
Erros
- 403 Forbidden - Quem chama se autenticou com uma chave de API em vez de um token Bearer humano ("This action requires a logged-in user session, not an API key") ou, no caso de quem chama como Fornecedor, não é administrador de fornecedor deste espaço de trabalho ("Only a supplier administrator can create API keys for this workspace.").
- 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
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
}