Authorizing a request

Overview

The purpose of this document is to show you how to modify HTTP requests for the purpose of sending authorized requests to the Twitter API.

All of Twitter’s APIs are based on the HTTP protocol. This means that any software you write which uses Twitter’s APIs sends a series of structured messages to Twitter’s servers. For example, a request to post the text “Hello Ladies + Gentlemen, a signed OAuth request!” as a Tweet will look something like this:

POST /1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.twitter.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21

Any HTTP library should be able to generate and issue the above request with a minimum of difficulty. However, the above request is considered invalid, since there is no way of knowing:

1. Which application is making the request
2. Which user the request is posting on behalf of
3. Whether the user has granted the application authorization to post on the user’s behalf
4. Whether the request has been tampered by a third party while in transit

To allow applications to provide this information, Twitter’s API relies on the OAuth 1.0a protocol. At a very simplified level, Twitter’s implementation requires that requests needing authorization contain an additional HTTP Authorization header with enough information to answer the questions listed above. A version of the HTTP request shown above, modified to include this header, looks like this (normally the Authorization header would need to be on one line, but has been wrapped for legibility here):

POST /1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Authorization: 
        OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog", 
              oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg", 
              oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D", 
              oauth_signature_method="HMAC-SHA1", 
              oauth_timestamp="1318622958", 
              oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb", 
              oauth_version="1.0"
Content-Length: 76
Host: api.twitter.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21

When this request was created, it would have been accepted by the Twitter API as valid, and in fact, created this tweet.

If this signing process sounds like it is beyond the scope of your integration, consider using Web Intents, which do not need to use OAuth to interact with the Twitter API.

Collecting parameters

You should be able to see that the header contains 7 key/value pairs, where the keys all begin with the string “oauth_”. For any given Twitter API request, collecting these 7 values and creating a similar header will allow you to specify authorization for the request. How each value was generated is described below:

Consumer key
The oauth_consumer_key identifies which application is making the request. Obtain this value from checking the settings page for your application on dev.twitter.com/apps.

Nonce
The oauth_nonce parameter is a unique token your application should generate for each unique request. Twitter will use this value to determine whether a request has been submitted multiple times. The value for this request was generated by base64 encoding 32 bytes of random data, and stripping out all non-word characters, but any approach which produces a relatively random alphanumeric string should be OK here.

Signature
The oauth_signature parameter contains a value which is generated by running all of the other request parameters and two secret values through a signing algorithm. The purpose of the signature is so that Twitter can verify that the request has not been modified in transit, verify the application sending the request, and verify that the application has authorization to interact with the user’s account.

The process for calculating the oauth_signature for this request is described in Creating a signature.

Signature method
The oauth_signature_method used by Twitter is HMAC-SHA1. This value should be used for any authorized request sent to Twitter’s API.

Timestamp
The oauth_timestamp parameter indicates when the request was created. This value should be the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages. Twitter will reject requests which were created too far in the past, so it is important to keep the clock of the computer generating requests in sync with NTP.

Token
The oauth_token parameter typically represents a user’s permission to share access to their account with your application. There are a few authentication requests where this value is not passed or is a different form of token, but those are covered in detail in Obtaining access tokens. For most general-purpose requests, you will use what is referred to as an access token. You can generate a valid access token for your account on the settings page for your application at dev.twitter.com/apps.

Version
The oauth_version parameter should always be 1.0 for any request sent to the Twitter API.

Building the header string

To build the header string, imagine writing to a string named DST.

1. Append the string “OAuth ” (including the space at the end) to DST.
2. For each key/value pair of the 7 parameters listed above:
   1. Percent encode the key and append it to DST.
   2. Append the equals character ‘=’ to DST.
   3. Append a double quote ‘”’ to DST.
   4. Percent encode the value and append it to DST.
   5. Append a double quote ‘”’ to DST.
   6. If there are key/value pairs remaining, append a comma ‘,’ and a space ’ ’ to DST.

Pay particular attention to the percent encoding of the values when building this string. For example, the oauth_signature value of tnnArxj06cWHq44gCs1OSKk/jLY= must be encoded as tnnArxj06cWHq44gCs1OSKk%2FjLY%3D.

Performing these steps on the parameters collected above results in the following string:

OAuth oauth_consumer_key="xvz1evFS4wEEPTGEFPHBog", oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg", oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1318622958", oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb", oauth_version="1.0"

This value should be set as the Authorization header for the request.