Akses pesan pribadi
member JKT48, secara aman.

01 Overview

Semua permintaan partner masuk lewat dua base URL berikut. Simpan keduanya — kamu akan memakainya di setiap request.

02 Konsep dasar

Empat istilah yang akan sering kamu temui di dokumentasi ini.

03 Quickstart

Dari nol sampai membaca pesan pertama, dalam empat langkah.

const { generateKeyPairSync } = require("crypto");
const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });

// simpan ini di tempat aman, JANGAN pernah dibagikan
console.log(privateKey.export({ type: "pkcs8", format: "pem" }));

// kirim ini saat registrasi
console.log(JSON.stringify(publicKey.export({ format: "jwk" })));

05 Membuat DPoP key

DPoP key adalah keypair ECDSA P-256 milikmu sendiri — bukan diberikan oleh JKT48Connect. Private key-nya tetap di perangkat kamu selamanya; yang dikirim ke kami hanya public key-nya (saat registrasi atau saat rotate).

06 Menandatangani request

Tiga endpoint di Gateway (/access/claim, /access, /generate) mewajibkan tiga header berikut di setiap panggilan.

import crypto from "crypto";

function signRequest(secret, method, path, extraSalt = "") {
  const timestamp = String(Date.now());
  const derivedKey = crypto.hkdfSync(
    "sha256",
    Buffer.from(secret, "hex"),
    Buffer.from(timestamp, "utf8"),
    Buffer.from(`pm-gateway:${path}`, "utf8"),
    32
  );
  const signingStr = `${method}:${path}:${KID}:${timestamp}${extraSalt}`;
  const signature = crypto
    .createHmac("sha256", Buffer.from(derivedKey))
    .update(signingStr)
    .digest("hex");

  return { timestamp, signature };
}

const { timestamp, signature } = signRequest(secret, "POST", "/api/pm/generate", `:${identifier}`);
// signingStr akan jadi: POST:/api/pm/generate:KID:TIMESTAMP:Lily

Melihat akses aktif

Pakai header signing yang sama untuk melihat daftar member yang sedang aktif untuk akun kamu, beserta tanggal kedaluwarsanya. Endpoint ini tidak butuh extraSalt.

08 Generate token

Token berumur pendek dan hanya berlaku untuk satu member. Generate token baru setiap kali kamu akan mengambil pesan — jangan simpan token untuk dipakai berulang dalam jangka panjang.

x-kid: p_xxxxxxxxxxxx
x-timestamp: 1751870005000
x-signature: ...
x-identifier: Lily

{
  "status": true,
  "data": {
    "token": "eyJhbGciOi...",
    "expiresIn": 600,
    "identifier": "Lily"
  }
}

09 Mengambil pesan

Endpoint ini ada di domain terpisah, pmv.jkt48connect.com, dan mewajibkan dua header: token yang baru kamu generate, dan sebuah DPoP proof — bukti bahwa request ini benar berasal dari perangkat yang memegang DPoP key kamu.

Membuat DPoP proof

DPoP proof adalah JWT pendek yang kamu tanda tangani sendiri pakai DPoP private key, dibuat baru untuk setiap request.

import crypto from "crypto";

function b64url(buf) {
  return buf.toString("base64")
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

function makeDpopProof(privateKeyPem, method, url) {
  const header = { alg: "ES256", typ: "dpop+jwt" };
  const payload = {
    htm: method,
    htu: url,
    iat: Math.floor(Date.now() / 1000),
    jti: crypto.randomUUID(),
  };
  const h = b64url(Buffer.from(JSON.stringify(header)));
  const p = b64url(Buffer.from(JSON.stringify(payload)));

  const signer = crypto.createSign("SHA256");
  signer.update(`${h}.${p}`);
  signer.end();
  const sig = signer.sign({ key: privateKeyPem, dsaEncoding: "ieee-p1363" });

  return `${h}.${p}.${b64url(sig)}`;
}

Memanggil endpoint

const urlNoQuery = `https://pmv.jkt48connect.com/messages/Lily`;
const urlWithQuery = `${urlNoQuery}?page=1`;
const dpop = makeDpopProof(privateKeyPem, "GET", urlNoQuery);

const res = await fetch(urlWithQuery, {
  headers: {
    Authorization: `Bearer ${token}`,
    DPoP: dpop,
  },
});
const data = await res.json();

{
  "status": true,
  "idol_name": "Lily",
  "page": 1,
  "encrypted": true,
  "data": "base64-ciphertext..."
}

10 Mengganti kredensial

Dua hal yang bisa kamu rotate sendiri, kapan pun, tanpa menunggu tim kami.

Rotate secret (HMAC)

Tanda tangani request ini dengan secret lama. Secret baru langsung aktif; token yang sudah terlanjur ada tetap valid sampai kedaluwarsa.

Rotate DPoP key

{ "dpop_public_jwk": { "kty": "EC", "crv": "P-256", "x": "...", "y": "..." } }

Setelah rotate, generate token baru sebelum memanggil /messages lagi — token yang diterbitkan sebelum rotate tidak akan lagi cocok dengan key baru.

11 Membaca response terenkripsi

Field data dari /messages berisi base64 dari iv (12 byte) + authTag (16 byte) + ciphertext, dienkripsi AES-256-GCM memakai output secret yang diberikan tim kami saat onboarding.

import crypto from "crypto";

function decryptMessageData(encryptedBase64, outputSecret) {
  const key = crypto.createHash("sha256").update(outputSecret).digest();
  const combined = Buffer.from(encryptedBase64, "base64");

  const iv = combined.subarray(0, 12);
  const authTag = combined.subarray(12, 28);
  const ciphertext = combined.subarray(28);

  const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
  decipher.setAuthTag(authTag);

  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
  return JSON.parse(decrypted.toString("utf8"));
}

Belum punya output secret kamu? Hubungi tim JKT48Connect saat onboarding untuk mendapatkannya.

12 Kode error

Semua endpoint mengembalikan bentuk yang sama: { status: false, message: "..." }.

13 Rate limit

Setiap partner memiliki kuota permintaan wajar untuk penggunaan normal. Kalau aplikasi kamu perlu volume lebih tinggi dari kuota default, hubungi tim JKT48Connect untuk penyesuaian.

14 FAQ

Kenapa harus ada dua langkah, secret dan DPoP key?

Secret membuktikan identitas akun kamu ke Gateway. DPoP key membuktikan bahwa permintaan ke Messages API benar berasal dari perangkat kamu sendiri — jadi token tetap aman dipakai meskipun secret dan DPoP key kamu simpan terpisah.

Berapa lama token berlaku?

10 menit. Generate token baru setiap kali kamu akan mengambil data terbaru.

Bagaimana kalau DPoP private key saya bocor?

Segera panggil /partner/rotate-key dengan public key baru. Key lama langsung tidak berlaku setelah itu.

Bisa akses banyak member sekaligus?

Bisa. Klaim akses satu per satu lewat /access/claim, lalu generate token terpisah untuk masing-masing member saat dibutuhkan.

Kenapa muncul "Signature tidak valid atau sudah dipakai (replay)" padahal kid, secret, dan jam sudah benar?

Penyebab paling umum: lupa menyertakan extraSalt (:identifier) saat signing untuk endpoint /access/claim dan /generate, atau path yang disign tidak memakai full path (/api/pm/...). Lihat contoh lengkap di bagian 06.

Butuh bantuan lebih lanjut?

Hubungi tim JKT48Connect melalui kanal partner yang sudah kamu gunakan saat onboarding.