You may have heard that OAuth 2.0 simplifies development and provides better support for mobile apps. That’s why we announced OAuth 2.0 on the Core API at DBX this week. Most of the official Core API SDKs include OAuth 2.0 support already, so the best way to take advantage of OAuth 2.0 in your app is to use one of those libraries.
That said, you can easily implement the protocol yourself if you need to. The Core API supports both the “code grant” (for apps with a server-side component like web apps) and the “implicit grant” (for client-side apps like mobile or JavaScript apps). Let’s dive in!
Using the code grant
Step 1: Begin authorization
Directing the user to a URL like the following:
https://www.dropbox.com/1/oauth2/authorize?client_id=<app key>&response_type=code&redirect_uri=<redirect URI>&state=<CSRF token>
You should use the state parameter to prevent cross-site request forgery (CSRF) attacks on your app. Our SDKs generate a CSRF token by base-64 encoding a secure 16-byte random number, and we store a copy in the user’s session.
After the user has authorized your app, they’ll be sent to your redirect URI, with a few query parameters:
https://www.example.com/mycallback?code=<authorization code>&state=<CSRF token>Your app should verify the CSRF token matches the one you previously generated and stored, and then pull out the authorization code to use in the next step.
Step 2: Obtain an access token
To convert the authorization code to an access token, call the /token endpoint. Here’s an example of calling this endpoint using curl:
curl https://api.dropbox.com/1/oauth2/token -d code=<authorization code> -d grant_type=authorization_code -d redirect_uri=<redirect URI> -u <app key>:<app secret>
The response will look like this:
{"access_token": "<access token>", "token_type": "Bearer", "uid": "<user ID>"}The access token is all you need to make calls to the Core API.
Step 3: Call the API
Now that you have an access token, you can call any method in the Core API by just attaching the following header:
Authorization: Bearer <access token>As an example, here’s how to use curl to get information about the user’s account:
curl https://api.dropbox.com/1/account/info -H "Authorization: Bearer <access token>"
Using the implicit grant
Step 1: Obtain an access token
Direct the user to a URL that looks like this:
https://www.dropbox.com/1/oauth2/authorize?client_id=<app key>&response_type=token&redirect_uri=<redirect URI>&state=<CSRF token>
After successful authorization, the user will be redirected to the specified redirect URI, with a few parameters in the URL fragment (after the hash):
https://www.example.com/mycallback#access_token=<access token>&token_type=Bearer&uid=<user ID>&state=<CSRF token>Your app should verify the CSRF token and pull out the access token to use in the next step.
Step 2: Call the API
Once you have an access token, making calls to the Core API is the same as in the code flow. Just use the Authorization: Bearer <access token> header.
