JWT key rotation

JWT key types in SIVO

Key	Algorithm	Use	Who manages
sivo_user_jwt_key	HS256 (secret)	Signs tokens issued by /api/auth/login	SIVO (quarterly rotation)
sivo_scrt2_jwt_key	RS256 (keypair)	Signs JWTs sent to Salesforce SCRT2	SIVO (global) + optional per-org override

User JWT (HS256)

Secret shared between backend and verifier. Automatic rotation:

• Every 90 days SIVO generates a new secret.
• Grace period: for 24h both secrets are valid (old tokens still verify).
• After 24h, old secret invalidated. Sessions not renewed expire (re-login).

Salesforce SCRT2 JWT (RS256)

To call SCRT2 (POST /voiceCalls, message push, etc.) SIVO signs a JWT with RS256:

{
  "iss": "<scrt2_audience>",
  "sub": "<sf_user_id>",
  "aud": "<scrt_base_url>",
  "iat": ...,
  "exp": ...
}

Verification is done by Salesforce using the public key the calltreeSetup LWC configures automatically upon connect.

Global mode (default)

By default, all SIVO tenants share a single RS256 keypair maintained by SIVO. Pros:

• Centralized rotation (SIVO).
• Your SF admin doesn’t have to do anything on each rotation.
• Zero configuration after OAuth.

Per-org mode (Enterprise optional)

If your compliance requires a dedicated key per SF org, you can enable:

Settings → Salesforce → Connected orgs → your org → "Use dedicated keypair"

SIVO generates a new RS256 keypair for that org. Your SF admin configures the corresponding public key in their External Client App.

Trade-off:

• ✓ Cryptographic isolation per org.
• ✗ Rotation requires coordination with SF admin (re-upload of public key).

How to rotate manually (Enterprise)

If you need to force immediate rotation (suspected leak, internal quarterly policy):

1. Settings → Salesforce → your org → “Rotate keypair”.
2. SIVO generates new keypair, keeps the old for 24h in dual-verify mode.
3. Download the new public key in JWK format.
4. Your SF admin uploads it to the External Client App.
5. After 24h, the old keypair is invalidated.

If you miss step 4 within 24h, new JWTs won’t verify in SF and calls won’t push to VoiceCall. SIVO notifies you by email.

Technical runbook (internal)

The internal global keypair rotation runbook lives in the backend repo (docs/maintenance/rotate-scrt2-jwt-keypair.md). It runs:

• Every 6 months as policy.
• Immediately on suspected exposure.
• When an Enterprise customer migrates from global to dedicated.

Support

To activate dedicated mode or any rotation query: [email protected] (Enterprise: your direct CSM).