DNSimple Registrar

How to start

1. Get an OAuth 2.1 bearer token. See Authentication.
2. Find your tenant ID. Then select a TLD association.
3. Use the endpoints below. Each request must carry the bearer token as Authorization: Bearer <token>.

The API documentation gives an example request and an example response for each endpoint below.

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

Sign in (a step of the authorize flow)

POST /oauth/authorize/login

Two-factor challenge (TOTP)

POST /oauth/authorize/totp

Approve or deny (a step of the authorize flow)

POST /oauth/authorize/consent

Log out

POST /oauth/logout

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

Each tenant-scoped endpoint starts with /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/auth_code/retrieve — read the current auth code (admin role; audited)
• POST /domains/:name/transfer_lock — apply clientTransferProhibited
• DELETE /domains/:name/transfer_lock — release the transfer lock
• POST /domains/:name/update_lock — apply clientUpdateProhibited
• DELETE /domains/:name/update_lock — release the update lock
• POST /domains/:name/delete_lock — apply clientDeleteProhibited
• DELETE /domains/:name/delete_lock — release the delete lock
• POST /domains/:name/renew_lock — apply clientRenewProhibited
• DELETE /domains/:name/renew_lock — release the renew lock
• PUT /domains/:name/auto_renewal — set the auto-renewal mode (DEFAULT, AUTORENEW, AUTOEXPIRE, RENEWONCE, AUTODELETE)
• POST /domains/:name/auto_renewal — shortcut for AUTORENEW
• DELETE /domains/:name/auto_renewal — shortcut for AUTOEXPIRE
• 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

Change of registrant

A change to the registrant Name, Organization, or Email is material. It needs a confirmation from the two parties.

• POST /domains/:name/change_of_registrant — start a request (returns the two consent tokens one time only)
• GET /domains/:name/change_of_registrant — list the requests for a domain
• GET /change_of_registrant/:id — show a single request
• POST /change_of_registrant/:id/confirm — a party confirms with its token
• POST /change_of_registrant/:id/decline — a party declines with its token
• POST /change_of_registrant/:id/cancel — the initiator retracts a request that is not terminal

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

• POST /hosts/check — availability check against the local records
• POST /hosts/registry_check — availability check at the registry (EPP host:check)
• 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

Registry accounts and certificates

• GET /registry_accounts — list the tenant's registry accounts (never the credentials)
• POST /registry_accounts/:id/set_default — make an account the default for its registry
• POST /registry_accounts/:id/clear_default — clear that default
• GET /registry_accounts/:id/certificate — retrieve metadata + public PEM (never the key)
• PUT /registry_accounts/:id/certificate — upload or rotate (key is write-only)
• DELETE /registry_accounts/:id/certificate — remove the stored certificate
• GET /tld_associations/:id/certificate — obsolete path; it resolves the bound registry account
• PUT /tld_associations/:id/certificate — obsolete path
• DELETE /tld_associations/:id/certificate — obsolete path

TLD associations — read-only

• GET /tld_associations — list the tenant's TLD associations
• GET /tld_associations/:id_or_tld — show one association, by UUID or by TLD label
• PATCH /tld_associations/:id/notifications — set the notification address for the low-balance alerts

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

• GET /api/v1/tenants/:tenant_id — show the calling tenant
• PATCH /api/v1/tenants/:tenant_id — update mutable tenant attributes (also accepts PUT)
• GET /registrar_information — the registrar information that the tenant publishes (RAA §3.17)
• GET /users — list the identity of the tenant's users
• GET /users/:user_id — show the identity of one user
• 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)

Audit events — read-only

The audit log is the evidence of each action. A notification is different: it is an item that needs your attention.

• GET /audit_events — list the tenant's audit events (cursor pagination)
• GET /audit_events/:id — show a single audit event

Notifications

• GET /notifications — list the inbox (cursor pagination)
• GET /notifications/:id — show a single notification
• POST /notifications/:id/ack — mark a notification read
• DELETE /notifications/:id — dismiss a notification

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

These read-only lookups below /directory/v1/ are public. They need no bearer token. The service applies a rate limit to each source IP address. A lookup returns only the fields that the disclosure flags of the contact 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

These endpoints need no authentication. Each one completes a workflow that a token from the server started. Usually the service sends that token to the end user in an email message or an SMS message. Each endpoint takes its token in the URL or in the body. A call to one of these endpoints is the confirmation.

• GET /api/v1/invitations/:token — read the public data of an invitation
• POST /api/v1/invitations/:token/accept — accept a tenant invitation
• POST /api/v1/invitations/:token/decline — decline a tenant invitation (the invitee must authenticate)
• POST /api/v1/tenants/:tenant_id/contacts/:handle/verify — confirm a contact's email or phone
• POST /api/v1/users/verify — complete the verification of a user email address
• POST /api/v1/users/reset_password — request a password reset
• POST /api/v1/users/reset_password/complete — set the new password

Registrar-hosted pages

These paths give HTML, not JSON. They let a person complete an operation without an API client. An email message links to them when the tenant has no page of its own. Each page is a second front end onto the endpoints above, and it adds no rule.

• GET / POST /verify/user — user email verification page
• GET / POST /verify/:tenant_id/:handle — contact verification page (the fallback when the tenant has no verification URL template)
• GET / POST /forgot-password — request a password reset
• GET / POST /reset-password — set the new password
• GET /invitations/:token — invitation page, with the accept and decline actions
• GET /change-of-registrant/:token — consent page, with the confirm and decline actions
• GET / POST /oauth/logout — end the browser session