Authentication

Every Create Session request must include an HMAC-SHA256 signature inside the JSON body. The signature is generated on the partner backend using the partner secretKey.

Canonical String Format

partnerId | user_id | email | name | company_id | candidate_ids_csv

Fields Included in the Signature

Field	Source	Required
`partnerId`	URL path	Yes
`user_id`	`user.user_id`	Yes
`email`	`user.email`	Yes
`name`	`user.name`	Yes
`company_id`	`user.company.company_id`	No (empty string when not provided)
`candidate_ids_csv`	concat `candidate_id` from `user.candidates`, comma-separated	No (empty string when not provided)

⚠️

Fields sent in the payload that are NOT included in the canonical string: username, company.name, company.email, candidates[].nama, candidates[].email. Do not include them when building the canonical string.

Rules

Join fields with | (pipe).
Join multiple candidate_id values with , (comma) in payload order.
Empty optional fields stay as empty strings (do not omit them).
Output format: lowercase hexadecimal.
No leading/trailing whitespace, no newlines, no hidden characters.

Security Rules

The secretKey lives only on the backend. Never expose it in frontend, mobile, or public repos.
Generate the signature for every request (do not cache).
HTTPS is mandatory.

Test Vectors

Use the vectors below to verify your implementation against the PsikologieHub rules before going live. The values use a dummy secretKey.

Test Vector 1 — Full Payload with One Candidate

secretKey: demo-secret-key-123
partnerId: psikologihub-1024

Payload

{
  "user": {
    "user_id": "ext-user-001",
    "email": "[email protected]",
    "name": "John Doe",
    "company": { "company_id": "comp-001" },
    "candidates": [
      { "candidate_id": "cand-001" }
    ]
  }
}

Canonical string

psikologihub-1024|ext-user-001|[email protected]|John Doe|comp-001|cand-001

Expected signature

ac689886217ce7c1002102d1327dfe741ecfeb3912426eac1777e80db427a1c2

Test Vector 2 — Without Company and Without Candidates

secretKey: demo-secret-key-123
partnerId: psikologihub-1024

Payload

{
  "user": {
    "user_id": "USR-001",
    "email": "[email protected]",
    "name": "John Doe"
  }
}

Canonical string

psikologihub-1024|USR-001|[email protected]|John Doe||

Expected signature

d8bb6246a84c56073db8ca8336e290b27c4646a76d2df8b4d44012af690c432b

Signature Generation Examples

function generateSignature(
    string $partnerId,
    string $userId,
    string $userEmail,
    string $userName,
    string $companyId,
    string $candidateIdsCsv,
    string $secretKey
): string {
    $canonical = implode('|', [
        $partnerId, $userId, $userEmail, $userName, $companyId, $candidateIdsCsv,
    ]);
    return hash_hmac('sha256', $canonical, $secretKey);
}

import crypto from 'crypto';
 
function generateSignature({
  partnerId, userId, userEmail, userName,
  companyId = '', candidateIdsCsv = '', secretKey,
}) {
  const canonical = [
    partnerId, userId, userEmail, userName, companyId, candidateIdsCsv,
  ].join('|');
  return crypto.createHmac('sha256', secretKey).update(canonical).digest('hex');
}

import hmac, hashlib
 
def generate_signature(partner_id, user_id, user_email, user_name,
                       company_id, candidate_ids_csv, secret_key):
    canonical = "|".join([
        partner_id, user_id, user_email, user_name,
        company_id or "", candidate_ids_csv or "",
    ])
    return hmac.new(
        secret_key.encode("utf-8"),
        canonical.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

import java.nio.charset.StandardCharsets;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
 
static String generateSignature(
    String partnerId, String userId, String userEmail, String userName,
    String companyId, String candidateIdsCsv, String secretKey
) throws Exception {
    String canonical = String.join("|",
        partnerId, userId, userEmail, userName,
        companyId == null ? "" : companyId,
        candidateIdsCsv == null ? "" : candidateIdsCsv
    );
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] hash = mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8));
    StringBuilder sb = new StringBuilder();
    for (byte b : hash) sb.append(String.format("%02x", b));
    return sb.toString();
}

API Reference Error Handling