Create a separate API application for each custom integration so its purpose, credentials and rotation can be managed independently. An application record identifies the consumer. It does not itself contain a newly issued HMAC secret, so key creation is a second explicit operation.
IN THIS ARTICLE
01 Create the application and key
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
POST |
/v2/api-clients |
keys:write |
Required |
POST |
/v2/api-clients/{clientId}/keys |
keys:write |
Required |
GET |
/v2/api-clients/{clientId} |
keys:read |
Not required by this route |
- Authenticate with an identity authorised to manage API applications.
- POST an application with a descriptive
name, such asCustomer domain dashboard. Use the appropriateclient_typeand permitted rate-limit profile where needed. - Store the returned application public ID as
clientId. - POST to that application's keys resource with a non-empty list of permitted scopes. Add an IP/CIDR allowlist and expiry when appropriate for the deployment.
- Capture the returned key ID and secret once in approved secret storage. Use them together for the HMAC signing method.
- Test a read endpoint allowed by the new scope set from the real web or worker environment.
A minimal read-oriented key request might contain:
{
"scopes": ["profile:read", "domains:read"],
"networks": ["192.0.2.10/32"]
}
The example address is documentation data. Replace it with the integration's actual authorised egress address before using a network restriction. The caller must be allowed to delegate every requested scope.
Why does reading the application not show its secret?
Application reads expose metadata. Secret material is revealed during issuance, and redacted reads or an idempotency replay may not reveal it again. Treat the initial response as a secure credential handover, not ordinary debug output.
What should happen if key issuance is uncertain?
Keep the original idempotency key and request evidence. Inspect the application and authorised key-management state rather than creating untracked keys repeatedly. If a replacement is required, record it and revoke unused credentials through the supported workflow. Store the application ID alongside its consuming installation so future rotation affects the correct integration.