Documentation Powered by ReDoc

PAKD Education Service Public API v0.0.1 (0.0.1)

Download OpenAPI specification:Download

ICEx Support API: support@icex.id License: MIT

Public API Contract for PAKD (Pedagang Aset Keuangan Digital) Education Service.

This spec covers the exchange-facing (public) API — the endpoint that exchanges call to create education sessions for their users.

PAKD is an educational quiz system for derivative trading knowledge assessment.

Base URL (Staging): https://edu-api-staging.icex.id Base URL (Production): https://edu-api.icex.id

The embedUrl returned by the session endpoints points to the education frontend (staging: https://edu-staging.icex.id, production: https://edu.icex.id).

Authorization

This API uses the API Key Authentication pattern: a public API key identifies the caller, and an HMAC-SHA512 signature proves possession of the secret key. The secret key is never sent over the wire.

Required Headers

Header Required Description
X-API-Key Yes Public API key that identifies the exchange.
X-Signature Yes HMAC-SHA512 signature of METHOD|PATH|CANONICAL_BODY|TIMESTAMP, hex-encoded (lowercase).
X-Timestamp Yes Unix timestamp in milliseconds. Must be within ±5 minutes of server time.
Content-Type Yes Must be application/json.

Optional Headers

Header Description
X-Idempotency-Key Unique key to prevent duplicate session creation.

Signature Generation

  1. Create canonical JSON: Sort the request body JSON keys alphabetically (recursively) and remove all whitespace.
  2. Build payload string: Format as "METHOD|PATH|BODY|TIMESTAMP".
  3. Calculate HMAC-SHA512: Use your api_secret as the HMAC key.
  4. Convert to hex: Lowercase hexadecimal representation.

Key Separation

Concept Sent over wire Used for
api_key (public) Yes — X-API-Key header Looking up the exchange (safe to log)
api_secret (private) Never HMAC-SHA512 signature + JWT signing

Idempotency: Use X-Idempotency-Key header to prevent duplicate session creation.

Session Lifecycle:

  • PENDING → MATERIAL_IN_PROGRESS → QUIZ_IN_PROGRESS → PASSED/FAILED/TIMEOUT/INCOMPLETE

Quiz Rules:

  • Mandatory questions always included
  • Final selection shuffled
  • Score threshold: ≥ the exchange's configured pass_threshold_pct (default: 70). Confirm the exact value for your exchange during onboarding.
  • Mandatory knockout: If any mandatory question is wrong → FAIL

Education

Education session management

Create Education Session

Creates a new education session for the given user. Returns an embed URL with a JWT token.

Note: This endpoint can return both 201 Created (new session) and 200 OK (existing active session, idempotency replay, or already certified). All 200/201 responses include a status discriminator field.

path Parameters
user_id
required
string
Example: usr_8f3a2c1b9e

The end-user identifier as known by the exchange. Opaque string, no length limit enforced by backend (DB stores as TEXT). Examples: test-user-127, user_demo_001, cust-abc-123.

header Parameters
X-Idempotency-Key
string
Example: unique-key-001

Optional unique key to prevent duplicate session creation for the same (exchange_id, user_id, idempotency_key) tuple. Stored server-side with a 24-hour TTL. On replay, returns 200 OK with the original session and a freshly generated JWT token (status: idempotent_replay).

Request Body schema: application/json
required
object

Callback URLs for session outcomes

sessionTimeoutMinutes
integer

Total time allowed to complete the entire education flow (material + quiz). If omitted or ≤ 0, falls back to the exchange's configured sessionTimeoutMinutes (default: 60). Values ≤ 0 are accepted and trigger the fallback; they are not rejected.

Responses

Request samples

Content type
application/json
Example
Create a new session
Create a new session
Create session with custom timeout
{}

Response samples

Content type
application/json
Example
Existing active session
Existing active session
Idempotency key replay
User already has a valid certification
Idempotency key replay but stored session unresolved
{
  • "status": "active_session",
  • "embedUrl": "https://edu.icex.id/embed/<JWT_TOKEN>",
  • "sessionId": "9f189718-4521-4437-a0ae-6452030c1235",
  • "questionsTotal": 30,
  • "expiresAt": "2026-07-29T21:10:19+07:00"
}

Health Check

Public health endpoint to verify service is running

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "version": "0.1.0",
  • "uptimeSeconds": 123,
  • "goVersion": "go1.26.0"
}