Client API Reference

• Authentication
• Response format
• Domains
• Pricing
• Domain actions
• Invoices
• Sub-accounts
• API keys
• Rate limits
• Health check

Authentication

There are two ways to authenticate. Which one you use depends on what you're building.

You don't need both. A couple of endpoints — managing sub-accounts, managing your own API keys — are portal-login only; noted where relevant.

Getting an API key

1. Log in to this portal, then go to Account.
2. Create a new key, giving it a label and at least one allowed IP address or CIDR range (e.g. 203.0.113.4 or 203.0.113.0/24).
3. Copy the key immediately — it's shown exactly once and cannot be retrieved again. If you lose it, revoke it and create a new one.
4. Requests from any IP not in that key's allowlist are rejected, even with a valid key. There is no "allow from anywhere" option — this is by design.

Send it as a bearer token on every request:

Session login

Login is two steps, because the email on an account can be shared across more than one of your organization's client records — for example, if you manage several accounts from one inbox. Step 1 tells you which account(s) that email belongs to; step 2 verifies the password for the one you pick.

Exactly one account? Skip straight to step 2. More than one? Show a picker using client_display_name before asking for a password.

Use token as a bearer token on every subsequent request. Watch for 401 UNAUTHORIZED as the signal to log in again.

Response format

Every response uses the same envelope:

On failure:

request_id is worth logging on your end — quote it if you ever report an issue, it lets us trace the exact request server-side.

Common error codes

Data isolation

Every endpoint below only ever returns or affects data belonging to your own account. Passing another account's ID anywhere returns 404 NOT_FOUND, the same as if it didn't exist. This is enforced on every request server-side, not just hidden in the portal UI.

Domains

Lists every domain on your account.

A single domain, including its owner/admin/tech contacts.

Pricing

Resolves the price for a given TLD + action (+ period, for period-based actions like registration/renewal/transfer). Reflects any account-specific pricing you have — this is the price you'd actually be charged.

Returns 404 PRICE_NOT_FOUND if that TLD/action combination isn't orderable for your account.

Domain actions

The way you request anything to actually happen to a domain — a renewal, a DNS change, an ownership transfer, and so on.

Registering a brand-new domain? Omit domain_id and pass tld and domain_name instead — the domain is created as part of the request.

What happens next

• Free (price_amount: "0.00") — dispatched immediately; status is sent_to_supplier (or pending with a warning if dispatch needs a retry on our end — not something you need to act on).
• Paid — queued onto an open order; the response includes order_id. The action stays pending until the resulting invoice is paid, then dispatches automatically.

Lists actions requested on a specific domain. domain_id is required — this endpoint always scopes to one domain.

Invoices

List / fetch a single invoice, including its line items.

Decode content_base64 to get the raw PDF file bytes.

Sub-accounts portal login only

Lets an account owner create and manage additional logins under the same account — separate billing/tech contacts, each with their own credentials. Requires a portal session with the owner role; not available via API key.

API keys portal login only

Self-service management of your own API keys, including the one you're currently using — also portal-login only, so a compromised key can never mint another key or widen its own access.

Returns the raw key once, in the response — save it now.

Rate limits

Exceeding either returns 429 RATE_LIMITED. Build in a backoff/retry — repeatedly retrying immediately will just keep tripping the limit.

Health check

Returns {"status":"ok"} — useful for your own monitoring, doesn't touch anything else.