Single sign on (SSO) requests

Request for SSO URL that provides authenticated access to Employment Hero Payroll.

A successful SSO request will return a response object containing a SSO URL, which has a SSO token. Opening the SSO URL in a browser will open an authenticated session for the intended user.

Example success response:

{
    "url": "https://yourbrand.yourpayroll.com.au/Security/SSO?token=TUhoRGJ6SnhZbXRVWkVKM_TRUNCATED"
}

Notes about the generated SSO token:

  • a token is only valid for 5 minutes from the time it is generated
  • a token can only be used once
  • a user can only have one active token at any time

This page details the different usages of the SSO endpoints.

Endpoints and the request object

There are 3 SSO endpoints, each for a slightly different purpose, that take a POST request:

  • https://api.yourpayroll.com.au/api/v2/business/singlesignon
  • https://api.yourpayroll.com.au/api/v2/business/{businessId}/singlesignon
  • https://api.yourpayroll.com.au/api/v2/business/{businessId}/employee/{employeeId}/singlesignon

All of the above endpoints can take a common SSO request object:

{
    "businessId": "int32",
    "hostName": "string",
    "navigation": "string",
    "url": "string",
    "userName": "string"
}

Below are examples of usages in combinations of SSO endpoint and the request object with minimal properties specified.

Requesting SSO URL for API user

Note: This does not work for brand administrator because brand administrator is not allowed to logging in via SSO.

To request SSO URL for the API user (whose API key is in use), make a POST request to the https://api.yourpayroll.com.au/api/v2/singlesignon endpoint without a request object.

Example using curl:

curl -X POST -u API_KEY_HERE: https://api.yourpayroll.com.au/api/v2/singlesignon -d ""

Alternatively, to request SSO URL for one of the businesses the API user has access to, make a POST request to the https://api.yourpayroll.com.au/api/v2/business/{businessId}/singlesignon endpoint without a request object.

Example of endpoint, assuming the API user has access to businessId 152556:

https://api.yourpayroll.com.au/api/v2/business/152556/singlesignon

For the purpose of requesting SSO URL for the API user, the endpoints specified above also accept a request object with any of the following optional properties:

Example specifying the navigation property with curl in JSON format:

curl -X POST -u API_KEY_HERE: https://api.yourpayroll.com.au/api/v2/singlesignon \
--header 'Content-Type: application/json' \
--data-raw '{
    "navigation": "None"
}'

Requesting SSO URL for a specific user

Note: Generally, only brand administrator can request SSO URL for another user, and the brand administrator must have access to the requested business.

To request SSO URL for a user other than the API user (whose API key is in use), make a POST request to the https://api.yourpayroll.com.au/api/v2/singlesignon endpoint with a request object consisting of the following required properties:

  • businessId: required
  • hostName: optional
  • navigation: optional
  • url: optional
  • userName: required

To request SSO URL for user (userName payroll.admin@yourbusiness.com.au), POST the following request object:

{
    "businessId": "152556",
    "userName": "payroll.admin@yourbusiness.com.au"
}

Alternatively, POSTing the request object to the https://api.yourpayroll.com.au/api/v2/business/{businessId}/singlesignon endpoint will also work.

The request object specified above can be used to request SSO URL for the following types of business users:

  • full access users
  • managers (non-full access users with "Employee access" to the business)
  • report users (non-full access users with only "Report access" to the business)

When the requested user is a full access user, the following rules apply:

  • the user (userName) is an existing user
  • the user has access to the business (businessId)
  • the user cannot be a full access user for any business under any other brand

If the requested user is a manager, a report user or an employee, the following rules apply:

  • the user (userName) is an existing user
  • the user cannot be a full access user for any other business
  • depending on the user type of the requested user, one of the following:
    • employee - the user cannot have access to any other employee
    • manager - the user cannot have employee group access for any other business
    • report user - the user cannot have report access for any other business
Requesting SSO URL for employee

To request SSO URL for an employee, make a POST request to the https://api.yourpayroll.com.au/api/v2/business/{businessId}/employee/{employeeId}/singlesignon endpoint.

Example to access the employee portal for an employee (employeeId 30298, userName your.employee@yourbusiness.com.au):

curl -X POST -u API_KEY_HERE: https://api.yourpayroll.com.au/api/v2/business/152556/employee/30298/singlesignon \
--header 'Content-Type: application/json' \
--data-raw '{
    "businessId": "152556",
    "userName": "your.employee@yourbusiness.com.au"
}'

Specifying the url property in the request object

Oftentimes, it is desirable to show (i.e. redirect to) a specific Employment Hero Payroll page upon navigating to the generated SSO URL. This can be achived by specifying the url property of the request object.

For example, to show the Business Details page on SSO login, specify /Business/{businessId}/BusinessDetails as the value for the url property:

{
    "businessId": "152556",
    "userName": "payroll.admin@yourbusiness.com.au",
    "url": "/Business/152556/BusinessDetails"
}

The url value can be extracted from the URL of the corresponding Employment Hero Payroll page. In this case, the URL was extracted from https://yourbrand.yourpayroll.com.au/Business/152556/BusinessDetails