<< 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 and difficult to track.

OAuth is the Twitter preferred method of authentication moving forward. While we have no plans in the near term to require OAuth, new applications should consider it best practice to develop for OAuth.  We eventually would like to suspend Basic Auth support. However we realize that Basic Auth has been a large part of the API's success, and that the barrier to entry if OAuth is the only solution is substantially higher. Many applications rely on Twitter accounts as their means of account management. Additionally, Basic Auth allows a developer with a command line, cURL, and his account credentials to start poking at Twitter data. There are still a number of archetectural use cases to work through before we consider the deprication of Basic Auth. Before any changes begin to happen, we will discuss them with the community through the support channels, and give at least 6 months lead time before making any policy changes.

<< Back to Getting Started