Authorisation

iPayroll uses OAUTH2 Authorisation Code Grant. A user with the role of paymaster is required to authorise an external application to access their organisation in iPayroll via the API.

The following sequence diagram illustrates how the authorisation process works:

Request Permission

Before a third party application can make any API call, it needs the permission of a resource owner. Depending on types of data that the application is planning to access, it may request permission to access one or more scopes.

This is achieved by redirecting the browser that initiated the request (UserAgent) to iPayroll's authorisation endpoint.

Response type should always be code. It is an OAuth 2 specific parameter.

Client id is the unique identification of your application.

List of scopes that the application needs the resource owner to grant permission to. If multiple scopes are specified, separate them by a space.

Redirect URI is used for returning the control back (callback) to the application once authentication process completes.

State is an optional parameter that can be used to maintain a state, and is a reference to the request instance. The value passed would be returned back to the redirect URI when the callback is made.

Authorisation

The resource owner is required to authenticate itself to iPayroll in order to grant permission to an application. Therefore, https://<SERVER-DOMAIN>/oauth/authorize is a protected endpoint.

If the resource owner is not already logged in, iPayroll would redirect the user agent to the standard login page. But if already logged in, this step is skipped.

Once successfully authenticated, the following page is displayed asking for the resource owner's permission to grant access.

If the resource owner grants permission, the client application is notified via the callback URI.

Authorisation Code

Once resource owner's permission is granted, the redirect URI of the application is called passing authorisation code as a parameter:

https://<CALLBACK_URL>?code=<AUTH_CODE>&state=<STATE>

The response would also contain state, with the value originally passed on when making the authorisation request.

As HTTP redirect is used for making the callback, the redirect URI does not have to be a globally accessible one.

Re-authorisation

When a resource owner authorises an application, it is valid forever, unless the resource owner manually revokes the grant. Therefore, ideally, an application would only have to request for permission once.

However, if an application would want to request for scopes that are not already permitted, it could initialise another authentication request any time.

Request Tokens

Once the application receives the authentication code, it should request for tokens that could be used for making subsequent API calls by making the following HTTP POST request:

Once an application acquires tokens by passing an authorisation code, that code would be deleted. Subsequent calls with the same authorisation code would not return tokens. Therefore, it is client application's responsibility to hold onto tokens.

Access Token Expiry

The received access token can be used for making API calls till it expires. The system will return the following error when it expires:

The server would reply with the same response as the request tokens method.

Refresh Token Expiry

By default, refresh token is valid for 10 years. The value can be further increased if required. However, if the validity period of the refresh tokens is decreased, the application should handle expired refresh tokens.

When a new access token is requested passing a refresh token, server would reply back with the following error message if the refresh token is expired:

The client application should initiate a request tokens method to get a new refresh token. As this method expects a new authorisation code, the client application should first initiate a request permission call to get an authorisation code. Since a resource owner has already authorised the application, the grant permission page would be bypassed in this scenario.

Making Requests

API method calls expect the access token to be passed in with incoming requests.

One option is to use the standard HTTP authorization header:

Header: Authorization Value: <access_token>

The other option is to pass the access token as the value for request parameter access_token.

Token generation for development

When you are developing against our API in our demo environment, you may desire to generate a token without having to programmatically perform all of the steps outlined on this page. This can be achieved by using your normal web browser alongside a tool such as Postman, Restlet Client, or Insomnia. These instructions assume that you do not have an actual server to receive the callback, containing the code needed for getting a token, and are for development purposes only. When moving in to production, we recommend you set up an appropriate server to process the callbacks.

Start by ensuring that you are completely logged out from the iPayroll / CloudPayroll website in your web browser.

Combine your client id and scopes into a url for the authorize endpoint as per the Request Permission section above.

We suggest using a redirect_uri server of localhost, like the example above, with the assumption that it doesn't actually exist.

Copy the url, paste it in to your web browser of choice, and go to the page. This will take you to the iPayroll / CloudPayroll login page. You need to log in using a Paymaster user for the organisation that you want to use the API for.

If you have previously authorised the requested scopes, skip to step 5.Otherwise, if this is the first time you have used the API on this organisation, you will be presented with the Authorisation page (as described above). Confirm that the API scopes listed are what you expect and then click Authorize.

The website will now attempt to load your redirect uri that was provided in step 2. Because this server likely doesn't exist, your browser will show an error page. This is normal and expected. If you look in the address bar of the browser, you will see it looks something like:

http://localhost/?code=a1B2c3&state=1234

Copy the code portion of the address eg. a1B2c3.

Switch to one of the tools mentioned earlier (Postman, Restlet or Insomnia) as you cannot do this step inside your normal web browser. Using this application, you need to send a POST request as described in the Request Tokens section above.