API Access Token

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
• Viewing and editing the permissions of a scoped 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 and user.

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.

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.

We recommend using account tokens unless your application needs multi-account access via a single token.

Getting to the API & Access page

This page shows your API usage and limits at the top, followed by your access tokens, including the last used date for each. 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 Limits & Usage card at the top of the API & Access page summarizes how your account is using the DNSimple API.

The card has two sections:

• 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

Click Add to add a new access token.

When you create a new token, give it a name you can remember.

If you are subscribed to the Solo Pro plan or higher, you can choose permission scopes for the token. If you are on the Solo plan, the token will have full permissions to all resources in the account.

Click Generate token to create the token after giving it a name.

Selecting permission scopes

Scoped access tokens can be restricted to access only 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.

When using a scoped access token with granular permissions (i.e., access to specific domains or zones rather than all), 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 clicking on Generate token, the generated access token will be displayed on the screen.

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.

Viewing and editing the permissions of a scoped access token

After an access token has been created, you can view and edit the permissions it was created with. In the list of access tokens, click the actions menu (three dots) next to the token, then click Edit.

You can then see what resources the token has access to and make changes to the permissions if needed.

When you are done editing the token permissions, click Update token to save the updated permissions to the token, or click Cancel to exit without making changes.

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.

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

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 Unauthorized response. 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>' disabled or Token '<name>' enabled.
• For a scoped account token, DNSimple sends an email to the account notification recipients when you disable or enable the token.
• The disabled token keeps its name. You cannot create another token with the same name until you delete the disabled token.

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.

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.