pykoauth2 is the smart oAuth2 client library.

The problem

Usually, when one wants to access an oAuth2 protected resource using Python, one has to,

  • Read up the documentation to find out the authorization and token endpoints for an Authorization Server.
  • Read up the documentation for the available scopes, and what URLs the authorization server applies to.
  • Write some amount of code (with or without an oAuth2 library) to generate an authorization request, somehow make a user use the web browser to fetch an authorization code, and then make another request to the authorization server to retrieve an access token. Access tokens, however, are short-lived, so more code has to be written to automatically refresh the tokens (if a refresh token grant is provided) to refresh an access token when it expires.

There are a lot of steps in this process, and a lot of boilerplate code has to be written. The problem is made worse by the fact that not all authorization servers implement the oAuth2 standard correctly. In fact, most of them do not conform to the specification. The worse offender is Facebook, by the way. (Also, Google takes the prize for implementing oAuth2 correctly. Thank you, Google engineers!)

pykoauth2 aims to remove the headache of making oAuth2 authorization and protected resource requests, by being smart.

  • pykoauth2 has an Authorization Server database where the endpoints, scopes, resources and workarounds for each Authorization Server is stored.
  • pykoauth2 provides database implementations which allow you to easily store access tokens, grants and client credentials.
  • A curl-like command line application pykoauth2curl is also provided. You use it just like you would use curl, but pykoauth2 will automatically apply the relevant access token stored in the database.


The following additional packages are required on Windows:

  • pywin32


Development Install

Clone the repository, then cd to the working directory and run:

dev.py install

This creates a development install. The installed python package, binaries and data files point to the cloned copy of the repository.


Here is how you can use pykoauth2 to use the Facebook Graph API.

Firstly, you must add your Client Credentials to the database. You only need to do this once. To get the Client Credentials, you must register an App in Facebook.


Ensure that the Site URL is http://localhost. (Tick the box "Website with facebook login"). Also ensure that "localhost" is listed in "App Domains".

You can then add the client credentials to the database with pykoauth2 addclient. The command has the format:


Hence, you would run the command:

pykoauth2 addclient facebook.com CLIENT_ID CLIENT_SECRET

replacing CLIENT_ID and CLIENT_SECRET with your "App ID" and "App Secret" of your app.

Secondly, you need to make an authorization request using your web browser. To do this, you use the pykoauth2 authcode command. It has the format:

pykoauth2 authcode SERVER_FQDN

Thus, to make an authorization request, run the command:

pykoauth2 authcode facebook.com

What happens is that by default, pykoauth2 will first run a webserver at http://localhost:8080. A URL will be printed on to the console. Copy and paste it into the web browser. Facebook will ask you to authorize your app. Authorize it, and your browser will redirect to http://localhost. Return back to the console window, and you should see that the command has exited. This means that the authorization request is successful, and you now have an AuthorizationCodeGrant in the database. This grant can be then exchanged for an AccessToken in the next step.


By default, if no scope is provided in pykoauth2 authcode, pykoauth2 will request for all scopes/permissions available in the Authorization Server. Therefore, you will see that the Facebook app authorization requests requests for quite a lot of permissions in your Facebook profile.


You must allow pykoauth2 to listen on the port 8080. If port 8080 is being used, you can specify a different port by providing a different redirect_uri. For example, to listen on port 1234, use pykoauth2 authcode --redirect-uri http://localhost:1234 facebook.com.

Thirdly, to exchange the AuthorizationCodeGrant for an AccessToken, use pykoauth2 token. It has the format:

pykoauth2 token --server_fqdn SERVER_FQDN

Hence, run the command:

pykoauth2 token --server_fqdn facebook.com

pykoauth2 will print out a list of grants in the database which belong in Facebook, and ask you which grant you would like to use to exchange for an Access Token, like so:

Grants found:
0 : <class 'pykoauth2.tokengrantdb.simple.AuthorizationCodeGrant'>
Select Grant:

In this case, enter 0 and press Enter. pykoauth2 should then exit successfully, meaning that it has successfully exchanged the grant for an Access Token and stored it in its database.

You can now use pykoauth2curl to make authenticated requests to Facebook. For example, the below command will post a message to your profile feed:

pykoauth2curl --data-urlencode 'message=Hello world from pykoauth2!' \

oAuth2 Provider Support

Currently the following oAuth2 providers are supported. Note that they are referred to by the Fully Qualified Domain Name (FQDN) of their Authorization Servers in pykoauth2. For example, to make an Authorization Code request to Google, you would use:

pykoauth2 authcode accounts.google.com

as accounts.google.com is the FQDN of the Google Authorization Server.

The list of oAuth2 providers (FQDN in brackets):

  • Google (accounts.google.com)
  • Facebook (facebook.com)
  • Github (github.com)