Search... ⌘ K
Get Started Contact Sales

API Glossary

Table of Contents

A reference for DNSimple API terminology. For user tokens, account tokens, and Domain Access Control roles, see the Account Glossary. For request formats and endpoints, see the DNSimple developer documentation.

Tokens and access

API access token

A credential that lets a script, an integration, or the DNSimple CLI call the DNSimple API. There are two kinds: user tokens and account tokens. The token value is shown only once, when you create it.

Learn more:

Bearer token

The way an API request sends an access token: in the HTTP header Authorization: Bearer {TOKEN}. A request with a missing, wrong, or disabled token returns 401 Authentication failed.

Learn more:

Scoped access token

An account token limited by permission scopes, instead of having full access to the account. Scoped access tokens are available on the Teams plan and higher. On the Solo plan, every account token has full access. If an account moves to a plan without scoped tokens, its scoped tokens stop working with 412 Feature not enabled: scoped_access_tokens.

Learn more:

Permission scope

One permission on a scoped access token, covering one type of resource, such as Zones, Domains, or Certificates. Each scope has an access level. Certificates, Domains, Registrar, and Zones scopes can also be limited to selected domains or zones. The API names a missing scope in its 403 Permission Denied error, for example zones:{zone_name}:write.

Learn more:

Access level

The setting on a permission scope: No access, Read-only, or Full access. In error messages, Read-only appears as read and Full access as write. Full access also covers requests that only need Read-only.

Learn more:

Disabled token

An access token that has been switched off without being deleted. The API rejects it with 401, the same as a deleted token. It keeps its value, name, and permission scopes, so enabling it again restores the same token. OAuth tokens cannot be disabled.

Learn more:

API & Access page

The page in your DNSimple account where you create and manage account tokens. It also shows the API Limits & Usage card with your hourly limit, requests remaining, and reset time. User tokens are managed on your user profile page instead.

Learn more:

Account ID

The number that identifies a DNSimple account in API paths, as in /v2/{account_id}/domains. Calling the whoami endpoint with an account token returns it. Requests with an account ID in the path count toward that account’s rate limit.

Learn more:

whoami

The API endpoint /v2/whoami, which returns who a token belongs to. An account token returns the account. A user token returns the user, with "account": null. It is the quickest way to test whether a token works.

Learn more:

OAuth applications

OAuth application

An application you register with DNSimple so that it can ask users for access to their DNSimple accounts without getting their passwords. You manage OAuth applications on the OAuth Applications page of your account. Users can revoke an application’s access at any time.

Learn more:

Client ID

The unique identifier DNSimple assigns to an OAuth application when you register it. Every OAuth application has one, whether it is confidential or public.

Learn more:

Client secret

The private value a confidential OAuth application uses to prove its identity. Keep it private. If it is exposed, reset it on the application page and update your application with the new one. Public applications do not have a client secret.

Learn more:

Confidential application

An OAuth application that runs on a server you control and can keep a client secret private. It is labeled Web app (server-side) in the dashboard. Most integrations are this type. The client type cannot be changed after the application is created.

Learn more:

Public application

An OAuth application that runs on a user’s device or in their browser, such as a command-line tool, a desktop or mobile app, or a single-page app. It is labeled Native or browser app in the dashboard. It cannot keep a secret private, so it authenticates with PKCE instead of a client secret. Accounts that do not see this choice register confidential applications.

Learn more:

PKCE

Proof Key for Code Exchange. The method a public OAuth application uses to prove its identity without a client secret.

Learn more:

Authorization callback URL

The URL DNSimple sends users back to after they authorize your OAuth application. It must use HTTPS, or HTTP with localhost or a loopback address for native apps such as command-line tools.

Learn more:

Authorized application

A third-party OAuth application that a user has allowed to access your account. Authorized applications are listed in the Applications card on the OAuth Applications page, where you can revoke their access.

Learn more:

Limits and errors

Rate limit

The number of API requests allowed per hour. By default, an account can make 2,400 requests per hour, shared by every token that calls the API for that account. Requests made without an account, such as whoami with a user token, are limited per user. Unauthenticated requests are limited to 30 per hour per IP address.

Learn more:

Rate limit headers

The X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every authenticated API response. They describe the hourly limit only, not the domain availability check limit.

Learn more:

429 Too Many Requests {#429}

The HTTP status the API returns when a request goes over a limit. The message says which one: quota exceeded for the hourly limit, endpoint checkDomain quota exceeded for the domain availability check limit, or Monthly request cap reached for the Domain Research API.

Learn more:

Domain availability check limit

A separate limit of 60 domain availability checks per hour per account, on top of the hourly limit. The rate limit headers do not show it. The limit is much higher in the Sandbox, so design for the production limit.

Learn more:

Monthly request cap

The Domain Research API limit of 10,000 requests per account per calendar month. Over the cap, requests return 429 until the start of the next month, given in the Retry-After header. Domain Research requests also count toward the hourly limit.

Learn more:

Pagination

How the API splits long lists into pages. List endpoints return 30 results per page by default and 100 at most. The pagination object in the response shows the current page and the total number of pages. An integration that ignores it only sees the first page.

Learn more:

Domain Research API

An API endpoint that reports whether a domain is available, unavailable, or unknown for registration. It is available on the Enterprise plan, in private beta, and needs a token with the Domain Research scope.

Learn more:

Drop catching

Checking a domain’s availability over and over to register it the moment it expires. DNSimple does not allow drop catching, and accounts that attempt it are disabled.

Learn more:

Webhooks

Webhook

A URL where DNSimple sends an HTTP POST request whenever an event happens in your account, such as a domain registration or a DNS record change. The URL must use HTTPS, and your endpoint must respond with HTTP 200. Any other response counts as a failed delivery.

Learn more:

Webhook suppression

What happens when deliveries to a webhook keep failing: DNSimple stops sending it events. The Webhooks page shows a warning icon next to a suppressed webhook. After you fix your endpoint, clear the suppression to start receiving events again.

Learn more:

Sandbox and production

Sandbox

DNSimple’s isolated test environment, at app.sandbox.dnsimple.com for the web interface and api.sandbox.dnsimple.com for the API. It mirrors production, but it is shared with other customers, its records do not resolve publicly, and its data can be cleared.

Learn more:

Production

The live DNSimple environment, at app.dnsimple.com and api.dnsimple.com. Production and Sandbox accounts and tokens are separate. A Sandbox token sent to the production API returns 401 Authentication failed.

Learn more:

OT&E

Operational Test and Evaluation. The registry test environments that Sandbox domain registrations, transfers, and renewals run against. Availability in OT&E does not match real-world availability.

Learn more:

Have more questions?

If you have any questions about the DNSimple API, contact support, and we will be happy to help.