Tech Partner

Documentation

Last Updated:

Partner DocumentationWhite-label Members Portal

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

  1. Receive environment URLs, issuer and audience claim values, the entry url_slug, a company_code for each organization, the 256-bit shared secret, and any redirect slug allow-list from CCA.
  2. Store the shared secret in a server-side secrets manager. Treat it as a production credential.
  3. Implement server-side token minting using the nested JWE/JWS format.
  4. Redirect the member to the entry URL with token and optional redirect_url.
  5. Complete the sandbox testing checklist before production cutover.

What CCA Provisions Before Go-Live

ItemDescription
Integration Partner configurationIntegration Partner code, issuer and audience claim values, and the fallback_login_url registered on the integration partner record.
Shared secretA 256-bit base64url-encoded value delivered securely. Sandbox and production use different secrets.
Organization enrollmentThe entry url_slug and a company_code for each target organization. One entry can cover multiple organizations.
Environment URLsWhite-label base URL per environment and expected iss and aud values.
Redirect slugsOptional allow-listed deep-link slugs.

End-User Flow

  1. The integration partner server mints a nested JWE(JWS) with member claims using the shared secret.
  2. The integration partner redirects the member's browser to /go/{url_slug}/token?token=....
  3. The CCA application removes sensitive query parameters from the visible URL and calls the token-exchange API.
  4. CCA decrypts and verifies the token, enforces the one-time jti, and creates or updates the member.
  5. CCA returns the member and Bearer token; the application opens the session and navigates to the organization home or an allow-listed redirect.
  6. On failure, the member is sent to the fallbackUrl from 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}]
PlaceholderDescription
{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

ParameterRequiredDescription
tokenYesCompact nested JWE string.
redirect_urlNoAllow-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_slug in the path. The required company_code selects the exact organization.
  • Omit redirect_url to use the organization's default experience.
  • If token is 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

LayerFieldValue
Inner JWSalgHS256
Inner JWStypJWT
Outer JWEalgdir
Outer JWEencA256GCM
Outer JWEctyJWT

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

ClaimTypeDescription
issstringMust match the issuer configured by CCA.
audstringMust match the configured audience for the environment.
iatnumberIssued-at time in Unix seconds.
expnumberExpiry in Unix seconds; exp - iat must not exceed 300 seconds by default.
jtistringFresh UUIDv4 token identifier; single-use across all integration partner URL slugs.
emailstringMember email used for find-or-create.
company_codestringCCA-assigned organization identifier that selects the login organization.
first_namestringNon-empty given name.
last_namestringNon-empty family name.
countrystringISO country code such as AU or US.
preferred_languagestringLanguage tag such as en or en-AU.

Optional Claims

ClaimTypeDescription
external_idstringStable partner-side identifier. Prefixing it as <partner-code>:<internal-id> is recommended.
substringStable partner-side user identifier; CCA prefixes it with the integration partner code for storage.
nbfnumberNot-before time in Unix seconds; 60 seconds of clock skew is allowed.

Security and Privacy

ControlDescription
Short-lived tokensToken lifetime is capped at 300 seconds from iat by default.
One-time useEach jti can be consumed once; replay attempts are rejected.
Transport securityRedirects and CCA services use HTTPS and TLS.
Encrypted payloadMember claims travel inside a JWE using dir and A256GCM.
Integrity and originInner claims are signed with HS256 for compatibility with the required nested format.
Algorithm pinningOnly HS256, dir, and A256GCM are accepted.
Minimal browser exposureCCA removes sensitive query parameters from the visible URL before token exchange.
No open redirectsUnknown redirect_url values are ignored.
Audit loggingEvents 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 jti for 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.

SlugDestination
learnLearn
text-coaching-requestText coaching entry
intake-startIntake start
intake-start?skipClinicianSelect=trueBooking without clinician selection
worklifeWork-Life Assistance

Confirm the slugs you plan to use before sandbox cutover. CCA can add additional slugs before production.

Shared-Secret Rotation

Routine Rotation

  1. CCA generates and securely delivers a new shared secret.
  2. CCA coordinates a cutover window.
  3. 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

FieldRequiredDescription
tokenYesCompact nested JWE string.
url_slugYesEntry-path organization slug; it must match the organization selected by company_code.
redirect_urlNoAllow-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.

CodeHTTPMeaning
token_invalid401Decryption, signature, issuer, audience, lifetime, algorithm, or other cryptographic validation failed.
token_expired401The exp time is in the past.
token_replayed401The same jti was already used.
missing_claim400A required claim is absent or empty.
missing_url_slug400The internal request is missing url_slug.
unknown_company_code400 / 401No active organization matches the company code or path slug.
company_not_enrolled_with_partner401The entry slug or company code is not assigned to the integration partner.
partner_inactive401The integration partner is suspended.
partner_not_found401The 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

  1. Confirm the sandbox issuer, audience, entry url_slug, organization codes, base URL, and shared secret.
  2. Store the sandbox secret in a server-side vault.
  3. Mint a token within the allowed lifetime with a fresh jti.
  4. Open the entry URL in an incognito window to avoid stale sessions.
  5. Verify login lands in the expected organization experience.
  6. Repeat with every redirect_url you plan to use.
  7. 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.