Using OAuth in "PLAINTEXT" mode

Posted by Kannan Goundan on July 13, 2012

OAuth is the way every Dropbox API request is signed to verify the user and permission of the request. If you're using the API with one of our SDKs, then there's nothing for you to do; OAuth is already handled for you. However if that's not an option and you end up dealing with OAuth directly, here are some tips to make your life easier:

  • Use the "PLAINTEXT" mode of OAuth (definitely)
  • Don't use an OAuth library, just do it yourself (probably)

Why? OAuth 1.0 (which is what the Dropbox API uses) was designed to work over unencrypted HTTP, so it does a bunch of crypto to try and make things secure. However it's error-prone, and if you're using SSL, unnecessary.

Fortunately, OAuth 1.0 also has a "PLAINTEXT" mode specifically for SSL that is way simpler. It's so simple that it's probably less work to implement it yourself than to try and use an existing OAuth library. (OAuth libraries tend to provide an API that is the lowest common denominator of the different modes, which makes them unnecessarily complicated if you only want PLAINTEXT.)

Here's how to do it yourself (equivalent Python code here):

  1. Get a Dropbox API app key and secret from the My Apps page.
  2. Make an API call for a request token:

    POST https://api.dropbox.com/1/oauth/request_token

    Your HTTP request should have the following header:

    Authorization: OAuth oauth_version="1.0", oauth_signature_method="PLAINTEXT", oauth_consumer_key="<app-key>", oauth_signature="<app-secret>&"

    The response body will be a url-encoded string:

    oauth_token=<request-token>&oauth_token_secret=<request-token-secret>

    Parse out the request token and secret and save them somewhere.

  3. Have the user authorize your app. To do this, send the user's browser to:

    https://www.dropbox.com/1/oauth/authorize?oauth_token=<request-token>&oauth_callback=<callback-url>

    The callback-url is where Dropbox will redirect the user's browser when authorization is complete. Typically, this will be something like "https://yoursite.com/auth_complete". It's just a way for your app to know that the user has approved your app, so you can continue.

  4. Make a call to convert your request token into an access token:

    POST https://api.dropbox.com/1/oauth/access_token

    This token is what lets you make calls to the Dropbox API. Your HTTP request should have the following header:

    Authorization: OAuth oauth_version="1.0", oauth_signature_method="PLAINTEXT", oauth_consumer_key="<app-key>", oauth_token="<request-token>", oauth_signature="<app-secret>&<request-token-secret>"

    The response body will be a url-encoded string:

    oauth_token=<access-token>&oauth_token_secret=<access-token-secret>&uid=<user-id>

    Parse out the access token and secret and save them somewhere long-term. You no longer need the request token and secret.

  5. You can now make normal API requests. For example, let's get the user's account info:

    GET https://api.dropbox.com/1/account/info

    Your HTTP request should have the following header:

    Authorization: OAuth oauth_version="1.0", oauth_signature_method="PLAINTEXT", oauth_consumer_key="<app-key>", oauth_token="<access-token>, oauth_signature="<app-secret>&<access-token-secret>"

That's it. You can add the Authorization header in the same way to make any of the calls available in the API.