The steps below outline how to use the default Authorization Grant Type flow to obtain an access token and fetch a protected resource. In this example the provider is Google and the protected resource the user profile.
>>> client_id = r'your_client_id'
>>> client_secret = r'your_client_secret'
>>> redirect_uri = 'https://your.callback/uri'
# Note that these are Google specific scopes
>>> scope = ['https://www.googleapis.com/auth/userinfo.email',
'https://www.googleapis.com/auth/userinfo.profile']
>>> oauth = OAuth2Session(client_id, redirect_uri=redirect_uri,
scope=scope)
>>> authorization_url, state = oauth.authorization_url(
'https://accounts.google.com/o/oauth2/auth',
# access_type and approval_prompt are Google specific extra
# parameters.
access_type="offline", approval_prompt="force")
>>> print 'Please go to %s and authorize access.' % authorization_url
>>> authorization_response = raw_input('Enter the full callback URL')
>>> token = oauth.fetch_token(
'https://accounts.google.com/o/oauth2/token',
authorization_response=authorization_response,
# Google specific extra parameter used for client
# authentication
client_secret=secret)
>>> r = oauth.get('https://www.googleapis.com/oauth2/v1/userinfo')
>>> # Enjoy =)
There are four core work flows:
Certain providers will give you a refresh_token along with the access_token. These can be used to directly fetch new access tokens without going through the normal OAuth workflow. requests-oauthlib provides three methods of obtaining refresh tokens. All of these are dependant on you specifying an accurate expires_in in the token.
expires_in is a credential given with the access and refresh token indiciating in how many seconds from now the access token expires. Commonly, access tokens expire after an hour an the expires_in would be 3600. Without this it is impossible for requests-oauthlib to know when a token is expired as the status code of a request failing due to token expiration is not defined.
If you are not interested in token refreshing, always pass in a positive value for expires_in or omit it entirely.
>>> token = {
... 'access_token': 'eswfld123kjhn1v5423',
... 'refresh_token': 'asdfkljh23490sdf',
... 'token_type': 'Bearer',
... 'expires_in': '-30', # initially 3600, need to be updated by you
... }
>>> client_id = r'foo'
>>> refresh_url = 'https://provider.com/token'
>>> protected_url = 'https://provider.com/secret'
>>> # most providers will ask you for extra credentials to be passed along
>>> # when refreshing tokens, usually for authentication purposes.
>>> extra = {
... 'client_id': client_id,
... 'client_secret': r'potato',
... }
>>> # After updating the token you will most likely want to save it.
>>> def token_saver(token):
... # save token in database / session
This is the most basic version in which an error is raised when refresh is necessary but refreshing is done manually.
>>> from requests_oauthlib import OAuth2Session
>>> from oauthlib.oauth2 import TokenExpiredError
>>> try:
... client = OAuth2Session(client_id, token=token)
... r = client.get(protected_url)
>>> except TokenExpiredError as e:
... token = client.refresh_token(refresh_url, **extra)
... token_saver(token)
>>> client = OAuth2Session(client_id, token=token)
>>> r = client.get(protected_url)
This is the, arguably awkward, middle between the basic and convenient refresh methods in which a token is automatically refreshed, but saving the new token is done manually.
>>> from requests_oauthlib import OAuth2Session, TokenUpdated
>>> try:
... client = OAuth2Session(client_id, token=token,
... auto_refresh_kwargs=extra, auto_refresh_url=refresh_url)
... r = client.get(protected_url)
>>> except TokenUpdated as e:
... token_saver(e.token)
The third and recommended method will automatically fetch refresh tokens and save them. It requires no exception catching and results in clean code. Remember however that you still need to update expires_in to trigger the refresh.
>>> from requests_oauthlib import OAuth2Session
>>> client = OAuth2Session(client_id, token=token, auto_refresh_url=refresh_url,
... auto_refresh_kwargs=extra, token_updater=token_saver)
>>> r = client.get(protected_url)