Last Updated:
White-label Members Portal
Audience: Engineering leads and security reviewers implementing redirect-based portal access. Members land on CCA's branded booking site already signed in. CCA owns the booking experience; the integration partner mints a one-shot token and redirects the browser.
About This Integration
Token-Based Authentication lets an external integration partner platform sign members into the CCA White-label Members Portal using a one-shot encrypted token. CCA validates the token, creates or updates the member profile, opens a session, and lands them on the correct organization experience.
This flow is separate from the Intake and Scheduling API. Integration Partners integrate through a browser redirect. Integration Partners mint the token on their servers; the CCA application calls the token-exchange API after redirect, so integration partners do not call that API directly in production.
Setup
- Receive environment URLs, issuer and audience claim values, the entry
url_slug, acompany_codefor each organization, the 256-bit shared secret, and any redirect slug allow-list from CCA. - Store the shared secret in a server-side secrets manager. Treat it as a production credential.
- Implement server-side token minting using the nested JWE/JWS format.
- Redirect the member to the entry URL with
tokenand optionalredirect_url. - Complete the sandbox testing checklist before production cutover.
What CCA Provisions Before Go-Live
| Item | Description |
|---|---|
| Integration Partner configuration | Integration Partner code, issuer and audience claim values, and the fallback_login_url registered on the integration partner record. |
| Shared secret | A 256-bit base64url-encoded value delivered securely. Sandbox and production use different secrets. |
| Organization enrollment | The entry url_slug and a company_code for each target organization. One entry can cover multiple organizations. |
| Environment URLs | White-label base URL per environment and expected iss and aud values. |
| Redirect slugs | Optional allow-listed deep-link slugs. |
End-User Flow
- The integration partner server mints a nested JWE(JWS) with member claims using the shared secret.
- The integration partner redirects the member's browser to
/go/{url_slug}/token?token=.... - The CCA application removes sensitive query parameters from the visible URL and calls the token-exchange API.
- CCA decrypts and verifies the token, enforces the one-time
jti, and creates or updates the member. - CCA returns the member and Bearer token; the application opens the session and navigates to the organization home or an allow-listed redirect.
- On failure, the member is sent to the
fallbackUrlfrom the error response.
Session lifetime. The integration partner token is single-use and short-lived; it only bootstraps login. CCA then issues a Bearer JWT session valid for 14 days. Integration Partners do not need to refresh or re-mint tokens during that session.
Entry URL
Redirect the member's browser to:
{WHITE_LABEL_BASE_URL}/go/{url_slug}/token?token={JWE}[&redirect_url={slug}]| Placeholder | Description |
|---|---|
{WHITE_LABEL_BASE_URL} | CCA-provided White-label host for the target environment. |
{url_slug} | The assigned entry slug. The company_code claim selects the member's organization. |
{JWE} | Compact nested token. |
{slug} | Optional allow-listed redirect slug. |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
token | Yes | Compact nested JWE string. |
redirect_url | No | Allow-listed post-login deep-link slug. |
https://{white-label-host}/go/{url_slug}/token?token={JWE}
https://{white-label-host}/go/{url_slug}/token?token={JWE}&redirect_url=text-coaching-request- Always use the assigned entry
url_slugin the path. The requiredcompany_codeselects the exact organization. - Omit
redirect_urlto use the organization's default experience. - If
tokenis missing, the member is sent to login with a generic SSO failure reason.
Sample Code
These examples build the inner JWS, wrap it in the outer JWE, and return a compact token ready for the entry URL. Fill in the values CCA provides and the per-login member fields.
Python
Using jwcrypto:
import json
import time
import uuid
from jwcrypto import jwe, jwk, jws
def mint_cca_sso_token(shared_secret_b64url, issuer, audience,
company_code, member, ttl_seconds=280):
key = jwk.JWK(kty="oct", k=shared_secret_b64url)
now = int(time.time())
claims = {
"iss": issuer,
"aud": audience,
"iat": now,
"exp": now + ttl_seconds,
"jti": str(uuid.uuid4()),
"email": member["email"],
"company_code": company_code,
"first_name": member["first_name"],
"last_name": member["last_name"],
"country": member["country"],
"preferred_language": member["preferred_language"],
}
for optional in ("external_id", "sub"):
if optional in member:
claims[optional] = member[optional]
inner = jws.JWS(json.dumps(claims).encode())
inner.add_signature(
key,
alg="HS256",
protected=json.dumps({"alg": "HS256", "typ": "JWT"}),
)
inner_compact = inner.serialize(compact=True)
outer = jwe.JWE(
inner_compact.encode(),
protected=json.dumps({"alg": "dir", "enc": "A256GCM", "cty": "JWT"}),
)
outer.add_recipient(key)
return outer.serialize(compact=True)Node.js
Using jose:
import { SignJWT, CompactEncrypt, base64url } from 'jose';
import { randomUUID } from 'node:crypto';
export async function mintCcaSsoToken({
sharedSecretB64url, issuer, audience, companyCode, member,
ttlSeconds = 280,
}) {
const key = base64url.decode(sharedSecretB64url);
const now = Math.floor(Date.now() / 1000);
const claims = {
email: member.email,
company_code: companyCode,
first_name: member.firstName,
last_name: member.lastName,
country: member.country,
preferred_language: member.preferredLanguage,
};
if (member.sub) claims.sub = member.sub;
if (member.externalId) claims.external_id = member.externalId;
const innerJws = await new SignJWT(claims)
.setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
.setIssuer(issuer)
.setAudience(audience)
.setIssuedAt(now)
.setExpirationTime(now + ttlSeconds)
.setJti(randomUUID())
.sign(key);
return await new CompactEncrypt(new TextEncoder().encode(innerJws))
.setProtectedHeader({ alg: 'dir', enc: 'A256GCM', cty: 'JWT' })
.encrypt(key);
}Other languages can use equivalent JOSE libraries with the same oct key and HS256, dir, and A256GCM settings.
Token Format
Tokens are a nested JWT: an inner JWS containing HMAC-signed claims wrapped in an outer JWE using direct symmetric encryption. Both layers use the same per-partner 256-bit shared secret.
Algorithms
| Layer | Field | Value |
|---|---|---|
| Inner JWS | alg | HS256 |
| Inner JWS | typ | JWT |
| Outer JWE | alg | dir |
| Outer JWE | enc | A256GCM |
| Outer JWE | cty | JWT |
CCA rejects every other algorithm combination. There is no negotiation, and alg: none is not accepted.
Key Material
There is one key per integration partner per environment. Use the same raw 256-bit secret for the inner HS256 signature and the outer dir/A256GCM encryption. No kid header is required; CCA resolves the integration partner from the redirect path's url_slug.
When using a JWK, represent the secret as {"kty":"oct","k":"<base64url-secret>"}.
Required Claims
| Claim | Type | Description |
|---|---|---|
iss | string | Must match the issuer configured by CCA. |
aud | string | Must match the configured audience for the environment. |
iat | number | Issued-at time in Unix seconds. |
exp | number | Expiry in Unix seconds; exp - iat must not exceed 300 seconds by default. |
jti | string | Fresh UUIDv4 token identifier; single-use across all integration partner URL slugs. |
email | string | Member email used for find-or-create. |
company_code | string | CCA-assigned organization identifier that selects the login organization. |
first_name | string | Non-empty given name. |
last_name | string | Non-empty family name. |
country | string | ISO country code such as AU or US. |
preferred_language | string | Language tag such as en or en-AU. |
Optional Claims
| Claim | Type | Description |
|---|---|---|
external_id | string | Stable partner-side identifier. Prefixing it as <partner-code>:<internal-id> is recommended. |
sub | string | Stable partner-side user identifier; CCA prefixes it with the integration partner code for storage. |
nbf | number | Not-before time in Unix seconds; 60 seconds of clock skew is allowed. |
Security and Privacy
| Control | Description |
|---|---|
| Short-lived tokens | Token lifetime is capped at 300 seconds from iat by default. |
| One-time use | Each jti can be consumed once; replay attempts are rejected. |
| Transport security | Redirects and CCA services use HTTPS and TLS. |
| Encrypted payload | Member claims travel inside a JWE using dir and A256GCM. |
| Integrity and origin | Inner claims are signed with HS256 for compatibility with the required nested format. |
| Algorithm pinning | Only HS256, dir, and A256GCM are accepted. |
| Minimal browser exposure | CCA removes sensitive query parameters from the visible URL before token exchange. |
| No open redirects | Unknown redirect_url values are ignored. |
| Audit logging | Events record integration partner code, jti, error code, client IP, and a hash of the lowercased email—not member names, country, or language. |
Integration Partner Responsibilities
- Mint tokens only on trusted servers. Never expose the shared secret to browsers or mobile clients.
- Do not log, cache, or retain full token strings after redirect.
- Protect the shared secret like a production database credential and never commit it to source control.
- Use a fresh UUIDv4
jtifor every login attempt. - Keep sandbox and production secrets separate, with separate rotation schedules.
HIPAA and Compliance
Protection of health-related information depends on the overall program between the integration partner and CCA, including the applicable contractual framework, access controls, workforce training, breach notification, and platform controls.
Use only the member data required for authentication and profile synchronization. Confirm that all claims align with your compliance team's minimum-necessary policies. CCA handles enterprise attestations and security questionnaires outside this technical documentation.
Redirect Slugs
The optional redirect_url is validated against a server-side allow-list. Unknown values are silently ignored and the member lands on the organization's default experience.
| Slug | Destination |
|---|---|
learn | Learn |
text-coaching-request | Text coaching entry |
intake-start | Intake start |
intake-start?skipClinicianSelect=true | Booking without clinician selection |
worklife | Work-Life Assistance |
Confirm the slugs you plan to use before sandbox cutover. CCA can add additional slugs before production.
Shared-Secret Rotation
Routine Rotation
- CCA generates and securely delivers a new shared secret.
- CCA coordinates a cutover window.
- At cutover, update the minting service while CCA updates the integration partner record.
Only one symmetric secret is active per integration partner at a time; there is no overlap window. For emergency rotation, notify CCA immediately and coordinate the cutover.
Token Exchange Endpoint
CCA's application calls this endpoint after redirect. Integration Partners do not call it directly in production; it is included for sandbox testing and reference.
POST /v2/user/sso-partner-login/post/The endpoint validates the nested token, creates or updates the member, and returns the member with a Bearer token.
Request Body
| Field | Required | Description |
|---|---|---|
token | Yes | Compact nested JWE string. |
url_slug | Yes | Entry-path organization slug; it must match the organization selected by company_code. |
redirect_url | No | Allow-listed post-login deep-link slug. |
{
"token": "eyJhbGciOiJkaXIiLCJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIn0...",
"url_slug": "example-org",
"redirect_url": "text-coaching-request"
}Success Response — 200
{
"id": 42,
"email": "jane.doe@example.com",
"token": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"redirect_url": "text-coaching-request"
}Error Response — 400 / 401
{
"status": 401,
"code": "token_expired",
"message": "Token has expired.",
"fallbackUrl": "https://partner.example.com/login"
}Error Response — 500
{
"detail": "An internal server error occurred",
"code": "INTERNAL_SERVER_ERROR"
}Errors and Fallback URLs
When token exchange fails, CCA redirects the member to the response's fallbackUrl. CCA selects it in this order: organization-specific fallback, integration partner fallback_login_url, then the White-label platform login.
| Code | HTTP | Meaning |
|---|---|---|
token_invalid | 401 | Decryption, signature, issuer, audience, lifetime, algorithm, or other cryptographic validation failed. |
token_expired | 401 | The exp time is in the past. |
token_replayed | 401 | The same jti was already used. |
missing_claim | 400 | A required claim is absent or empty. |
missing_url_slug | 400 | The internal request is missing url_slug. |
unknown_company_code | 400 / 401 | No active organization matches the company code or path slug. |
company_not_enrolled_with_partner | 401 | The entry slug or company code is not assigned to the integration partner. |
partner_inactive | 401 | The integration partner is suspended. |
partner_not_found | 401 | The organization references a missing integration partner record. |
CCA intentionally returns token_invalid for all cryptographic failures. Detailed rejection information remains in CCA's internal logs.
Sandbox Testing Checklist
- Confirm the sandbox issuer, audience, entry
url_slug, organization codes, base URL, and shared secret. - Store the sandbox secret in a server-side vault.
- Mint a token within the allowed lifetime with a fresh
jti. - Open the entry URL in an incognito window to avoid stale sessions.
- Verify login lands in the expected organization experience.
- Repeat with every
redirect_urlyou plan to use. - Confirm expired and replayed tokens return a fallback URL and redirect correctly.
Support
Technical integration questions: techsupport@ccainc.com
For shared-secret rotation, organization enrollment, or redirect allow-list changes, contact your CCA onboarding lead.