OAuth.io

This add-on is operated by Oauth.io

OAuth made easy for 100+ providers

OAuth.io

Last updated July 27, 2023

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

OAuth.io is a dead simple OAuth solution that allows you to integrate the common API providers, with just three lines of JavaScript, completely abstracting away the complexity of OAuth integration.

By using OAuth.io, you are free to focus your attention on product development instead of losing time on API integration using OAuth.

Exhaustive: compatible with 100+ providers

OAuth.io works with all your favorite platforms, whether social (Facebook, Twitter, LinkedIn…) or SaaS (Mailchimp, Paypal, Stripe…).

Simplified API calls

With OAuth.io, you can make API calls instead of dealing with complex OAuth flows. Abstract tokens with the ‘Request API’ and get user info in a unified way, no matter which provider you are using. The API also lets you perform CRUD actions on behalf of users.

Secured encrypted API

OAuth.io lets you choose an authorization flow that fits your needs (client-side or server-side). It secures providers API access with SSL encryption and allows you to specify domains/url restrictions for more security.

Integrate in less than 90 seconds

Through the OAuth.io add-on, you can start adding OAuth providers to your Heroku app. You’ll then get a public key to start using these APIs right away.

Adding OAuth.io

You can add OAuth.io to your app either through the add-on catalog or through the CLI.

To select the free, Bootstrap plan (default):

$ heroku addons:create oauthio

To select another plan, (e.g. the Scalability plan for high-availability):

$ heroku addons:create oauthio:scalability

You can get the full list of plans in the Heroku add-on catalog.

Configuring the providers on OAuth.io

The OAuth.io key-manager can be accessed via the CLI:

$ heroku addons:open oauthio
Opening oauthio for sharp-mountain-4005...

or by visiting the Heroku Dashboard and selecting the application in question. Select oauthio from the Add-ons menu.

Once there, you should have an app already created and a screen that looks like this : oauthio-dashboard oauthio-app-page

To add a provider, click on the button and search for the one you want for your application. Then follow the instructions. If that’s not already done, you’ll need to access the provider’s website, create a developer account and create an app there.

You’ll usually need to specify a callback URL on the provider’s website, which must point to https://oauth.io/auth and the domain that must point to oauth.io. We already add by default your app’s domain. You then need to get the API key and the API secret. Once you have them, go back to oauth.io and fill the form. Feel free to repeat these steps for every provider you want to add to your app.

You can then try your API keys right away on OAuth.io by clicking on Try auth and debugging the response as needed. If everything is working by now, you are pretty close to success!

Getting your public key

The OAuth.io add-on adds the following config var to your Heroku app: OAUTHIO_PUBLIC_KEY.

Use the heroku config command to view your app’s config vars.

$ heroku config:get OAUTHIO_PUBLIC_KEY

Using OAuth.io

OAuth.io lets you choose an authorization flow that fits your needs (client-side or server-side). You can use OAuth.io either server-less or with the server-side flow if you don’t want to use APIs directly from the front-end, but rather through web-services inside your backend. Either you choose the server-side flow or the client-side flow, you will need to use one of our SDKs. Check out our Security Topics to help you make your choice.

Start playing directly from your front-end

We’ll use the JavaScript SDK and the client-side flow as an example here, but know that you can use other SDKs (Phonegap, iOS, Android for client-side and PHP and NodeJs for server-side). You can check out our Getting-Started guides to learn how to integrate those.

To use the JavaScript SDK, just copy the oauth.js script from the official GitHub repository and paste it in a OAuth.js file. (Linking directly from GitHub won’t work).

In the <head> of your HTML file, add a script link to the SDK.

<script src="/path/to/OAuth.js"></script>

In one of your JavaScript files, add this line to initialize OAuth.js with the public key of your app:

OAuth.initialize('<%= ENV["OAUTHIO_PUBLIC_KEY"] %>');

The exact details of how you access the OAUTHIO_PUBLIC_KEY environment variable will differ depending on your language and page rendering framework.

Token API - Authenticating the user

Add the following code (using Facebook as an example) to show a popup and retrieve the user’s credentials (the access token) from OAuth.io

//Using popup
OAuth.popup('facebook')
    .done(function(result) {
      //use result.access_token in your API request
      //or use result.get|post|put|del|patch|me methods (see below)
    })
    .fail(function (err) {
      //handle error with err
});

The popup method launches a popup over the app that asks the user to log in to Facebook and accept the permissions you set in your OAuth.io app. After the user accepts the permissions, the popup disappears, and the callback given in the .done() method is called with a result object as first argument.

The result object is what contains the access token. It also lets you perform API requests easily, as we will see in the next step. Note that here, we pass the result to a callback that is going to be called in the next step.

Requests API - Get data

You can manually make requests to the provider’s API with the access token you got from the popup/callback methods, or you can use the request methods stored in the result object.

GET Request

To make a GET request, you have to call the result.get method like this :

//Let's say the /me endpoint on the provider API returns a JSON object
//with the field "name" containing the name "John Doe"
OAuth.popup(provider)
.done(function(result) {
    result.get('/me')
    .done(function (response) {
        //this will display "John Doe" in the console
        console.log(response.name);
    })
    .fail(function (err) {
        //handle error with err
    });
})
.fail(function (err) {
    //handle error with err
});

Other Requests

Note that the result objects also contain the .get, .post, .put, .del and .patch methods that allow you to perform standard HTTP calls to the provider’s API endpoints. For more information and examples, check our API Reference.

User API - Me()

The me() request is an OAuth.io feature that allows you to retrieve a unified object describing the authenticated user. This method can be used for many providers, and will always return the same field names when they are available. That can be very useful when you need to login a user via several providers, but don’t want to handle a different response each time.

To use the me() feature, follow this example (which works for Facebook, Github, Twitter and many other providers) :

//provider can be 'facebook', 'twitter', 'github', or any supported
//provider that contain the fields 'firstname' and 'lastname'
//or an equivalent (e.g. "FirstName" or "first-name")
var provider = 'facebook';

OAuth.popup(provider)
.done(function(result) {
    result.me()
    .done(function (response) {
        console.log('Firstname: ', response.firstname);
        console.log('Lastname: ', response.lastname);
    })
    .fail(function (err) {
        //handle error with err
    });
})
.fail(function (err) {
    //handle error with err
});

The response object also contains a raw field, which contains the provider’s original response.

Filtering the results

You can filter the results of the me() method by passing an array of the fields that you need :

//...
result.me(['firstname', 'lastname', 'email'/*, ...*/])
//...

Migrating between plans

To migrate to a new plan on the OAuth.io add-on, you can either use the add-on catalog or the CLI command heroku addons:upgrade :

$ heroku addons:upgrade oauthio:scalability
-----> Upgrading oauthio:scalability to sharp-mountain-4005... done, v18 ($99/mo)
       Your plan has been updated to: oauthio:scalability

Removing the add-on

The OAuth.io add-on can be removed either through the add-on catalog or via the CLI command heroku command.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy oauthio
-----> Removing oauthio from sharp-mountain-4005... done, v20 (free)

Missing the provider you need?

Check out our wishlist if you want to use a provider that is not in our list!

Questions about security or OAuth flows

Check out our security topic, which will help you understand the oauth.io client-side flow and security concerns related to OAuth and our implementations.

Support

All OAuthio support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issue or product feedback is welcome at OAuth.io.

Feedback

Log in to submit feedback.