Skip to main content
Custom authentication lets you connect your own identity provider to Cadana so users can access your white-label app without creating separate Cadana credentials. Users log into your system, and you exchange their JWT for a Cadana session — a seamless Single Sign-On (SSO) experience. This is the standard approach for White-Label UI integrations where Cadana hosts a fully branded web app on your subdomain (e.g., payroll.yourcompany.com).

​
Prerequisites

1

JWT-compliant auth system

Your identity provider must issue standard JWTs and expose a JWKS (JSON Web Key Set) endpoint for signature verification. Cadana supports popular providers including Auth0, AWS Cognito, and Stytch. Custom engines are also supported — contact your account manager to confirm compatibility.
2

API key from Dashboard

Get your API key from the Cadana Dashboard. See Authentication for details.
3

White-label platform configured

You need a white-label setup with a custom domain (or use the default Cadana domain).
Any custom authentication engine must be ISO and SOC 2 compliant to ensure security and compatibility with Cadana’s platform.

​
How It Works

  1. User logs in to your application
  2. You issue a JWT with the user’s identity
  3. You exchange the JWT with Cadana for a one-time redirect token
  4. You redirect the user to the branded white-label app with the token
  5. Cadana validates the token and establishes an active session

​
Step 1: Configure SSO Settings

Configure the following settings for your platform:
SettingDescriptionExample
Auth Issuer (ISS)Your identity provider’s issuer URLhttps://auth.yourcompany.com
JWKS EndpointURL where Cadana fetches your public keyshttps://auth.yourcompany.com/.well-known/jwks.json
Login URLWhere Cadana redirects when a session expireshttps://yourcompany.com/login
Logout URLWhere Cadana redirects when a user logs outhttps://yourcompany.com/logout
SSO settings are currently configured with the help of your Cadana account manager. Self-service configuration in the Dashboard is coming soon.
Cadana uses the ISS and JWKS endpoint to validate and decode your JWTs. Your auth engine must be able to mint standard JWTs and expose verification metadata at the JWKS endpoint.

​
Step 2: Create the User with SSO

When onboarding a user who will access the white-label app via SSO, first create their Person and User records. See Onboard Workers for the full Person creation flow. Once the Person exists, create the User with POST /v1/users/invite. Set suppressWelcomeEmail to true so they don’t receive the default Cadana sign-up email — they’ll log in through your system instead.
bash
curl -X POST 'https://api.cadanapay.com/v1/users/invite' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
Step 3: Attach Your Auth ID to the User

For every user, attach your internal auth identifier as the sub (subject) on their Cadana User record. This is the critical step that ties your identity system to Cadana’s. Use PUT /v1/users/{userId}/sub with the tokenSub field set to your internal user ID — the same value that appears in the sub claim of your JWTs.
bash
curl -X PUT 'https://api.cadanapay.com/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sub' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Returns 204 on success.
The tokenSub value must exactly match the sub claim in the JWTs you issue for this user. If they don’t match, the token exchange in the next step will fail.

​
Step 4: Exchange JWT for Redirect Token

When a user needs to access the white-label app, exchange their JWT for a Cadana redirect token using POST /v1/auth/login/jwt.
bash
curl -X POST 'https://api.cadanapay.com/v1/auth/login/jwt' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Response: 
{
  "redirectToken": "eybzym7hwk..."
}

​
JWT Requirements

Your JWT must include these claims:
ClaimRequiredDescription
issYesIssuer — must match the Auth Issuer you configured in Step 1
subYesSubject — the user’s unique ID, must match the tokenSub you attached in Step 3
expYesExpiration timestamp
iatYesIssued-at timestamp
The JWT header must include a kid (Key ID) field. The kid must exactly match a key in your JWKS endpoint so Cadana can verify the signature.

​
Step 5: Redirect to the White-Label App

Use the redirect token to send the user to the white-label app. The token is one-time use — once consumed, it establishes an active session. Default Cadana domain: 
https://app.cadanapay.com/login?redirectToken={{redirectToken}}
Custom domain: 
https://payroll.yourcompany.com/login?redirectToken={{redirectToken}}
Once the user lands on this URL, Cadana exchanges the redirect token for an active session. The user gets full access to the branded white-label app without any additional login.

​
Session Management

Cadana manages session lifecycle automatically. When a session event occurs, Cadana redirects the user to the URLs you configured in Step 1:
EventRedirect destination
Session expiresYour Login URL — user re-authenticates and you repeat the JWT exchange
User logs outYour Logout URL — handle cleanup in your app

​
Full Integration Example

Here’s the complete flow for onboarding a user and enabling SSO access:

​
Next Steps

Custom Domain

Set up a custom domain for the white-label app

Onboard Workers

Create Person and User records

White-Label UI Overview

Customize the white-label app for your brand