DNSimple platform

The platform

Add-ons: getting started

Add-Ons: Reference


One of the first steps to accomplish when writing your add-on is to authenticate with DNSimple and retrieve the access token of your user so as to make requests to DNSimple on their behalf.

OAuth 2 is used for authentication and authorization to the DNSimple API.

Setting up an OAuth app

To authenticate against the DNSimple API you first need register an OAuth Application. You can set up your application on your account settings page:

  1. Go to your user settings (or for Sandbox, use the Sandbox user settings).
  2. Select the account you want to create a application for.
  3. Go to Applications -> Developer applications

developer applications list

Here you can see a list of all your applications belonging to the selected account.

To create a new one, select New application at the bottom of the list.

You now can fill out the details of your application:

developer applications form filled

Congratulations 🎉 ! You have created your developer application and now see a screen presenting your Client ID and Client Secret.

developer test application

You can always access and edit this information from the “developers applications” tab. Here you can also reset the client secret and all user tokens, or delete the application.

Starting the OAuth dance

Now that you have the Client ID and Client Secret you can start the OAuth redirection flow.

First you redirect the user to the OAuth authorize url along with the following GET parameters:


Note: That all official DNSimple clients have functions constructing these urls

The user must then authorize your application so you can retreive an access token your add-on will use when communicating with the API.

oauth access flow

After the user successfully grants access, they are sent back to your application along with the following get parameters:


Handing the callback

Now that you have an authorization code and the flow is returned to your application, it’s time to exchange the code for an access token.

For this documentation, cURL is used to show how to retrieve the access token, but note that all official DNSimple clients have functions which convert the code into an access token.

$ curl https://api.dnsimple.com/v2/oauth/access_token --data "grant_type=authorization_code&client_id=2d64f58b507944a4&client_secret=Dwjm23pGuTcdTdAa1TzuWhqAYYag5qgw&code=X0dmUUyoUpDcMrEyL33WAHpIowT8nVwE&redirect_uri=http://localhost:4000/dnsimple/callback&state=HDuBq"

Check out the case studies for a detailed implementation of this flow.

With that access_token you can access all DNSimple resources on behalf of the user. See Interacting with DNSimple.

Authenticating with other services

Often when you are writing an add-on for the DNSimple platform, you want to connect with other services as well. For that purpose, we strongly recommend to also use OAuth whenever it’s available.

When dealing with multiple OAuth providers, it’s recommended to follow a certain “scheme” of callback urls:

/:provider/authorize # to start OAuth flow
/:provider/callback # to handle the callback


OAuth2 can be a complicated topic, and sometimes things do not work as you might expect. Here are some tips we’ve collected for you to spot errors quickly.

Look at the complete response body:

Usually the response body contains helpful error messages indicating what went wrong and why.

Double check client_id and client_secret

These have to match exactly otherwise you will encounter errors.

Keep an eye on the state

As this value is passed back and forth, check every step in the flow if it’s still correct.

Use a simple state

We recommend (but don’t enforce) to only use plain ASCII characters for your state. As many systems touch it, it is better to keep things simple.

More Information

You can find detailed information about DNSimple OAuth at the official API documentation: https://developer.dnsimple.com/v2/oauth/

If you want to learn more about OAuth2, our friends at Digital Ocean have written a excellent tutorial about it: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

We also have official clients supporting OAuth: