Search... ⌘ K
Get Started Contact Sales

OAuth Applications

Table of Contents

When you build an application that needs access to DNSimple, or you let an external application request authorization to private details in a user’s DNSimple account without getting their password, you need an OAuth token.

If you only need basic access to the API, a regular user or account token works instead.

What is OAuth?

OAuth 2 is a protocol that lets external applications request authorization to private details in a user’s DNSimple account without getting their password. This is preferred over Basic Authentication, because tokens can be revoked by users at any time.

Register your application before you start. A registered OAuth application is assigned a unique client ID. How the application proves its identity afterward depends on its client type: a confidential application also receives a client secret, while a public application uses PKCE instead of a secret.

Confidential and public applications

When you register an application, you choose how it authenticates. This choice is permanent: you cannot change it after the application is created.

  • Web app (server-side) is a confidential application. It runs on a server you control and can keep a client secret private. It authenticates with its client secret. Most integrations are this type; if you are not sure, choose this.
  • Native or browser app is a public application, for command-line tools, desktop apps, mobile apps, and single-page apps. These run on a user’s device or in their browser, where a secret cannot be kept private. A public application authenticates with PKCE (Proof Key for Code Exchange) instead of a client secret, so the dashboard does not display a client secret for it.

Note

If you do not see a client type choice when you create an application, your account registers web (server-side) applications by default. These authenticate with a client secret.

Finding the OAuth Applications page

To open the OAuth Applications page
  1. Log into DNSimple with your user credentials.
  2. If you have more than one account, select the relevant one.
  3. Go to your account page.
  4. Click in the account menu.

screenshot of adding an oauth application

The page has two cards:

  • Developer applications lists the OAuth applications you registered. From here you can create a new application, and open an existing one to edit, revoke its tokens, or delete it.
  • Applications lists third-party applications that users have authorized to access this account. See Revoking an authorized application.

Creating a new application

In the Developer applications card, click .

Enter an , a , and an . The callback URL must use HTTPS, or HTTP with localhost or a loopback address (127.0.0.1, [::1]) for native apps such as command-line tools. See the OAuth developer guide for how loopback redirect URIs are matched.

If your account can register public applications, the form also asks Choose Web app (server-side) for a confidential application or Native or browser app for a public one. Then click .

Tip

The field is optional.

screenshot of creating a new oauth application

After the application is created, you are taken to its page. A confidential application shows a Client ID and a Client Secret. A public application shows only a Client ID, because it authenticates with PKCE and is not issued a client secret.
screenshot of successful creation of new oauth application

Note

For confidential applications, the Client ID and Client Secret are unique to your application, and the client secret should not be shared.

Resetting the client secret

If the client secret of a confidential application is exposed, reset it. On the application page, click and confirm. DNSimple issues a new client secret, and your application must be updated to use it.

Revoking user tokens

To revoke every token issued to users of your application, open the application page and click . In the dialog, confirm the action.
screenshot of revoking tokens for an oauth application

Warning

This cannot be undone. All clients will lose access to your application.

Deleting an application

Deleting an application is permanent. Any clients using the application can no longer access DNSimple.

To delete an application, open the application page and click . In the dialog, type the application name to confirm.
screenshot of deleting an oauth application

screenshot of confirming delete of oauth application

Revoking an authorized application

The Applications card on the OAuth Applications page lists third-party applications that have been authorized to access this account. To remove an application’s access, click the actions menu (three dots) next to it, then click .

Interacting with the API through OAuth

For step-by-step instructions on interacting with the DNSimple API through OAuth, see the OAuth developer guide.

Have more questions?

If you have additional questions or need any assistance with your OAuth Applications, just contact support, and we’ll be happy to help. You can also read more about the DNSimple API.