When making API calls to the Dropbox API, each request requires a certain level of authentication. If you're using an official Dropbox SDK, it will handle these specifics for you. If you're using the HTTP endpoints however, you'll need to implement the right authentication type for each endpoint. The documentation for each endpoint indicates which type is used, which will be one of the following:
This is the most common authentication type. This type uses an access token for a specific user and app pair, in order to operate on that user's account, to the extent allowed by that app's permission. Applications that authorize only scopes for the User API will receive a user access token.
curl -X POST "https://api.dropboxapi.com/2/users/get_current_account" \ --header "Authorization: Bearer <OAUTH2_ACCESS_TOKEN>"
This type uses an access token for a specific team and app pair, in order to operate on that team, to the extent allowed by that app's permissions. Applications that authorize team scopes to use the Business API will receive a team access token.
curl -X POST "https://api.dropboxapi.com/2/team/get_info" \ --header "Authorization: Bearer <OAUTH2_ACCESS_TOKEN>"
Team access tokens can be used for calls requiring User Authentication by including additional HTTP headers. Note that applications using Select-User or Select-Admin headers must have a team_data.member
scope applied to the access token. This dependency is enforced in the scoped app's Permissions page and OAuth flow.
This type uses an access token for a specific team and app pair in conjunction with a header specifying the target team_member_id
, in order to operate on behalf of the team member, to the extent allowed by that app's permission. All API calls that support User Authentication support this methodology.
curl -X POST "https://api.dropboxapi.com/2/users/get_current_account" \ --header "Authorization: Bearer <OAUTH2_ACCESS_TOKEN>" \ --header "Dropbox-API-Select-User: <TEAM_MEMBER_ID>"
An additional error may occur when using Dropbox-API-Select-User
:
401
Member ID doesn't exist on the team.This type uses an access token for a specific team and app pair in conjunction with a header specifying the target team_member_id
, in order to operate on behalf of the team administrator, to the extent allowed by that app's permission.
When using Admin Authentication, the specified team_member_id
must refer to a team administrator. Whereas Dropbox-API-Select-User
enables acting on behalf of a team member, Dropbox-API-Select-Admin
to enables access to & operations on any team owned content.
Specifically, there are two different modes for Dropbox-API-Select-Admin
header that calls may support:
In general, Whole Team is supported by read-only endpoints in order to simplify referring to and traversing team-owned content: a caller can specify an admin, rather than determining the member with access with Dropbox-API-Select-User
.
Conversely, Team Admin is supported by mutable calls in order to perform particular actions an administrator (rather than user) - which may be a required permission for some operations within team spaces.
Not all User Authentication calls support this admin mode; refer to the API documentation of the given method.
curl -X POST "https://api.dropboxapi.com/2/users/get_current_account" \ --header "Authorization: Bearer <OAUTH2_ACCESS_TOKEN>" \ --header "Dropbox-API-Select-Admin: <TEAM_MEMBER_ID>"
This type only uses the app's own app key and secret, and doesn't identify a specific user or team. The app key and secret are transmitted in place of a username and password using "HTTP basic access authentication".
When supplying the app key and secret for App Authentication, the app key and secret are given in place of the HTTP username and password, respectively. This can be done either as separate strings, as shown in the first two examples below, or as an base64-encoded Basic
authorization string in the Authorization
header, as in the third example below.
curl -X POST "https://content.dropboxapi.com/2/files/get_thumbnail_v2" -u "<APP_KEY>:<APP_SECRET>" \ --header "Dropbox-API-Arg: {\"resource\": {\".tag\": \"link\", \"url\": \"https://www.dropbox.com/s/u0bdwmkjmqld9l2/dbx-supporting-distributed-work.gif?dl=0\"},\"format\": \"jpeg\",\"size\": \"w64h64\",\"mode\": \"strict\"}"
curl -X POST "https://<APP_KEY>:<APP_SECRET>@content.dropboxapi.com/2/files/get_thumbnail_v2" \ --header "Dropbox-API-Arg: {\"resource\": {\".tag\": \"link\", \"url\": \"https://www.dropbox.com/s/u0bdwmkjmqld9l2/dbx-supporting-distributed-work.gif?dl=0\"},\"format\": \"jpeg\",\"size\": \"w64h64\",\"mode\": \"strict\"}"
curl -X POST "https://content.dropboxapi.com/2/files/get_thumbnail_v2" \ --header "Authorization: Basic <base64(APP_KEY:APP_SECRET)>" \ --header "Dropbox-API-Arg: {\"resource\": {\".tag\": \"link\", \"url\": \"https://www.dropbox.com/s/u0bdwmkjmqld9l2/dbx-supporting-distributed-work.gif?dl=0\"},\"format\": \"jpeg\",\"size\": \"w64h64\",\"mode\": \"strict\"}"
To produce the encoded string in the last example, you would base64 encode the app key and app secret, separated by a :
. For example, if your app key was aaaaaaaaaaaaaaa
, and your app secret was bbbbbbbbbbbbbbb
, you would base64 encode aaaaaaaaaaaaaaa:bbbbbbbbbbbbbbb
, resulting in YWFhYWFhYWFhYWFhYWFhOmJiYmJiYmJiYmJiYmJiYg==
.
A small number of API calls do not require authentication, as they require a specific parameter value previously provided by Dropbox, and return limited information.
curl -X POST "https://notify.dropboxapi.com/2/files/list_folder/longpoll" \ --header "Content-Type: application/json" \ --data "{\"cursor\": \"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\",\"timeout\": 30}"