SSO Integration

Prerequisites

To facilitate SSO, you'll need an SSO secret, which is used with other parameters to construct a signature for each SSO request. The signature must be included in the URL of every SSO request.

Base URL

https://app.{your_private_label_domain}.com/sso

Required Parameters

company_external_identifier
user_external_identifier
timestamp
signature

Example SSO URL

https://app.employee-onboarding.com/sso?company_external_identifier=123&user_external_identifier=456&timestamp=2025-01-30T23%3A12%3A45%2B00%3A00&signature=a1b2c3d4e5f6

Signature

The signature is a SHA256 hash hexadecimal digest built from the following:

SSO Secret
Company External Identifier
User External Identifier
Timestamp
Role (optional)

Parameter Reference

`company_external_identifier`

Must be unique across your private label. Determines if the SSO user is:

Logged in or added to the company (if already associated)
Prompted to create a new company (if not found)

`user_external_identifier`

Must also be unique across your private label. Determines if the SSO user is:

Logged in (if already associated)
Prompted to create a new user (if not found)

`timestamp`

Must be in ISO8601 format
Must be within 5 minutes of the current time
Older timestamps will result in a 401 response (prevents replay attacks)

`role` (optional)

String value to control permissions and access:

Available options:
- admin
- employee
- manager
If a company is being created and role is omitted, admin will be applied (initial request)
If omitted and creating users on an existing company, role will default to employee (subsequent requests)
Must either be omitted completely from both the URL and signature, or explicitly set in both

Additional Parameters

You can pass extra parameters to pre-fill data only if a user or company is being created. These are ignored during simple logins.

Full parameter list and defaults can be found in the REST API documentation: