Authentication Tutorial

Introduction

Tweepy supports both basic and oauth authentication. Authentication is handled by tweepy.AuthHandler classes with two implementations provided:

  • OAuthHandler
  • BasicAuthHandler

Basic Authentication

Basic authentication uses the user’s Twitter username and password for authenticating with the API. You must query the user for these two pieces of infomation before we can authenticate.

Now first we must create an instance of the BasicAuthHandler and pass into it the username and password:

auth = tweepy.BasicAuthHandler(username, password)

Next we need to create our API instance which will be used for executing requests to the Twitter API:

api = tweepy.API(auth)

We are now ready to make API calls that are authenticated! Here is a quick example posting a new tweet to the authenticated user’s account:

api.update_status('hello from tweepy!')

OAuth Authentication

OAuth is a bit trickier than basic auth, but there are some advantages to using it:

  • You can set a ‘from myappname’ which will appear in tweets posted
  • More secure since you don’t need the user’s password
  • Your app does not break if the user changes their password in the future

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

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

auth = tweepy.OAuthHandler(consumer_token, 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_token, 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 “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.key,
auth.request_token.secret)

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.set_request_token(token[0], token[1])

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.key
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 equiped with an access token, we are ready for business:

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