Web Quickstart

Get from zero to an authenticated portal session using the WEB chain. This guide walks through the full sequence: health check, Secure Channel bootstrap, login, and profile fetch.

Prerequisites

• API running at http://127.0.0.1:18020/prometheus (see Environments)
• A SYSTEM portal access code (provided by your administrator)
• A registered user account with email and password
• curl or any HTTP client

Step 1: Verify the API is reachable

curl http://127.0.0.1:18020/prometheus/actuator/health
# Expected: {"status":"UP"}

Step 2: Establish a Secure Channel session

2a. Get the server's RSA public key

curl http://127.0.0.1:18020/prometheus/web/v1/secure-channel/public-key \
  -H "Content-Type: application/json" \
  -H "X-Client-Hash: quickstart-test" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "CF-Connecting-IP: 127.0.0.1" \
  -H "Cf-Ray: quickstart-$(date +%s)-DEV" \
  -H "cf-ipcountry: US" \
  -H "X-Forwarded-Proto: https" \
  -H "User-Agent: quickstart/1.0"

Expected response:

{
  "version": "2.0.0",
  "success": true,
  "code": "2000",
  "data": {
    "keyId": "rsa-key-2026-03-21",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
    "algorithm": "RSA-OAEP-2048",
    "keySize": 2048
  }
}

2b. Create a Secure Channel session

Generate two random AES-256 keys (one for requests, one for responses), encrypt each with the RSA public key, then submit:

curl -X POST http://127.0.0.1:18020/prometheus/web/v1/secure-channel/session \
  -H "Content-Type: application/json" \
  -H "X-Client-Hash: quickstart-test" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "CF-Connecting-IP: 127.0.0.1" \
  -H "Cf-Ray: quickstart-$(date +%s)-DEV" \
  -H "cf-ipcountry: US" \
  -H "X-Forwarded-Proto: https" \
  -H "User-Agent: quickstart/1.0" \
  -d '{
    "keyId": "rsa-key-2026-03-21",
    "encReqKey": "<base64-rsa-encrypted-aes-request-key>",
    "encRespKey": "<base64-rsa-encrypted-aes-response-key>"
  }'

Expected response:

{
  "version": "2.0.0",
  "success": true,
  "code": "2000",
  "data": {
    "sessionId": "sess_abc123def456",
    "expiresAt": 1709424000000
  }
}

Save the sessionId -- you will pass it as X-SC-Session-Id on encrypted requests.

Step 3: Initiate login

curl -X POST http://127.0.0.1:18020/prometheus/web/v1/system/auth/login/initiate \
  -H "Content-Type: application/json" \
  -H "X-PORTAL-ACCESS-CODE: {your-access-code}" \
  -H "X-Client-Hash: quickstart-test" \
  -H "X-SC-Session-Id: {session-id}" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "CF-Connecting-IP: 127.0.0.1" \
  -H "Cf-Ray: quickstart-$(date +%s)-DEV" \
  -H "cf-ipcountry: US" \
  -H "X-Forwarded-Proto: https" \
  -H "User-Agent: quickstart/1.0" \
  -d '{"email":"admin@example.com","password":"Str0ngP@ss!"}'

Expected response:

{
  "code": "2000",
  "data": {
    "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "mfaMethods": [
      { "code": "EMAIL", "value": 10011001 },
      { "code": "OTP", "value": 10011002 }
    ],
    "expiresIn": 300
  }
}

Step 4: Complete login with MFA

If MFA is required, send the verification code and then complete:

curl -X POST http://127.0.0.1:18020/prometheus/web/v1/system/auth/login/complete \
  -H "Content-Type: application/json" \
  -H "X-PORTAL-ACCESS-CODE: {your-access-code}" \
  -H "X-Client-Hash: quickstart-test" \
  -H "X-SC-Session-Id: {session-id}" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "CF-Connecting-IP: 127.0.0.1" \
  -H "Cf-Ray: quickstart-$(date +%s)-DEV" \
  -H "cf-ipcountry: US" \
  -H "X-Forwarded-Proto: https" \
  -H "User-Agent: quickstart/1.0" \
  -d '{"sessionId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","method":10011001,"code":"123456"}'

Expected response:

{
  "code": "2000",
  "data": {
    "accessToken": "eyJhbGciOi...example",
    "refreshToken": "dGVzdC1yZWZyZXNoLXRva2VuLWV4YW1wbGU",
    "expiresIn": 3600
  }
}

Step 5: Fetch your profile

curl http://127.0.0.1:18020/prometheus/web/v1/system/profile \
  -H "Authorization: Bearer {accessToken}" \
  -H "X-PORTAL-ACCESS-CODE: {your-access-code}" \
  -H "X-Client-Hash: quickstart-test" \
  -H "X-Request-Id: $(uuidgen)" \
  -H "CF-Connecting-IP: 127.0.0.1" \
  -H "Cf-Ray: quickstart-$(date +%s)-DEV" \
  -H "cf-ipcountry: US" \
  -H "X-Forwarded-Proto: https" \
  -H "User-Agent: quickstart/1.0"

Required Headers Summary

Every WEB request needs these gateway headers:

Header	Description
X-PORTAL-ACCESS-CODE	Portal access code
X-Client-Hash	Client device fingerprint
X-Request-Id	Unique request identifier (UUID)
CF-Connecting-IP	Client IP address
Cf-Ray	Cloudflare ray ID
cf-ipcountry	Client country code
X-Forwarded-Proto	Protocol (https)
User-Agent	Client user agent

Add these as needed:

Header	When needed
X-SC-Session-Id	Endpoints requiring Secure Channel
Authorization: Bearer <jwt>	Authenticated endpoints

Next Steps

• Auth Guide
• Account Guide
• Workspace Guide
• Secure Channel Concept
• Authentication Models