Authorization
Dropbox supports OAuth 2.0 for authorizing API requests. Find out more in our OAuth guide. Authorized requests to the API should use an Authorization header with the value Bearer <TOKEN>, where <TOKEN> is an access token obtained through the OAuth flow.
Access tokens provided by Dropbox should be treated as opaque. Applications must support variable token size with tokens capable of exceeding 1KB. Applications should not depend on details such as access token composition as Dropbox reserves the right to make changes to token contents.
Note: OAuth is an authorization protocol, not an authentication protocol. If you’re looking to use Dropbox as an identity provider, check out the Dropbox OpenID Connect Guide.
/oauth2/authorize
Description
This starts the OAuth 2.0 authorization flow. This isn’t an API call—it’s the web page that lets the user sign in to Dropbox and authorize your app. After the user decides whether or not to authorize your app, they will be redirected to the URI specified by redirect_uri.
OAuth 2.0 supports three authorization flows:
- The
codeflow returns an authorization code via the optionalredirect_uricallback which should then be converted into a bearer access token using the/oauth2/tokencall. This is the recommended flow for apps that are running on a server. - The
PKCEflow is an extension of the code flow that uses dynamically generated codes instead of asecretto perform an OAuth exchange from public clients. The PKCE flow is a newer, more secure alternative to the token (implicit) flow. It is the recommended flow for client-side apps, such as mobile, desktop, or browser JavaScript apps. - [Legacy. We recommend the PKCE flow.] — The
tokenor implicit grant flow returns the bearer token via theredirect_uricallback, rather than requiring your app to make a second call to a server. This is useful for pure client-side apps, such as mobile, desktop, or browser JavaScript apps.
For more information on the code and token flows, see Section 1.3 of the OAuth 2 spec. For more info on the PKCE extension, see RFC 7636
Your app should send the user to this app authorization page in their system browser, which will display the permissions being granted. If the user isn’t already signed in to the Dropbox website, they will be prompted to do so on this web page. This web page should not be displayed in a web-view. This is in order to maintain compatibility with the website and to comply with Google’s policy against processing their OAuth flow inside a web-view, to support users who sign in to Dropbox using their Google accounts. Learn about the dropbox.com system requirements.
URL Structure
Note: This is the only step that requires an endpoint on www.dropbox.com. All other API requests are done via api.dropboxapi.com, content.dropboxapi.com, or notify.dropboxapi.com.
Method: GET
Example: Auth URL for code flow
Example: Auth URL for code flow with offline token access type
Example: Auth URL for PKCE code flow
Parameters
response_type String The grant type requested, either token or code.
client_id String The app’s key, found in the App Console.
redirect_uri String? Where to redirect the user after authorization has completed. This must be the exact URI registered in the App Console; even ‘localhost’ must be listed if it is used for testing. All redirect URIs must be HTTPS except for localhost URIs. A redirect URI is required for the token flow, but optional for the code flow. If the redirect URI is omitted, the code will be presented directly to the user and they will be invited to enter the information in your app.
scope String? This parameter allows your user to authorize a subset of the scopes selected in the App Console. Multiple scopes are separated by a space. If this parameter is omitted, the authorization page will request all scopes selected on the Permissions tab. Read about scopes in the OAuth Guide.
include_granted_scopes String? This parameter is optional. If set to user, Dropbox will return the currently requested scopes as well as all previously granted user scopes for the user. If set to team , Dropbox will return the currently requested scopes as well as all previously granted team scopes for the team. The request will fail if this parameter is provided but not set to user or team, or if it is set to user but the scope contains team scope, or if it is set to team but the authorizing user is not a team admin. If not set, Dropbox will return only the scopes requested in the scope parameter.
token_access_type String? If this parameter is set to offline, then the access token payload returned by a successful /oauth2/token call will contain a short-lived access_token and a long-lived refresh_token that can be used to request a new short-lived access token as long as a user’s approval remains valid. If set to online then only a short-lived access_token will be returned. If omitted, this parameter defaults to online.
state String? Up to 2000 bytes of arbitrary data that will be passed back to your redirect URI. This parameter should be used to protect against cross-site request forgery (CSRF). See Sections 4.4.1.8 and 4.4.2.5 of the OAuth 2.0 threat model spec.
code_challenge String?(min_length=43, max_length=128) Part of the PKCE flow, the challenge should be an SHA-256 (S256) encoded value of a string that will serve as the code_verifier of the corresponding /oauth2/token call. Can can also be set to plain (plain).
code_challenge_method String? Defines the code challenge method. Can be set to S256 (recommended) or plain.
require_role String? If this parameter is specified, the user will be asked to authorize with a particular type of Dropbox account, either work for a team account or personal for a personal account. Your app should still verify the type of Dropbox account after authorization since the user could modify or remove the require_role parameter.
force_reapprove Boolean? Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.
disable_signup Boolean? When true (default is false) users will not be able to sign up for a Dropbox account via the authorization page. Instead, the authorization page will show a link to the Dropbox iOS app in the App Store. This is only intended for use when necessary for compliance with App Store policies.
locale String? If the locale specified is a supported language, Dropbox will direct users to a translated version of the authorization website. Locale tags should be IETF language tags.
force_reauthentication Boolean? When true (default is false) users will be signed out if they are currently signed in. This will make sure the user is brought to a page where they can create a new account or sign in to another account. This should only be used when there is a definite reason to believe that the user needs to sign in to a new or different account.
prompt String? Specifies whether the user should be prompted for reauthentication or consent. If none the user will not be prompted with an authorization screen. This will cause an error if the user has not previously authorized the app. If login the user will be prompted to sign in again before authorizing the app. This is equivalent to force_reauthentication=true. If consent the user will always be prompted for authorization. This is equivalent to force_reapprove=true. Errors may occur if one of these parameters conflicts with another (for example: prompt=none&force_reapprove=true).
max_age UInt64? Forces user session refresh if last login time is longer than time specified (seconds).
The OIDC display , preferred_locales , and acr_values are accepted for compatibility but are non-operational.
Returns
Because /oauth2/authorize is a website, there is no direct return value. However, after the user authorizes your app, they will be sent to your redirect URI. The type of response varies based on the response_type.
Code flow and PKCE flow
These parameters are passed in the query string (after the ? in the URL):
code String The authorization code, which can be used to attain a bearer token by calling /oauth2/token.
state String The state content, if any, originally passed to /oauth2/authorize.
Sample response
Token flow
These parameters are passed in the URL fragment (after the # in the URL).
Note: as fragments, these parameters can be modified by the user and must not be trusted server-side. If any of these fields are being used server-side, please use the PKCE flow, or alternatively using the fields returned from /get_current_account instead.
access_token String A token which can be used to make calls to the Dropbox API. This should always be treated as opaque with no guarantees as to the size or composition of this token.
token_type String The type of token, which will always be bearer.
account_id String A user’s account identifier used by API v2.
team_id String A team’s identifier used by API v2.
uid String Deprecated. The API v1 user/team identifier. Please use account_id instead, or if using the Dropbox Business API, team_id.
state String The state content, if any, originally passed to /oauth2/authorize.
Sample response
Errors
In either flow, if an error occurs, including if the user has chosen not to authorize the app, the following parameters will be included in the redirect URI:
error String An error code per Section 4.1.2.1 of the OAuth 2.0 spec.
error_description String A user-friendly description of the error that occurred.
state String The state content, if any, originally passed to /oauth2/authorize.
/oauth2/token
Description
This endpoint applies to apps using the authorization code flow or client credentials flow. An app calls this endpoint to acquire a refresh token and/or access token.
Calls to /oauth2/token need to be authenticated using the apps’s key and secret. These can either be passed as application/x-www-form-urlencoded POST parameters (see parameters below) or via HTTP basic authentication. If basic authentication is used, the app key should be provided as the username, and the app secret should be provided as the password.
URL Structure
Method: POST
Example: code flow access token request
Example: refresh token request
Example: app auth token request in client credentials flow
Example: PKCE code flow access token request
Example: PKCE refresh token request
Parameters
code String The code acquired by directing users to /oauth2/authorize?response_type=code.
grant_type String The grant type, which must be authorization_code for completing a code flow or refresh_token for using a refresh token to get a new access token, or client_credentials for using client credentials to get an app auth token. App auth tokens can only be used to call endpoints that use App Authentication, not User or Team Authentication.
refresh_token String? A unique, long-lived token that can be used to request new short-lived access tokens without direct interaction from a user in your app.
client_id String? If credentials are passed in POST parameters, this parameter should be present and should be the app’s key (found in the App Console).
client_secret String? If credentials are passed in POST parameters, this parameter should be present and should be the app’s secret.
redirect_uri String? The redirect URI used to receive the authorization code from /oauth2/authorize, if provided. Only used to validate it matches the redirect URI supplied to /oauth2/authorize for the current authorization code. It is not used to redirect again.
code_verifier String?(min_length=43, max_length=128) The client-generated string used to verify the encrypted code_challenge used in the Authorization URL.
scope String? Only allowed when grant_type=refresh_token, this parameter can be used to request a specific subset of the scopes originally granted for the supplied refresh token. Multiple scopes are separated by a space. If this parameter is omitted, the returned access token will include all of the scopes originally granted for the supplied refresh token.
refresh_token_expiration_seconds Integer? Only allowed when grant_type=authorization_code. The unix timestamp, in seconds, that the returned refresh token is valid until. If this parameter is omitted, the refresh token will be valid indefinitely, until revoked.
Returns
This endpoint returns a JSON-encoded dictionary including fields below:
When input grant_type=authorization_code:
access_token String The access token to be used to call the Dropbox API. This should always be treated as opaque with no guarantees as to the size or composition of this token.
expires_in Integer The length of time in seconds that the access token will be valid for.
token_type String Will always be bearer.
scope String The permission set applied to the token.
account_id String An API v2 account ID if this OAuth 2 flow is user-linked.
team_id String An API v2 team ID if this OAuth 2 flow is team-linked.
refresh_token String If the token_access_type was set to offline when calling /oauth2/authorize, then response will include a refresh token. This refresh token is long-lived and won’t expire automatically. It can be stored and re-used multiple times.
id_token String If the request includes OIDC scopes and is completed in the response_type=code flow, then the payload will include an id_token which is a JWT token.
uid String The API v1 identifier value. It is deprecated and should no longer be used.
Sample response
Example: short-lived token
Example: short-lived “offline” access token
Example: legacy long-lived access token
Example: OIDC request
When input grant_type=refresh_token:
Use the refresh token to get a new access token. This request won’t return a new refresh token since refresh tokens don’t expire automatically and can be reused repeatedly.
access_token String The access token to be used to call the Dropbox API.
expires_in Integer The length of time in seconds that the access token will be valid for.
token_type String Will always be bearer.
scope String? The permission set applied to the token. Only returned when the scope parameter was set.
Example: