DNSimple Registrar

Getting started

1. Obtain an OAuth 2.1 bearer token (see Authentication).
2. Identify your tenant ID and pick a TLD association.
3. Use the endpoints below. Every request carries the bearer token as Authorization: Bearer <token>.

Authentication

The server implements OAuth 2.1 with PKCE, refresh-token rotation with reuse detection, and unauthenticated Dynamic Client Registration.

Discovery

GET /.well-known/oauth-authorization-server

Authorize (interactive, with PKCE)

GET /oauth/authorize

Token exchange & refresh

POST /oauth/token

Token introspection

POST /oauth/introspect

Revocation

POST /oauth/revoke

Register a client (DCR, unauthenticated)

POST /oauth/register

Capability areas

All tenant-scoped endpoints are rooted at /api/v1/tenants/:tenant_id/.

Domains

• POST /domains/check — availability check
• POST /domains — register (ICANN TLDs require a quote and an agreement acceptance block)
• GET /domains — list the tenant's domains
• GET /domains/:name — show a single domain
• POST /domains/:name/renew — renew for a supplied number of years
• POST /domains/:name/update_nameservers — replace the nameserver set (external names auto-provision as host rows)
• POST /domains/:name/update_ds_records — replace the DNSSEC DS record set (full-replacement semantics bridged onto EPP secDNS-1.1 deltas)
• DELETE /domains/:name/ds_records — clear all DS records
• POST /domains/:name/update_contacts — assign admin / tech / billing contacts
• POST /domains/:name/transfer_in — initiate an inbound transfer
• POST /domains/:name/approve_transfer_out — approve a pending outbound transfer
• POST /domains/:name/reject_transfer_out — reject a pending outbound transfer
• POST /domains/:name/auth_code/rotate — rotate the transfer auth code
• POST /domains/:name/transfer_lock — apply clientTransferProhibited
• DELETE /domains/:name/transfer_lock — release the transfer lock
• POST /domains/:name/apply_hold — place a registrar hold
• POST /domains/:name/release_hold — release a registrar hold
• DELETE /domains/:name — delete the domain
• POST /domains/:name/restore — restore a deleted domain during RGP
• POST /domains/:name/reconcile — pull registry state back onto the local row
• GET /domains/:name/events — audit log

Contacts

• POST /contacts/check — validate a contact handle's availability
• GET /contacts — list the tenant's contacts
• GET /contacts/:handle — show a single contact
• POST /contacts — create a contact
• PATCH /contacts/:handle — update a contact
• DELETE /contacts/:handle — delete a contact
• POST /contacts/:handle/transfer — transfer a contact between tenants

Hosts (nameservers)

• GET /hosts — list the tenant's hosts
• GET /hosts/:name — show a single host
• POST /hosts — create a host (subordinate hosts need IPs; external hosts take none)
• PATCH /hosts/:name — update a host's IPs
• POST /hosts/:name/rename — rename a host
• DELETE /hosts/:name — delete a host
• POST /hosts/:name/reconcile — pull registry state (statuses + IPs) back onto the local row

Certificates

• GET /tld_associations/:id/certificate — retrieve metadata + public PEM (never the key)
• PUT /tld_associations/:id/certificate — upload or rotate (key is write-only)
• DELETE /tld_associations/:id/certificate — remove the stored certificate

Pricing

• GET /rate_cards — list active rate cards
• GET /rate_cards/:tld — show the active rate card for a TLD
• POST /quotes — mint a single-use quote (required for ICANN-TLD register / renew / transfer_in / restore)

Registrant agreement + acceptance

• GET /agreement_versions — list agreement versions
• GET /agreement_versions/:id — show a single agreement version
• POST /domains/:name/acceptance — record an acceptance
• GET /domains/:name/acceptance — show the active acceptance
• GET /domains/:name/acceptance/history — list every acceptance recorded for the domain

Tenant administration

• GET /members — list members
• GET /members/:user_id — show a single member
• DELETE /members/:user_id — remove a member
• PUT /members/:user_id/role — change a member's role
• PUT /members/:user_id/activate — activate a member
• PUT /members/:user_id/deactivate — deactivate a member
• GET /invitations — list pending invitations
• POST /invitations — invite a user
• DELETE /invitations/:id — revoke an invitation
• GET /oauth_clients — list the tenant's OAuth clients
• GET /oauth_clients/:id — show a single OAuth client
• POST /oauth_clients — register a new OAuth client
• DELETE /oauth_clients/:id — revoke an OAuth client
• POST /oauth_clients/:id/rotate_secret — rotate a confidential client's secret
• GET /sessions — list active sessions
• DELETE /sessions/:id — revoke a session

Disputes (read-only)

• GET /disputes — list disputes
• GET /disputes/:id — show a single dispute

Abuse

• POST /abuse/reports — public abuse intake (unauthenticated)
• GET /abuse/cases — list the tenant's abuse cases (read-only)

Directory (RDAP-adjacent)

• GET /directory/* — directory lookups (requires the directory:read scope)

Callbacks

Unauthenticated endpoints that complete a workflow started by a server-sent token — typically delivered to the end user via email or SMS. Each carries its token in the URL or body and requires no bearer token; calling them is the confirmation action itself.

• POST /api/v1/invitations/:token/accept — accept a tenant invitation
• POST /api/v1/tenants/:tenant_id/contacts/:handle/verify — confirm a contact's email or phone
• GET /verify/:tenant_id/:handle — registrar-hosted verification page (HTML fallback when the tenant has no custom verification URL template)
• POST /verify/:tenant_id/:handle — form submission target for the hosted verification page