API Access Token
Last updated
Table of Contents
- Video walk-through
- Account tokens vs user tokens
- Getting to the API & Access page
- Viewing your API usage and limits
- Generating an account access token
- Obtaining the generated access token
- Editing an account access token
- Disabling and enabling an access token
- Deleting an access token
- Have more questions?
An API access token lets a script, integration, or the DNSimple CLI use the DNSimple API on your behalf. Create account tokens on the API & Access page of your account, and user tokens on your user profile page.
To create an application that requires access to DNSimple, or let an external application request authorization to private details in a user’s DNSimple account without a password, you need an OAuth Token.
Video walk-through
Account tokens vs user tokens
The API offers two types of tokens: account tokens and user tokens.
The user token gives you access to any resource associated with any account the user has access to. An account token gives you access only to the resources connected to that account.
Tip
We recommend using account tokens unless your application needs access to several accounts with a single token.
Note
An account token is not the Account Identifier you enter to move a domain to another DNSimple account, even though the app labeled that identifier Account Token until November 2025.
Getting to the API & Access page
To open the API & Access page
- Log in to DNSimple with your user credentials.
- If you have more than one account, select the relevant one.
- Go to your account page.
- Click in the account menu.

This page shows the API card at the top, with your account ID and your API usage and limits, followed by your access tokens. Each token is labeled Classic or Scoped, and the list includes the last used date. You can add, disable, enable, and delete access tokens from here.
You manage user tokens on your user profile page, in the User access tokens section.
Viewing your API usage and limits
The API card at the top of the API & Access page shows your account ID and summarizes how your account is using the DNSimple API.

The card has these sections:
-
Account ID: the number that identifies your account in API paths, such as
/v2/{account_id}/domains. Click Copy to copy it. - General API: your hourly request limit, the number of requests remaining in the current window, and when the limit resets. See API Rate Limit for details on how the limit is applied.
- Domain Research API: your account’s request count for the current month against the Domain Research API. This section only appears when the Domain Research feature is active on your account.
The card reflects your whole account, not a single token. Every token on the account draws from the same limit.
Generating an account access token
Note
A classic token is available on every plan. Creating a scoped token requires the Solo Pro plan or higher.
The Access tokens card offers two actions:
- Click Add classic token to create a token that can access every resource in the account. The form asks for a name. The page title is New classic access token.
- Click Add scoped token to create a token limited to the resources you select. The page title is New scoped access token. On a plan without scoped tokens, Add scoped token is disabled.
Enter a name that says what the token is for, then click Generate token.
DNSimple emails the account notification recipients when you create the token. The subject and the body say whether the token is classic or scoped. User tokens do not send this email.
Selecting permission scopes
A classic token has no permission scopes. You cannot turn a classic token into a scoped token, or a scoped token into a classic token. Create a new token of the other type instead.
A scoped token can be restricted to certain resources, or certain groups of resources, in an account. You can also set the type of access: read-only or full access. For instance, you can create an account access token with permissions for managing all the certificates for a given domain name or across all domain names. You can also create account access tokens with read-only permissions for specific zones. For the full list of permissions, access levels, and which ones can be limited to specific domains or zones, see API Access Token Permissions Reference.
If the account moves to a plan without scoped tokens, existing scoped tokens keep working. You can disable, enable, and delete them. Edit is not in the actions menu, and Add scoped token stays disabled, until the account is on a plan that includes scoped tokens.
When a scoped access token has access to specific domains or zones rather than all of them, the API list endpoints (/domains and /zones) will return only the resources the token has access to.

Certificates, domains, registrar, and zones are resource types that allow restriction of access to specific resources.
Accounts with the Domain Research API feature also see a Domain Research scope. This scope is read-only and grants access to the domain research status check endpoint. It does not support per-resource restriction, so selecting it gives the token access to research any domain.
For example, when configuring the token for access to zones, after choosing Read-only or Full access from the dropdown, you can click Change to specify whether it should have access to all zones in the account or only selected zones.
When you are finished with your selections, click Generate token to create the token.
Obtaining the generated access token
After you click Generate token, DNSimple returns you to the token list. A message at the top of the list names the new token and shows its value. Click Copy next to the value to copy it.
Copy the access token now. It is shown only once.
You can now access the API with this token using the HTTP header Authorization: Bearer {TOKEN}, replacing {TOKEN} with the value taken from the page when the token is generated. For more on authenticating API requests, see the authentication section on the DNSimple Developer site.
Editing an account access token
In the list of access tokens, click the actions menu (three dots) next to the token, then click .
- A classic token shows the name only. Change the name, then click Update token.
- A scoped token on a plan that includes scoped tokens shows the name and the permissions. Change what you need, then click Update token, or click Cancel to leave without saving.
- A scoped token on a plan without scoped tokens has no action. You can still disable, enable, or delete it.
DNSimple emails the account notification recipients when you update the token.
Disabling and enabling an access token
Disable an access token to stop it from working without deleting it. For example, disable a token when you suspect a leak, or when you pause or retire an integration. The token keeps its value, its name, and its permission scopes. When you enable it again, the same token value works again.
To disable an access token
- Go to the token list. For an account token, go to the API & Access page of the account. For a user token, go to your user profile page.
- Click the actions menu (three dots) next to the token.
-
Click .

- In the dialog, confirm the action.
The token list shows Disabled under the name of the token. To use the token again, click the actions menu next to the token, then click .
You must be an account administrator to disable or enable an account token. You can disable or enable only your own user tokens.
What happens when a token is disabled
- The API rejects every request made with the token with an HTTP
401 Unauthorizedresponse. This is the same response as for a deleted token. - The last used date of the token does not change while the token is disabled.
- For an account token, the account activity log records the change as
Token '<name>' disabledorToken '<name>' enabled. - For an account token, classic or scoped, DNSimple sends an email to the account notification recipients when you disable or enable the token. User tokens do not send this email.
- The disabled token keeps its name. You cannot create another token with the same name until you delete the disabled token.
Note
You cannot disable OAuth tokens. To stop an OAuth application, revoke its tokens.
Deleting an access token
Delete a token when you no longer need it. A deleted token cannot be recovered. To stop a token temporarily, disable it instead.
To delete an access token
- Go to the token list. For an account token, go to the API & Access page of the account. For a user token, go to your user profile page.
- Click the actions menu (three dots) next to the token.
- Click .
- In the dialog, confirm the action.
Have more questions?
If you have additional questions or need any assistance with API access tokens, just contact support, and we’ll be happy to help. You can also read more about the DNSimple API.