OAuth2 Authentication

Guides
1

In addition to HTTP Basic Authentication, The YourPayroll API also supports OAuth2 authentication.

Obtaining OAuth credentials

If you’d like to register an OAuth2 application, please send an email to support@yourpayroll.com.au with the following details:

  • The name of your application
  • The callback URL of your application
  • A logo image to be shown when your application requests permission

We’ll then provide you with a client id and client secret.

OAuth2 Details

Authorization URL: https://{yourwhitelabel}.yourpayroll.com.au/oauth/authorise
Access Token URL: https://{yourwhitelabel}.yourpayroll.com.au/oauth/token

Client Authorisation

To initiate the client authorisation process, your client should be redirected to https://{yourwhitelabel}.yourpayroll.com.au/oauth/authorise?client_id={your_client_id}&redirect_uri={your_redirect_uri}&response_type=code&state={your_state}

The following query string parameters are required:

  • client_id this should correspond to the client id provided above
  • redirect_uri this should correspond to the callback URL provided above. It may be any sub-path of the callback URL.
  • response_type this should always have a value of code
  • state this is an optional parameter. this should contain any information that you need to recover the context when the user returns to your application, e.g. the starting URL

Once the user allows access to your application, they will be redirected to redirect_uri specified above. The following parameters will be supplied in the query string:

  • code this code will be used to obtain a request token
  • state this is the state value that you specified in the authorise request

Exchange code for access token and refresh token

Using the code received from the oauth callback above, your application should then make a POST request to https://{yourwhitelabel}.yourpayroll.com.au/oauth/token to obtain your access tokens.

The following parameters are required:

  • code The authorization code that is returned from the initial request.
  • client_id The client ID that you were provided above in Obtaining OAuth credentials.
  • client_secret The client secret that you were provided above in Obtaining OAuth credentials.
  • redirect_uri The URI that you specified when requesting your OAuth credentials
  • grant_type This field must contain a value of authorization_code, as defined in the OAuth 2.0 specification.

A successful response contains the following fields in a JSON result similar to the following:

{
“access_token”:“7Rqk!IAAAAJMsgSSNnKJx1tIoboFApUYQudG7nYiYr7OuGdTmSBOU4QAAAA”,
“token_type”:“bearer”,
“expires_in”:86400,
“refresh_token”:“MpE-!IAAAAHyBWSC908zHY-39rhq76dojb4QEXeryTDAdjbQ0d3AFbBYmLWXXrdgPW”,
“scope”:“”
}

  • access_token a token that can be sent to the YourPayroll API
  • token_type At the moment, this field will always have a value of bearer
  • refresh_token this can be used to refresh your access token when it is near expiry
  • expires_in the duration that the access token is valid for

NOTE: that the access tokens are currently set to expire every 24 hours so it’s important to implement the access token refresh code too.

Refreshing an access token

To refresh an access token, make a POST request to https://{yourwhitelabel}.yourpayroll.com.au/oauth/token and pass the following information

  • refresh_token The refresh token received when exchanging the code for access token and refresh token above
  • client_id The client ID that you were provided above in Obtaining OAuth credentials.
  • client_secret The client secret that you were provided above in Obtaining OAuth credentials.
  • grant_type This field must contain a value of refresh_token, as defined in the OAuth 2.0 specification.

A successful response contains the following fields in a JSON result similar to the following:

{
“access_token”:“1/fFBGRNJru1FQd44AzqT3Zg”,
“expires_in”:86400,
“token_type”:“bearer”,
}

  • access_token a new access token to use. the old access token is now invalid
  • token_type At the moment, this field will always have a value of bearer
  • expires_in the duration that the access token is valid for

Making API Requests

Now that you have the client’s access token, all API requests should supply that token in the Authorization: HTTP header. For example:

GET /api/v2/user HTTP/1.1
Host: {yourwhitelabel}.yourpayroll.com.au
Authorization: Bearer 1/fFBGRNJru1FQd44AzqT3Zg