Authorization Guide

This guide shows you how to get a user’s authorization to access private data through the Web API.

Introduction

All the Yuvo API require authorization; that is, the company admin must have granted permission for an application to access the requested data. To prove that the company admin has granted permission, the request header sent by the application must include a valid access token.

As the first step towards authorization, you will need to register your application. That will give you a unique client ID and client secret key to use in the authorization flows.

Supported Authorization Flows

The Yuvo API currently supports two authorization flows:

• The Client Credentials flow allows you to get an access token by supplying your client credentials (client ID and secret key). This flow is used in server-to-server authentication.

  Note: With this access token you can create companies and push employee's data from your application. You get full update access to these companies data.

  You are responsible for obtaining authorization from your application's users before using this API. Access to any other company (already existing on Yuvo platform) data could only be done via Authorization Code

• The Authorization Code flow first gets a code then exchanges it for an access token and a refresh token once authorization has been granted by a company admin user. This token gives only access to that particular company data.

  Since the exchange uses your client secret key, you should make that request server-side to keep the integrity of the key. An advantage of this flow is that you can use refresh tokens to extend the validity of the access token.

  Note: This flow is only necessary for accessing Yuvo data not created by your application via Client Credentials. You will use this flow when an existing Yuvo account company admin will subscribe to your application and give it access to their existing Yuvo data.

Client Credentials Flow

The method authenticates your application requests to the Yuvo API. It gives you full create/update access to Yuvo companies data that were originally sent by your application. This flow is described in RFC-6749.

1. Your application requests authorization

The request is sent to the /api/token endpoint of the Accounts service:

POST https://api.yuvohub.com/oauth/token/

The request will include parameters in the request body:

The header of this POST request must contain the following parameter:

For example:

curl -H "Authorization: Basic ZjM4ZjAw...WY0MzE=" -d grant_type=client_credentials https://api.yuvohub.com/oauth/token/
{
   "access_token": "NgCXRKc...MzYjw",
   "token_type": "bearer",
   "expires_in": 3600,
}

2. Use the access token to access the Yuvo API

The access token allows you to make requests to the Yuvo API endpoints that do not require user authorization.

Authorization Code Flow

This method is suitable for long-running applications which the user logs into once. It provides an access token that can be refreshed. Since the token exchange involves sending your secret key, this should happen on a secure location, like a backend service, not from a client like a browser or mobile apps. This flow is described in RFC-6749.

1. Your application requests authorization

The authorization process starts with your application sending a request to the Yuvo OAuth Service. (The reason your application sends this request can vary: it may be a step in the initialization of your application or in response to some user action, like a button click.) The request is sent to the /authorize endpoint of the Accounts service:

GET https://api.yuvohub.com/oauth/authorize/

The request will include parameters in the query string:

A typical request looks like this:

GET https://api.yuvohub.com/oauth/authorize/?client_id=5fe01282e44241328a84e7c5cc169165&response_type=code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=34fFs29kd09

2. The user is asked to authorize access within the scopes

The Yuvo OAuth service presents details of the scopes for which access is being sought. If the user is not logged in, they are prompted to do so using their Yuvo credentials.

When the user is logged in, they are asked to authorize access to the data sets defined in the scopes.

3. The user is redirected back to your specified URI

After the user accepts (or denies) your request, the Yuvo OAuth service redirects back to the redirect_uri. For our example, this would be the address:

https://developers.yuvohub.com/callback/

If the user has accepted your request, the response query string contains the following parameters:

For example:

https://developers.yuvohub.com/callback/?code=NApCCg..BkWtQ&state=profile%2Factivity

If the user has not accepted your request or an error has occurred, the response query string contains the following parameters:

For example:

https://developers.yuvohub.com/callback/?error=access_denied&state=STATE

4. Your application requests refresh and access tokens

When the authorization code has been received, you will need to exchange it with an access token by making a POST request to the Yuvo OAuth Service, this time to its /api/token endpoint:

POST https://api.yuvohub.com/oauth/token/

The body of this POST request must contain the following parameters:

An alternative way of sending the client id and secret is as request parameters (client_id and client_secret) in the POST body, instead of sending them base64-encoded in the header.

5. The tokens are returned to your application

On success, the response from the Yuvo OAuth Service has the status code 200 OK in the response header, and the following JSON data in the response body:

An example cURL request and response from the token endpoint will look something like this:

curl -H "Authorization: Basic ZjM...zE=" -d grant_type=authorization_code -d code=MQCbtKe...44KN -d redirect_uri=https%3A%2F%2Fwww.foo.com%2Fauth https://api.yuvohub.com/oauth/token/
{
   "access_token": "NgCXRK...MzYjw",
   "token_type": "Bearer",
   "scope": "user-read-private user-read-email",
   "expires_in": 3600,
   "refresh_token": "NgAagA...Um_SHo"
}

6. Use the access token to access the Yuvo API

The access token allows you to make requests to the Yuvo API on a behalf of a user, for example:

curl -H "Authorization: Bearer NgCXRK...MzYjw" https://api.yuvohub.com/companies
{
    "name": ...,
    "uen_code": ...,
    "sector": ...,
    "entity_type": ...,
    "entity_sub_type": ...,
    "work_locations": ...,
    "departments": ...,
}

7. Requesting access token from refresh token

Access tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.

The request is sent to the token endpoint of the Yuvo OAuth Service:

POST https://api.yuvohub.com/oauth/token/

The body of this POST request must contain the following parameters:

The header of this POST request must contain the following parameter:

For example:

curl -H "Authorization: Basic ZjM4Zj...Y0MzE=" -d grant_type=refresh_token -d refresh_token=NgAagA...NUm_SHo https://api.yuvohub.com/oauth/token/
{
   "access_token": "NgA6ZcYI...ixn8bUQ",
   "token_type": "Bearer",
   "scope": "user-read-private user-read-email",
   "expires_in": 3600
}