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>.

Every endpoint listed below is documented with example requests and responses in the API documentation.

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

Two-factor challenge (TOTP)

POST /oauth/authorize/totp

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; accepts a single name or a list of names spanning multiple TLDs (the service fans out per registry binding). Optional: idn_language, fee_commands, fee_period, client_transaction_id.
• 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
• GET /transfers — list inter-registrar transfers (in + out)
• GET /transfers/:id — show a single transfer
• POST /transfers/:id/cancel — cancel a pending inbound transfer

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_card — list active rate cards across this tenant's TLDs
• GET /tlds/:tld/rate_card — show the active rate card for a TLD
• POST /quotes — mint a single-use quote (required for ICANN-TLD register / renew / transfer_in / restore; informational for trade)

Registrant agreement + acceptance

• POST /agreement_versions — create a draft agreement version
• GET /agreement_versions — list agreement versions
• GET /agreement_versions/:id — show a single agreement version
• POST /agreement_versions/:id/publish — publish a draft
• POST /agreement_versions/:id/retire — retire a published version
• POST /domains/:name/acceptance — record an acceptance
• GET /domains/:name/acceptance — show the active acceptance
• POST /domains/:name/acceptance/terminate — terminate the active acceptance (start the 45-day deletion clock)
• GET /domains/:name/acceptance/history — list every acceptance recorded for the domain

Tenant administration

• PATCH /api/v1/tenants/:tenant_id — update mutable tenant attributes (also accepts PUT)
• 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

Current user (not tenant-scoped)

• GET /api/v1/user/tenants — list tenants the calling user can authenticate into
• GET /api/v1/user/totp — TOTP enrollment status
• POST /api/v1/user/totp/enrollments — start TOTP enrollment (returns secret + otpauth URI)
• POST /api/v1/user/totp/enrollments/confirm — confirm with a code (returns recovery codes once)
• DELETE /api/v1/user/totp — disable TOTP (requires a current code or recovery code)

Disputes (read-only)

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

Abuse

• POST /api/v1/abuse_reports — public abuse intake (unauthenticated)
• GET /abuse_cases — list the tenant's abuse cases (read-only)
• GET /abuse_cases/:id — show a single abuse case

Directory (RDAP-style lookups)

Public read-only lookups under /directory/v1/ — no bearer token required, rate-limited per source IP. Returns only the fields each contact's disclosure flags permit.

• GET /directory/v1/domains/by_name/:name — look up a domain by FQDN
• GET /directory/v1/contacts/:handle — look up a contact by handle
• GET /directory/v1/hosts/by_name/:name — look up a host by FQDN
• GET /directory/v1/registrars/by_iana_id/:iana_id — look up a registrar by IANA id

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