KeyPay API Reference

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)[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: The access tokens are currently set to expire every 24 hours, so it's important to implement the access token refresh code as well.

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.