OAuth guide

When working with the Dropbox APIs, your app will access the Dropbox service on behalf of your users. You'll need to have each user of your app authenticate with Dropbox to both verify their identity and give your app permission to access their data on Dropbox.

Dropbox uses OAuth 2, an open specification, for this purpose. Once completed by a user, the OAuth process returns an access token to your app. The access token is a string generated by Dropbox that you'll need to send with each subsequent API request to uniquely identify both your app and the end user.

There are several reasons we use OAuth. Most importantly, your app doesn't need to store or transmit the user's Dropbox password. OAuth also allows the user to authorize only a limited set of permissions and the user may revoke access at any time. This makes OAuth a safer and more secure form of API authorization for your users.

Setting up your app

Before you can get started, you'll need to register your app with Dropbox by creating a new app in My apps. That page will guide you through the process of registering your app, including choosing which permission your app needs, and specifying an app name.

After creating your app, you're ready to set up the authorization process in your app. The Dropbox SDKs will take care of some of the OAuth 2 process automatically for you, and you can use the tutorials and sample apps for reference.

Testing with a generated access token

If you'd like to test out the Dropbox APIs quickly using your own Dropbox account, you can generate an access token from your newly created app in My apps by pressing the button that says "Generate" in the OAuth 2 section of your app settings page. Keep in mind that this is only for your own account and you'll need to use the standard OAuth flow to obtain access tokens for other users.

OAuth 2 flow

Here's a simple diagram of the OAuth 2 flow - the process for authorizing your users with Dropbox.

OAuth 2 diagram

The general idea is that the user will be redirected to Dropbox to authorize your app to access their Dropbox data. After the user has approved your app, they'll be sent back to your app with an authorization code. At this point your app will exchange the authorization code for an access token which can be used to make subsequent requests to the Dropbox API (not shown in the diagram above).

Note that for certain apps, such as command line and desktop apps, it's not possible for a web browser to redirect back to your app. In these cases, your app does not need to include a redirect_uri parameter. Dropbox will present the user with an authorization code that they will need to copy and paste into your app, at which point your app can exchange it for a reusable access token.

The Dropbox SDKs for mobile apps take care of the tricky parts of OAuth 2 for you. However, with web apps, you'll need to know a bit more about the process.

OAuth 2 on the web

OAuth 2 web diagram

If you're building a web app, the first step in the OAuth process is to redirect the user to a Dropbox webpage. Typically the user takes some action on your site, such as clicking a "Connect to Dropbox" button, and your app will need to redirect the user to a particular Dropbox authorization URL.

The Dropbox authorization URL is specific to your app and is composed of your app key, redirect URI, response type, and state (it looks something like https://www.dropbox.com/oauth2/authorize?client_id=...&redirect_uri=...). Each of the Dropbox SDKs contains a method that will help you generate this URL when you need it.

At this point in the flow, the user may need to login to Dropbox or create a Dropbox account. Once the user is logged into Dropbox, they will be presented with a screen to authorize your app to access their Dropbox data.

Dropbox authorize screen

After the user approves your app, they'll be redirected from Dropbox back to your app using the redirect URI provided in the Dropbox authorization URL. For security, this redirect URI must match one of the redirect URIs you have specified for your app. If you forget to specify a redirect URI you'll get a friendly error message from Dropbox to go and set one up.

The redirect back to your app will include an authorization code from Dropbox. Your app will then need to make a request to Dropbox to exchange the authorization code for a re-useable access token. This request to exchange the authorization code for an access token takes places behind-the-scenes with a call to the /token API endpoint and shouldn't be visible to your end users.

This access token is the key to making successful requests to the Dropbox API. You'll want to store it someplace secure and use it each time your app needs data from Dropbox for that user. Web apps should store the access token along with other session information, usually in a database.

Now your app is authorized to use the Dropbox API on behalf of your user. When you'd like to make API calls to Dropbox, simply include the authorization header, "Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>", with each request.