<< Back to Getting Started

Authentication

The REST API has a number of methods that require user authenticaiton to access or publish data. For instance, functionality on Twitter.com available to logged in users, such as submitting updates or downloading direct messages, are similarly protected through the API. The Search API has no notion of accounts and therefore requires no authentication. There are currently two techniques to authenticate with the REST API.

OAuth

Twitter made a big step in early 2009 by fully integrating the OAuth pattern of authentication into the REST API. OAuth is a token-passing mechanism that allows users to control which application have access to their data without giving away their passwords. More information on the OAuth specification can be found at oauth.net or in the excellent Beginner's Guide to OAuth from Hueniverse.

Registration for OAuth applications is available at http://twitter.com/oauth_clients.

Access tokens should never expire. An user's access token will be invalidated if the user explicitly revokes your application's authorization or if Twitter suspends your application. If your application is suspended there will be a note on your application page saying that it has been suspended. In either case, your application should be able to handle token revokation gracefully.

Many users trust an application to read their information but not necessarily change their name or post new statuses. OAuth permissions are granular, allowing applications and users to agree on Read-Only or Read-Write access. Updating information through the REST API, be it name, location or adding updating status, requires an HTTP POST. Any API method that requires an HTTP POST is considered a write method and requires Read-Write access.

Sign in with Twitter

OAuth permits sites to offer users a very seamless experience of login into a service using their Twitter account. With as little as one or two clicks, a user is able to connect their Twitter account with a third-party service, like your website. We call this Sign in with Twitter.

Desktop Clients

The traditional OAuth flow for desktop clients can be cumbersome. We've created a PIN-based experience for destkop clients that use the following flow:

1. The application uses oauth/request_token to obtain a request token from twitter.com.
2. The application directs the user to oauth/authorize on twitter.com.
3. After obtaining approval from the user, a prompt on twitter.com will display a 7 digit PIN.
4. The user is instructed to copy this PIN and return to the appliction.
5. The application will prompt the user to enter the PIN from step 4.
6. The application uses the PIN as the value for the oauth_verifier parameter in a call to oauth/access_token which will verify the PIN and exchange a request_token for an access_token.
7. Twitter will return an access_token for the application to generate subsequent OAuth signatures.

Examples and code for using OAuth >> 

Basic Auth

Basic Authentication sends user credentials in the header of the HTTP request. This makes it easy to use, but insecure. OAuth is the Twitter preferred method of authentication moving forward - come August 2010, we'll be turning off Basic Auth from the API.

Streaming API

Both basic authentication and OAuth are supported on the Streaming API, but User Streams requires OAuth. We haven't laid firm plans to disable basic authentication on the rest of the Streaming API.

<< Back to Getting Started