Learn to implement an OAuth flow using the Dropbox API
When working with the Dropbox APIs, your app will access Dropbox on behalf of your users. You'll need to have each user of your app sign into dropbox.com to grant your app permission to access their data on Dropbox.
Dropbox uses OAuth 2.0, an open specification, to authorize access to a user’s data. Once completed by a user, the OAuth flow returns an access token to your app. This authorization token your app and user in subsequent API calls. It should be passed with the
Authorization HTTP header value of
Note that Pre-Built components (the Chooser, Saver, and Embedder) are built into the Dropbox web site, and rely on the end-user’s own Dropbox web session, so they don’t require an OAuth flow (or an access token).
Here's a diagram of an OAuth flow:
In this flow:
The Dropbox API uses OAuth scopes to determine the actions your application is allowed to perform on a user’s data. When you create your application in the App Console, you’ll choose from different scopes in the ‘Permissions’ tab.
The selected scopes are applied to your access token and determine which API calls your application is allowed to execute. This level of access is then communicated to the end user on the Dropbox app authorization page where the user consents to sharing their data.
Scopes are generally organized into major actions, often read and write, on major objects. These objects include:
For applications using the Business API to operate on Teams, this also includes:
The scope required for any given API call is documented on the endpoint.
Prior to the introduction of scopes, Dropbox API apps would select only their level of content access (described below). Business API apps would select from one of four permission types to determine the API calls they have access to:
For compatibility, these deprecated app types remain selectable - but over the coming months we will begin to transition these apps to equivalent scopes. If you have an existing app on these types, don’t worry - this transition does not require code change.
As you create your Dropbox application, you will also be prompted to select the scope of file access. Currently, these two options options are:
Always ask for the least amount permissions required by your applications. Requesting more scope and content access than required may result in end users not accepting your OAuth request and could impact your app review process.
When using API scopes, you may also ask for minimal permissions at authorization time - then re-authorize at later time if and when your application requires more permissions from the user.
Remember, that pre-built components (the Chooser, Saver, and Embedder) are authorized on dropbox.com. You don’t need to manage their access - but the components can be used in conjunction with apps making API calls.
For example, you may discover that using these components for upload/download/preview means that you don’t need to build functionality and request permission to do this in direct API endpoints.
Before you can get started, you'll need to register your app with Dropbox by creating a new app in the App Console. That page will guide you through the process of registering your app, selecting permissions, and obtaining an app key and secret (a.k.a.
client_secret) and inputting redirect URIs.
If you'd like to quickly test out the Dropbox APIs using your own Dropbox account before implementing OAuth, 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 - you'll need to use the standard OAuth flow to obtain access tokens for other users.
Do not instruct your users to register their own Dropbox application to use your app - you just need to register your app once. Your end-users will connect to that app via the OAuth flow.
While doc will cover details of OAuth using HTTP calls, remember that Dropbox SDKs will take care of some of the OAuth 2 process automatically for you. Using one of these SDKs is recommended when possible. If you’re using one of the SDKs, see their tutorials and sample apps for reference after reviewing this guide.
The code flow is the recommended OAuth flow for all types of applications. In order to implement it, your application should:
redirect_uri(if applicable) and specifying the
code, and present it to the user
client_secretto exchange the code for an access token in order to make API calls
As you configure redirects, remember:
redirect_uriparameter in your Authorization URL matches one of the registered values at authorization time.
redirect_uriis optional with the code flow - if unspecified, the authorization code is displayed on dropbox.com for the user to copy and paste to your app.
stateparameter the authorization URL - which will be returned as a query parameter in the redirect.
When using the code flow, your app must keep the
client_secret secure. If your app can’t guarantee it’s security, then we recommend the use of PKCE as described below
Some types of applications may be unable to keep the
client_secret secure. This includes, but isn’t restricted to:
PKCE is an open extension to OAuth 2.0, and solves this problem using dynamic codes instead of the static
client_secret. Your app should construct a random
code_verifier at authorization time of the user.
Incorporating these codes is similar to the code flow above, with the following additions:
code_challengein your authorization URL. The code challenge method may be
plain. The challenge should be the SHA-256 encoded value of your verifier (if method is 256), or the value if the method is plain. Using
code_verifierwith your generated value instead of the
Prior to the introduction of PKCE, the implicit grant flow was the recommended solution to applications which cannot secure a
Dropbox continues to support this legacy flow for compatibility, but recommends PKCE for new apps. You should disable the implicit grant option in App Console if you are not using it.
In the implicit grant flow:
response_typeand specifying the
Your authorization URL should look like:
In this flow, the
redirect_uri is required and verified in the App Console as described in the code flow.
Currently, the Dropbox mobile SDKs use the implicit grant - but will support PKCE in the near future.
Dropbox access tokens are short lived, and will expire after a short period of time. The exact expiry time of a token is returned by the token endpoint (or the redirect URI in implicit grant) - but is generally long enough for a reasonable web session.
If the token expires - throwing a 401 error - your application may simply re-authenticate as described above. If your token is expired, but the user is signed into Dropbox and their approval is still valid, the redirects will not require end-user input. A user’s approval remains valid until explicitly revoked.
Applications that require offline access to the API - meaning using the API when the end user is not actively interacting through your app - will not be able to prompt for re-authorization. These apps may instead use long-lived refresh tokens can be used to obtain new access tokens.
When using refresh tokens, your call to the /oauth2/token endpoint with the
code will return a new short-lived access token and a new refresh token, which should be securely stored.
To update your access token, call the /oauth2/token endpoint - specifying your
refresh_token as a parameter and using the
refresh_token. The endpoint will return a new short-lived access token and a timestamp indicating its expiration time.
Working with refresh tokens is easier with an SDK. Helper methods accept the refresh token, and manage this update of the short-lived access token for you.
In the past, the Dropbox API used only long-lived access tokens. These are now deprecated, but will remain available as an option in the Developer console for compatibility until mid 2021.
For existing apps migrating to short-lived tokens, the
token_access_type parameter on your authorization URL enables requesting short-lived tokens per-auth, allowing you to update your code without versioning issues in the Dropbox App Console.
There are several implementation options to OAuth - which is best for you will depend on the nature of your application. Dropbox recommends the following:
If your app is
A server-side web application that only calls the Dropbox API as users interact with it
Use the OAuth code flow with short-lived access tokens only (no refresh tokens).
Use the OAuth code flow with short-lived access tokens with PKCE (no refresh tokens).
A server-side application that requires background access.
Use the OAuth code flow, with refresh tokens.
A client-side Desktop app or mobile app that requires background access
Use the OAuth code flow with PKCE, with refresh tokens.
Currently using long-lived tokens
Adopt short-lived tokens over the coming months
Currently using a legacy app permission type
Stay tuned for an option to convert to a scoped app