Autentikasi

Setiap request Create Session wajib menyertakan signature HMAC-SHA256 di dalam JSON body. Signature dibuat di backend partner menggunakan secretKey partner.

Format Canonical String

partnerId | user_id | email | name | company_id | candidate_ids_csv

Field yang Masuk Signature

Field	Sumber	Wajib
`partnerId`	URL path	Ya
`user_id`	`user.user_id`	Ya
`email`	`user.email`	Ya
`name`	`user.name`	Ya
`company_id`	`user.company.company_id`	Tidak (empty string jika tidak ada)
`candidate_ids_csv`	concat `candidate_id` dari `user.candidates`, dipisah koma	Tidak (empty string jika tidak ada)

⚠️

Field di payload yang TIDAK masuk canonical string: username, company.name, company.email, candidates[].nama, candidates[].email. Jangan masukkan field-field tersebut ke canonical string.

Aturan

Field digabung dengan | (pipe).
Beberapa candidate_id digabung dengan , (koma) mengikuti urutan payload.
Field opsional yang kosong tetap berupa empty string (jangan dihilangkan).
Format output: hexadecimal lowercase.
Tidak boleh ada spasi di awal/akhir, newline, atau karakter tersembunyi.

Aturan Keamanan

secretKey hanya ada di backend. Jangan pernah ekspos di frontend, mobile, atau repo publik.
Buat signature untuk setiap request (jangan di-cache).
HTTPS wajib.

Test Vectors

Gunakan vektor di bawah untuk memverifikasi implementasi Anda terhadap aturan PsikologieHub sebelum go-live. Nilai memakai secretKey dummy.

Test Vector 1 - Payload Lengkap dengan Satu Kandidat

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 - Tanpa Company dan Tanpa 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

Contoh Generate Signature

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();
}

Referensi API Penanganan Error