PSOhub API - OAuth 2.0 Quickstart Guide

PSOhub supports the OAuth 2.0 Authorization Code grant type, which involves several steps:

1. The application opens a browser to send the user to the PSOhub OAuth 2.0 server

2. The user reviews the requested permissions, and grants access to the application

3. The user is redirected back to the application with an authorization code in the query string

4. The application sends a request to the OAuth 2.0 server to exchange the authorization code for an access token

Getting OAuth 2.0 tokens

Prerequisites

Before beginning the steps for using OAuth 2.0 with PSOhub, you should first:

1. Request an invite to the PSOHub API via Hello@psohub.com

2. Create an app within the developer portal

Step 1: Direct to PSOhub's OAuth 2.0 Server

When sending the user to PSOhub OAuth 2.0 server, first step is to create the authorization URL. This will identify your app, and define the resources that it's requesting access to on behalf of the user. The query parameters that you can pass as part of an authorization URL are shown below.

To start the OAuth 2.0 process, send the user to the authorization URL.

Example:

Using a server-side redirect:

// Build the auth URL const authUrl = 'https://www.psohubapp.com/link/apiauthorization' + `?clientid=${encodeURIComponent(CLIENT_ID)}` + `&scope=${encodeURIComponent(SCOPES)}` + `&redirecturl=${encodeURIComponent(REDIRECT_URI)}`; // Redirect the user return res.redirect(authUrl);

Using an HTML link:

<a href="https://www.psohubapp.com/link/apiauthorization?scope=projects%20timesheets&redirecturl=https://www.example.com/auth-callback&clientid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&clientsecret=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">Install</a>

Step 2: PSOhub prompts user for consent

PSohub displays a consent window to the user that shows the name of your app and a short description of each of the PSOhub API services that it's requesting permission to access. The user can then grant access to your app.

Your application doesn't do anything at this stage. When access has been granted, the PSOhub OAuth 2.0 server will send a request to the callback URL defined in the authorization URL.

Step 3: Handle the OAuth 2.0 server response

When the user has completed the consent prompt from step 3, the OAuth 2.0 server sends a GET request to the redirect URI specified in your authentication URL. If there are no issues and the user approves the access request, the request to the redirect URI will have a code query parameter attached when it's returned. If the user doesn't grant access, no request will be sent.

Example:

app.get('/oauth-callback', async (req, res) => { if (req.query.code) { // Handle the received code } });

Step 4: Exchange authorization code for tokens

After your app has received an authorization code from the OAuth 2.0 server, it can exchange the code for an access and refresh token by sending a URL-form encoded POST request to https://www.psohubapp.com/oauth/token with the values shown below.

Example:

const formData = { grant_type: 'authorization_code', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, code: req.query.code }; request.post('https://www.psohubapp.com/oauth/token', { form: formData }, (err, data) => { // Handle the returned tokens }

The body of the token response will be JSON data with the form:

{ "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1", "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I", "expires_in": 600 }

Now that you’ve completed the OAuth Authorization flow and retrieved an access token, you can make calls to PSOhub's API on behalf of the user. The next sections will go into detail on how to use the access token and how you can request a new one when it expires.

Using OAuth 2.0 tokens

Once the authorization code flow has been completed, your app is now authorized to make requests on behalf of the user. To do this, provide the token as a bearer token in the Authorization HTTP header.

request.get('https://www.psohubapp.com/rest/psohubapi/v1/project?limit=50', { headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );

Refreshing OAuth 2.0 tokens

OAuth access tokens will expire after a certain period of time. This is to make sure that if they are compromised, attackers will only have access for a short period. The token's lifespan (in seconds) is specified in the expires_in field when an authorization code is exchanged for an access token. To get a new access token, your app can exchange the received refresh token for a new access token by sending a URL-form encoded POST request to https://www.psohubapp.com/oauth/token with the following values:

Example

const formData = { grant_type: 'refresh_token', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, refresh_token: REFRESH_TOKEN }; request.post('https://www.psohubapp.com/oauth/token', { form: formData }, (err, data) => { // Handle the returned tokens }

The body of the token response will be JSON data with the form:

{ "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1", "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I", "expires_in": 600 }

The new access token can then be used to make calls on behalf of the user. When the new token expires, you can follow the same steps again to retrieve a new one.

• The default expiration time is 10min which is send back as 600 seconds

• If there is an error within the authentication flow we will send back an explicit error where we are seeing a problem so you can quickly solve it