Authentication Tutorial

Introduction

Tweepy supports both OAuth 1a (application-user) and OAuth 2 (application-only) authentication. Authentication is handled by the tweepy.AuthHandler class.

OAuth 1a Authentication

Tweepy tries to make OAuth 1a as painless as possible for you. To begin the process we need to register our client application with Twitter. Create a new application and once you are done you should have your consumer key and secret. Keep these two handy, you’ll need them.

The next step is creating an OAuthHandler instance. Into this we pass our consumer key and secret which was given to us in the previous paragraph:

auth = tweepy.OAuthHandler(consumer_key, consumer_secret)

If you have a web application and are using a callback URL that needs to be supplied dynamically you would pass it in like so:

auth = tweepy.OAuthHandler(consumer_key, consumer_secret,
callback_url)

If the callback URL will not be changing, it is best to just configure it statically on twitter.com when setting up your application’s profile.

Unlike basic auth, we must do the OAuth 1a “dance” before we can start using the API. We must complete the following steps:

  1. Get a request token from twitter
  2. Redirect user to twitter.com to authorize our application
  3. If using a callback, twitter will redirect the user to us. Otherwise the user must manually supply us with the verifier code.
  4. Exchange the authorized request token for an access token.

So let’s fetch our request token to begin the dance:

try:
    redirect_url = auth.get_authorization_url()
except tweepy.TweepError:
    print('Error! Failed to get request token.')

This call requests the token from twitter and returns to us the authorization URL where the user must be redirect to authorize us. Now if this is a desktop application we can just hang onto our OAuthHandler instance until the user returns back. In a web application we will be using a callback request. So we must store the request token in the session since we will need it inside the callback URL request. Here is a pseudo example of storing the request token in a session:

session.set('request_token', auth.request_token['oauth_token'])

So now we can redirect the user to the URL returned to us earlier from the get_authorization_url() method.

If this is a desktop application (or any application not using callbacks) we must query the user for the “verifier code” that twitter will supply them after they authorize us. Inside a web application this verifier value will be supplied in the callback request from twitter as a GET query parameter in the URL.

# Example using callback (web app)
verifier = request.GET.get('oauth_verifier')

# Example w/o callback (desktop)
verifier = raw_input('Verifier:')

The final step is exchanging the request token for an access token. The access token is the “key” for opening the Twitter API treasure box. To fetch this token we do the following:

# Let's say this is a web app, so we need to re-build the auth handler
# first...
auth = tweepy.OAuthHandler(consumer_key, consumer_secret)
token = session.get('request_token')
session.delete('request_token')
auth.request_token = { 'oauth_token' : token,
                         'oauth_token_secret' : verifier }

try:
    auth.get_access_token(verifier)
except tweepy.TweepError:
    print('Error! Failed to get access token.')

It is a good idea to save the access token for later use. You do not need to re-fetch it each time. Twitter currently does not expire the tokens, so the only time it would ever go invalid is if the user revokes our application access. To store the access token depends on your application. Basically you need to store 2 string values: key and secret:

auth.access_token
auth.access_token_secret

You can throw these into a database, file, or where ever you store your data. To re-build an OAuthHandler from this stored access token you would do this:

auth = tweepy.OAuthHandler(consumer_key, consumer_secret)
auth.set_access_token(key, secret)

So now that we have our OAuthHandler equipped with an access token, we are ready for business:

api = tweepy.API(auth)
api.update_status('tweepy + oauth!')

OAuth 2 Authentication

Tweepy also supports OAuth 2 authentication. OAuth 2 is a method of authentication where an application makes API requests without the user context. Use this method if you just need read-only access to public information.

Like OAuth 1a, we first register our client application and acquire a consumer key and secret.

Then we create an AppAuthHandler instance, passing in our consumer key and secret:

auth = tweepy.AppAuthHandler(consumer_key, consumer_secret)

With the bearer token received, we are now ready for business:

api = tweepy.API(auth)
for tweet in tweepy.Cursor(api.search, q='tweepy').items(10):
    print(tweet.text)