API reference · /api/v1

Authentication

Every request carries your API key ID and an HMAC-SHA256 signature made with your API secret. The secret itself is never sent. Credentials belong on secure server-side systems only.

Headers

X-DomainAf-Key: Your API key ID
X-DomainAf-Timestamp: Unix time of the request (must be within 5 minutes)
X-DomainAf-Nonce: A random value, 16–128 characters [A-Za-z0-9_-], never reused
X-DomainAf-Signature: hex HMAC-SHA256 of the string to sign, keyed with your API secret
 Accept: application/json
Content-Type: application/json

Signing a request

string_to_sign = METHOD + "\n" + PATH + "\n" + QUERY + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + hex(sha256(BODY))
signature      = hex(hmac_sha256(string_to_sign, API_SECRET))

• METHOD upper case; PATH as requested, e.g. /api/v1/domains/register; QUERY the raw query string without ? (empty if none); BODY the exact bytes sent (empty for GET).
• The timestamp must be within 5 minutes of server time, and each nonce is accepted once.

$ts = (string) time();
$nonce = bin2hex(random_bytes(16));
$body = json_encode(['domains' => ['example.af']]);
$sig = hash_hmac('sha256', "POST\n/api/v1/domains/availability\n\n$ts\n$nonce\n".hash('sha256', $body), $secret);

Idempotency

Billable calls (register, renew, transfer, buying WHOIS Privacy or Domain Protection) require an Idempotency-Key header (16–128 characters). Retrying with the same key and body returns the original response with Idempotent-Replayed: true and never charges again. Reusing a key for a different body returns 422 idempotency_conflict.

Permissions

Each key can be limited to scopes: account.read, domains.read, domains.register, domains.renew, domains.transfer, domains.manage, dns.manage, privacy.manage, protection.manage.

Credential lifecycle

• Generate credentials in the reseller portal after API access is enabled
• Copy the secret immediately — it is shown once
• Optionally restrict the credential to IP addresses or CIDR ranges
• Rotate or revoke credentials if they are compromised
• Never commit secrets to Git or ship them to browsers

Older keys

The read and DNS endpoints also accept X-DomainAf-Key + X-DomainAf-Secret headers for existing integrations. Registration and management endpoints require signed requests; keys created before request signing must be regenerated to sign.