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:
This page details the different usages of the SSO endpoints.
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.
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:
businessId
: exclude this propertyhostName
: optionalnavigation
: optional, see iFrame navigation for optionsurl
: optional, see Specifying the "url" propertyuserName
: exclude this propertyExample 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"
}'
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
: requiredhostName
: optionalnavigation
: optionalurl
: optionaluserName
: requiredTo 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, POST
ing 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:
When the requested user is a full access user, the following rules apply:
userName
) is an existing userbusinessId
)If the requested user is a manager, a report user or an employee, the following rules apply:
userName
) is an existing userTo 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"
}'
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
Powered by DapperDox