Authorizing a request¶
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.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:
- Which application is making the request
- Which user the request is posting on behalf of
- Whether the user has granted the application authorization to post on the user’s behalf
- 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.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.
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.
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:
oauth_consumer_keyidentifies which application is making the request. Obtain this value from checking the settings page for your application on apps.twitter.com.
oauth_nonceparameter 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.
oauth_signatureparameter 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.
oauth_signature_methodused by Twitter is
HMAC-SHA1. This value should be used for any authorized request sent to Twitter’s API.
oauth_timestampparameter 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.
oauth_tokenparameter 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.
oauth_versionparameter should always be
1.0for any request sent to the Twitter API.
Building the header string¶
To build the header string, imagine writing to a string named DST.
- Append the string “OAuth ” (including the space at the end) to DST.
- For each key/value pair of the 7 parameters listed above:
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
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.