> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.dropboxapi.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server. # Authorization Dropbox supports [OAuth 2.0](http://oauth.net) for authorizing API requests. Find out more in our [OAuth guide](/dropbox-api/docs/oauth). Authorized requests to the API should use an `Authorization` header with the value `Bearer `, where `` 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](https://developers.dropbox.com/oidc-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 `code` flow returns an authorization code via the optional `redirect_uri` callback which should then be converted into a bearer access token using the [`/oauth2/token` call](/dropbox-api/docs/get-started/authorization#oauth2token). This is the recommended flow for apps that are running on a server. * The `PKCE` flow is an extension of the code flow that uses dynamically generated codes instead of a `secret` to perform an OAuth exchange from public clients. The [PKCE flow](https://oauth.net/2/pkce/) 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 `token` or implicit grant flow returns the bearer token via the `redirect_uri` callback, 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](http://tools.ietf.org/html/rfc6749#section-1.3). For more info on the PKCE extension, see [RFC 7636](https://tools.ietf.org/html/rfc7636) 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](https://developers.googleblog.com/2016/08/modernizing-oauth-interactions-in-native-apps.html), to support users who sign in to Dropbox using their Google accounts. Learn about [the dropbox.com system requirements.](https://help.dropbox.com/desktop-web/system-requirements#web) **URL Structure** ```bash https://www.dropbox.com/oauth2/authorize ``` **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 ```bash https://www.dropbox.com/oauth2/authorize?client_id=&response_type=code ``` Example: Auth URL for code flow with offline token access type ```bash https://www.dropbox.com/oauth2/authorize?client_id=&token_access_type=offline&response_type=code ``` Example: Auth URL for PKCE code flow ```bash https://www.dropbox.com/oauth2/authorize?client_id=&response_type=code&code_challenge=&code_challenge_method= ``` **Parameters** **response\_type** *String* The grant type requested, either `token` or `code`. **client\_id** *String* The app's key, found in the [App Console](https://www.dropbox.com/developers/apps). **redirect\_uri** *String?* Where to redirect the user after authorization has completed. This must be the exact URI registered in the [App Console](https://www.dropbox.com/developers/apps); 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](https://www.dropbox.com/developers/apps). 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](/dropbox-api/docs/oauth). **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`](/dropbox-api/docs/get-started/authorization#oauth2token) 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](http://tools.ietf.org/html/rfc6819#section-4.4.1.8) and [4.4.2.5](http://tools.ietf.org/html/rfc6819#section-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`](/dropbox-api/docs/get-started/authorization#oauth2token) 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](https://www.dropbox.com/help/31), Dropbox will direct users to a translated version of the authorization website. Locale tags should be [IETF language tags](http://en.wikipedia.org/wiki/IETF_language_tag). **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`](/dropbox-api/docs/get-started/authorization#oauth2token). `state` *String* The state content, if any, originally passed to `/oauth2/authorize`. **Sample response** ```json [REDIRECT_URI]?code=ABCDEFG&state=[STATE] ``` ### 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`](/dropbox-api/api-reference/user-endpoints/users/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** ```json [REDIRECT_URI]#access_token=ABCDEFG&token_type=bearer&account_id=dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc&uid=12345&state=[STATE] ``` **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](http://tools.ietf.org/html/rfc6749#section-4.1.2.1). `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](/dropbox-api/docs/get-started/authorization#oauth2authorize) 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](https://en.wikipedia.org/wiki/Basic_access_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** ```bash https://api.dropboxapi.com/oauth2/token ``` **Method:** POST Example: code flow access token request ```bash curl https://api.dropbox.com/oauth2/token \     -d code= \     -d grant_type=authorization_code \     -d redirect_uri= \     -d client_id= \     -d client_secret= ``` Example: refresh token request ```bash curl https://api.dropbox.com/oauth2/token \     -d grant_type=refresh_token \     -d refresh_token= \     -d client_id= \     -d client_secret= ``` Example: app auth token request in client credentials flow ```bash curl https://api.dropbox.com/oauth2/token \     -d grant_type=client_credentials \     -d client_id= \     -d client_secret= ``` Example: PKCE code flow access token request ```bash curl https://api.dropbox.com/oauth2/token \     -d code= \     -d grant_type=authorization_code \     -d redirect_uri= \     -d code_verifier= \     -d client_id= ``` Example: PKCE refresh token request ```bash curl https://api.dropbox.com/oauth2/token \     -d grant_type=refresh_token \     -d refresh_token= \     -d client_id= ``` **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](https://www.dropbox.com/developers/apps)). `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 ```json {   "access_token": "sl.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",   "expires_in": 14400,   "token_type": "bearer",   "scope": "account_info.read files.content.read files.content.write files.metadata.read",   "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",   "uid": "12345" } ``` Example: short-lived "offline" access token ```json {   "access_token": "sl.u.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",   "expires_in": 14400,   "token_type": "bearer",   "scope": "account_info.read files.content.read files.content.write files.metadata.read",   "refresh_token": "nBiM85CZALsAAAAAAAAAAQXHBoNpNutK4ngsXHsqW4iGz9tisb3JyjGqikMJIYbd",   "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",   "uid": "12345" } ``` Example: legacy long-lived access token ```json {   "access_token": "7rBynGOob1cAAAAAAAAAAe72L3T6rQK5ImB5a06ijnwRG9IdeTxvsqdZNAIxq8pZ",   "token_type": "bearer",   "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",   "uid": "12345" } ``` Example: OIDC request ```json {   "access_token": "sl.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",   "expires_in": 14400,   "token_type": "bearer",   "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkRUVXpsY3Nw",   "scope": "account_info.read files.content.read files.content.write files.metadata.read",   "account_id": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",   "uid": "12345" } ``` ### 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: ```json {   "access_token": "sl.u.AbX9y6Fe3AuH5o66-gmJpR032jwAwQPIVVzWXZNkdzcYT02akC2de219dZi6gxYPVnYPrpvISRSf9lxKWJzYLjtMPH-d9fo_0gXex7X37VIvpty4-G8f4-WX45AcEPfRnJJDwzv-",   "expires_in": 14400,   "token_type": "bearer" } ```