Skip to content

Knowledgebase

Create a dedicated API application and issue its first HMAC key

domain-nexus, development

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.

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
  1. Authenticate with an identity authorised to manage API applications.
  2. POST an application with a descriptive name, such as Customer domain dashboard. Use the appropriate client_type and permitted rate-limit profile where needed.
  3. Store the returned application public ID as clientId.
  4. 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.
  5. Capture the returned key ID and secret once in approved secret storage. Use them together for the HMAC signing method.
  6. 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:

Structured data example
{
  "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.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support