Skip to content

Getting started

Jump to bottom
Corentin edited this page May 25, 2020 · 25 revisions

This tutorial is intended for those interested in consuming OAuth based APIs, such as engineers and web developers, and how Pizzly makes it faster to integrate with a pre-configured list of APIs.

Objectives

  • Running Pizzly locally
  • Connect yourself to GitHub
  • Retrieve your GitHub accessToken
  • Make an authenticated request to GitHub API

Prerequisites

Running Pizzly on your machine

  1. Download the Pizzly source code:
git clone https://github.com/Bearer/Pizzly
  1. Change to the directory:
cd pizzly
  1. Install dependencies for the project (you can also use npm):
yarn install
  1. Start the local server:
yarn start
  1. View app in your browser by opening:
http://localhost:8080/

Connect yourself to GitHub

  1. On GitHub, create an OAuth application.
  2. Make sure to register the following url as the Authorization callback URL:
http://localhost:8080/auth/callback
  1. Open Pizzly dashboard and select the GitHub API:
http://localhost:8080/dashboard/github

  1. Click on "Save credentials" and fill the form with the following information:

    1. Use the "Client ID" / "Client Secret" provided by GitHub in step 2.
    2. For the scopes field, enter user.
    3. Save the form to save the credentials in the database.

  2. Open the following page in your browser and click on "Connect to GitHub":

http://localhost:8080/dashboard/github/connect

Tip: when you want to connect your users to an API, you don't need to repeat all these steps. Only the latest one (#7) is required. To learn more on how to connect users on your application, read the Pizzly's connect guide.

Retrieve your GitHub's accessToken

While you connected yourself to GitHub, Pizzly has created an authId. It's a reference that Pizzly uses to retrieve the OAuth payload, including the accessToken. Let's see how to retrieve the information associated with your authId.

  1. Grab the authId from the step #7 in the previous section. It's something similar to:
9170f2c0-8957-11ea-ad33-0bc14197b007
  1. Retrieve the OAuth payload with the following command:
curl "http://localhost:8080/api/github/authentications/REPLACE-WITH-YOUR-AUTH-ID"
  1. The response should look something similar to:
{
  "id":"9170f2c0-8957-11ea-ad33-0bc14197b007",
  "object":"authentication",
  "auth_id":"9170f2c0-8957-11ea-ad33-0bc14197b007",
  "user_attributes":{
    "connectParams":{},
    "serviceName":"github",
    "userId":"9170f2c0-8957-11ea-ad33-0bc14197b007",
    "updatedAt":1588081979214,
    "accessToken":"d7eexxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "refreshToken":"non",
    "idToken":"non",
    "expiresIn":0,
    "scopes":[],
    "tokenResponseJSON":"...",
    "callbackParamsJSON":"..."
  },
  "created_at":"2020-04-28T13:52:59.218Z",
  "updated_at":"2020-04-28T13:52:59.218Z"
}

Make an authenticated request to GitHub

The example below uses Node.js, as it's the main language of Pizzly, but the concept is applicable to any programming language.

const axios = require('axios')

const PIZZLY_INSTANCE = 'http://localhost:8080'
const authId = 'REPLACE-WITH-YOUR-AUTH-ID'

// 1. Fetch the OAuth payload for the provided authId
axios
  .get(PIZZLY_INSTANCE + '/api/github/authentications/' + authId)
  .then(({ data }) => {
    const { accessToken } = data.user_attributes

    // 2. Fetch authenticated user's profile on GitHub
    return axios
      .get('https://api.github.com/user', {
        headers: { Authorization: 'token ' + accessToken }
      })
      .then(({ data }) => console.log(data))
      .catch(console.error)
  })
  .catch(console.error)

This snippet does two requests:

  1. First, it fetch the OAuth payload from Pizzly to retrieve the accessToken;
  2. Then, it makes an authenticated request to GitHub using that accessToken.

To reduce the number of requests, your Pizzly instance can work as a proxy. Here's an example (in Node.js again):

const axios = require('axios')

const PIZZLY_INSTANCE = 'http://localhost:8080'
const authId = 'REPLACE-WITH-YOUR-AUTH-ID'

axios
  .get(PIZZLY_INSTANCE + '/proxy/github' + '/user', {
  	headers: { "Pizzly-Auth-Id": "" }
	})
	.then(({data}) => console.log(data))
	.catch(console.error)

From your application's point of view, this second snippet does only one (1) request, directly to the Pizzly instance. Behind the scene, here's what's happening:

  1. Pizzly receives the request and queries the database to retrieve the user's accessToken.
  2. It uses the accessToken to make an authenticated request to the GitHub API.
  3. And send the response back to your application.

There are two main benefit from using Pizzly as a proxy:

  • In case needed, Pizzly will automatically refresh the token before requesting the third-party API.
  • Use can use the Pizzly's JS client to query APIs right from your frontend

What's next?

Clone this wiki locally