Secure Channel v2

Secure Channel v2 (SCv2) protects sensitive WEB requests by encrypting request and response payloads with per-session AES-256-GCM keys.

When It Is Used

SCv2 is required for:

1. login initiation
2. registration initiation
3. password reset
4. password change
5. sensitive security center mutations

All other endpoints use plaintext JSON.

Protocol Flow

1. Get server public key

GET /web/v1/secure-channel/public-key

Returns the active RSA public key (keyId, publicKey, algorithm).

2. Generate AES session keys

The client generates two random AES-256 keys:

• Request key -- encrypts outbound request payloads
• Response key -- the server uses this to encrypt response payloads

3. Create session

POST /web/v1/secure-channel/session

The client RSA-encrypts both AES keys using the server public key. The server decrypts and stores them, returns a sessionId.

4. Send encrypted requests

Set X-SC-Session-Id header. The HTTP body is replaced with a binary SCv2 envelope (Content-Type remains application/json;charset=UTF-8).

5. Close session when done

POST /web/v1/secure-channel/session/close

Binary Envelope Format

Type 1 -- Key Exchange (first request):

[2B magic "SC"] [1B version] [1B type=1]
[1B keyIdLen] [keyIdLen B keyId]
[2B reqKeyLen] [reqKeyLen B encryptedReqKey]
[2B respKeyLen] [respKeyLen B encryptedRespKey]
[remaining: AES-GCM encrypted payload]

Type 2 -- Session Data (subsequent requests):

[2B magic "SC"] [1B version] [1B type=2]
[remaining: AES-GCM encrypted payload]

Type 129 -- Response Data:

[2B magic "SC"] [1B version] [1B type=129]
[remaining: AES-GCM encrypted payload]

The AES-GCM payload is: 12-byte IV + ciphertext + 16-byte auth tag.

What It Does Not Replace

Secure Channel does not replace:

1. portal context (X-PORTAL-ACCESS-CODE)
2. JWT session state (Authorization)
3. X-Client-Hash fingerprinting
4. permission checks

Common Failure Modes

Issue	Cause
SECURE_CHANNEL.INVALID_PAYLOAD	Plaintext sent to an SCv2-required endpoint
401 with SC session active	Missing JWT or portal context alongside SC
Expired session	SC session TTL exceeded; create a new one

Read Next

1. Quickstart
2. Auth Guide