Privy Digital ID — Integration GuidePanduan Integrasi

EnvironmentsEnvironment

Two environments, same API. Use Sandbox for integration and testing, Production for live traffic — just swap the base host. Dua environment, API sama. Pakai Sandbox untuk integrasi & pengujian, Production untuk trafik live — cukup ganti base host.

OverviewRingkasan

Privy Digital ID is an identity verification widget. The merchant never handles the camera, biometric data, or the user's personal data — the merchant only: Privy Digital ID adalah widget verifikasi identitas. Merchant tidak menangani kamera, data biometrik, maupun data pribadi pengguna — merchant hanya:

1. Creates a session from its backend (with an API key) → receives a session_url. Membuat sesi dari backend (dengan API key) → menerima session_url.
2. Embeds the session_url in an iframe / WebView. Meng-embed session_url di iframe / WebView.
3. Receives the result via a server-to-server callback (source of truth) and/or a postMessage event. Menerima hasil lewat callback server-to-server (sumber kebenaran) dan/atau event postMessage.

How it worksBagaimana ia bekerja

There are two parties: the Merchant (who embeds) and Privy (who verifies identity). The whole process runs inside Privy's widget. Two steps below depend on your credential's verification type — the Identity markers show what changes for a PII credential. Ada dua pihak: Merchant (yang meng-embed) dan Privy (yang memverifikasi identitas). Seluruh proses berjalan di dalam widget Privy. Dua langkah di bawah bergantung pada jenis verifikasi credential Anda — penanda Identity menunjukkan yang berubah untuk credential PII.

Integration flowDiagram integrasi

The full sequence between the four parties. Steps 1–3 set up the widget; step 4 all happens inside Privy; steps 5–8 deliver the verified data to the merchant. otp* runs only for Identity credentials. Urutan lengkap antara empat pihak. Langkah 1–3 menyiapkan widget; langkah 4 seluruhnya terjadi di dalam Privy; langkah 5–8 mengantar data terverifikasi ke merchant. otp* hanya untuk credential Identity.

Quickstart

1 · Create a session (merchant backend)Buat sesi (backend merchant)

# API key stays in the backend — never in the browserAPI key hanya di backend — jangan pernah di browser
curl -X POST https://sandbox-api-digitalid.privy.id/v1/sessions \
  -H "X-API-Key: <MERCHANT_API_KEY>"

{
  "session_id": "9f1c…",
  "session_url": "https://sandbox-digitalid.privy.id/?t=eyJ…",
  "expires_at": "2026-07-21T18:15:00Z"
}

2 · Embed the widget (merchant frontend)Embed widget (frontend merchant)

<iframe src="{{session_url}}" allow="camera"
        style="width:100%;height:100%;border:0"></iframe>

3 · Receive the resultTerima hasil

window.addEventListener('message', (e) => {
  if (e.origin !== 'https://sandbox-digitalid.privy.id') return; // requiredwajib
  const { type, payload } = e.data || {};
  if (type === 'privy:success') {
    // hand payload.exchange_code to your backend to swap for a tokenserahkan payload.exchange_code ke backend untuk ditukar token
  }
});

Verification statesAlur verifikasi

The state machine is enforced server-side. Data-sharing consent happens AFTER the face match (Privy's regulation): State machine dijaga server-side. Consent berbagi data terjadi SETELAH wajah cocok (regulasi Privy):

Identity (PII) credentials add an OTP (2FA) step after the face match, before consent (see Verification types): Credential Identity (PII) menambah langkah OTP (2FA) setelah pencocokan wajah, sebelum consent (lihat Jenis verifikasi):

Verification typesJenis verifikasi

A credential is provisioned as one of two types. The type is fixed per credential (chosen when Privy creates your credential) — it decides the input, whether an OTP step runs, which data is shared, and how it is delivered. Your integration doesn't select it per request. Tiap credential disetel salah satu dari dua jenis. Jenis ini tetap per credential (dipilih saat Privy membuat credential Anda) — menentukan input, ada/tidaknya langkah OTP, data apa yang dibagikan, dan cara pengirimannya. Integrasi Anda tidak memilihnya per request.

AuthenticationAutentikasi

Privy issues one API key per merchant. All back-channel requests (create session, exchange code) carry the X-API-Key header. Privy menerbitkan satu API key untuk tiap merchant. Semua permintaan back-channel (buat sesi, tukar exchange code) dikirim dengan header X-API-Key.

API Reference

{ "session_id":"…", "session_url":"https://sandbox-digitalid.privy.id/?t=…", "expires_at":"…Z" }

{ "session_id":"…", "event":"identity.verified", "token":"eyJ… (JWT EdDSA)" }

{ "keys":[{ "kty":"OKP", "crv":"Ed25519", "alg":"EdDSA", "use":"sig", "kid":"…", "x":"…" }]}

postMessage eventsEvent postMessage

The widget posts events to the parent (iframe) prefixed with privy:. Always validate event.origin against the widget origin. Widget mengirim event ke parent (iframe) dengan prefix privy:. Selalu validasi event.origin terhadap origin widget.

The sections fieldField sections — optional previewpratinjau opsional

The data the user agreed to share, grouped by section (only populated fields). For display only — the authoritative data is always fetched by the backend via exchange → JWT: Data yang disetujui pengguna, dikelompokkan per bagian (hanya field berisi nilai). Untuk menampilkan ke pengguna saja — data resmi tetap diambil backend lewat exchange → JWT:

"sections": [
  { "section":"my_contact_data", "label":"My Contact Data", "fields":[
    { "key":"email", "label":"Email", "value":"user@mail.com", "is_verified":true }
  ]}
]

Native integration (iOS / Android)Integrasi native (iOS / Android)

Load the session_url directly in a WebView. The same events are delivered via a native bridge:Muat session_url langsung di WebView. Event yang sama dikirim lewat bridge native:

// JSON received by the native bridge — a native WebView is a TRUSTED host (not an iframe), so the payload comes in FULLJSON yang diterima bridge native — WebView native adalah host TERPERCAYA (bukan iframe), jadi payload dikirim PENUH
{
  "type": "privy:success",
  "payload": {
    "session_id":    "…",
    "exchange_code": "…",    // redeem server-to-server (recommended)redeem server-to-server (disarankan)
    "token":         "…",    // verified-data JWT (present on native)JWT verified-data (ada di native)
    "sections":      [ … ]   // shared-data preview (Identity: my_identity stays encrypted)pratinjau data (Identity: my_identity tetap terenkripsi)
  }
}

Camera & permissions (WebView SDK)Kamera & izin (SDK WebView)

On mobile the widget is wrapped by the DigitalID WebView SDK (iOS & Android). The liveness step opens the camera with the standard Web API — navigator.mediaDevices.getUserMedia(). There is no custom bridge message to request the camera: the SDK observes the getUserMedia call, decides grant/deny, and drives the native OS permission prompt. The web contract is identical on both platforms; only the native integrator setup differs. Di mobile, widget dibungkus SDK WebView DigitalID (iOS & Android). Langkah liveness membuka kamera dengan Web API standar — navigator.mediaDevices.getUserMedia(). Tidak ada pesan bridge khusus untuk meminta kamera: SDK mengamati panggilan getUserMedia, memutuskan izinkan/tolak, dan menggerakkan prompt izin OS. Kontrak web sama di kedua platform; hanya setup integrator native yang berbeda.

Web contract (frontend — required)Kontrak web (frontend — wajib)

• Request video only — getUserMedia({ video: true }). Do not add audio: true: both SDKs grant the camera only when the capture type is exactly camera; adding audio makes it camera+microphone, which is denied outright (the camera never opens). Minta video saja — getUserMedia({ video: true }). Jangan tambahkan audio: true: kedua SDK hanya mengizinkan kamera bila tipe capture tepat camera; menambahkan audio menjadikannya camera+mikrofon yang langsung ditolak (kamera tak pernah terbuka).
• Handle the rejected promise — always .catch(…) and show a fallback/retry UI; never assume a stream was returned. Tangani promise yang gagal — selalu .catch(…) dan tampilkan UI fallback/coba-lagi; jangan berasumsi stream selalu ada.
• HTTPS only — getUserMedia needs a secure context and the SDK transport policy rejects non-HTTPS pages. All widget/redirect origins must be https://. Hanya HTTPS — getUserMedia butuh secure context dan kebijakan transport SDK menolak halaman non-HTTPS. Semua origin widget/redirect harus https://.
• Call lazily — request the camera only at the liveness step (the prompt appears on the first getUserMedia call); don't call it eagerly on load. Popups/new windows are rejected by both SDKs. Panggil saat dibutuhkan — minta kamera hanya di langkah liveness (prompt muncul pada panggilan getUserMedia pertama); jangan panggil saat halaman dimuat. Popup/jendela baru ditolak kedua SDK.

Capture-type behaviorPerilaku tipe capture

Rejection contract (error handling)Kontrak penolakan (penanganan error)

navigator.mediaDevices.getUserMedia({ video: true })
  .then(stream => { /* proceed with livenesslanjut liveness */ })
  .catch(err => {
    switch (err.message) {
      case "camera_unsupported":        // OS/WebView too old → "update device" fallbackOS/WebView terlalu lama → fallback "perbarui perangkat"
      case "camera_missing_permission": // host app not configured → "camera unavailable"host app tak dikonfigurasi → "kamera tak tersedia"
      default:                          // DOMException: NotAllowedError / NotFoundError / NotReadableError…DOMException: NotAllowedError / NotFoundError / NotReadableError…
    }
  });

Native integrator requirementsKebutuhan integrator native

// iOS · Info.plist
<key>NSCameraUsageDescription</key>
<string>Digital ID uses the camera to capture identity verification images.</string>

// Android · AndroidManifest.xml
<uses-permission android:name="android.permission.CAMERA" />

Data deliveryPengiriman data

Verified data is always delivered as a Privy-signed JWT — regardless of the identity source — through two complementary channels: Data terverifikasi selalu diantar sebagai JWT yang ditandatangani Privy — apapun sumber identitasnya — lewat dua jalur yang saling melengkapi:

1. Exchange code → JWT — the frontend receives a single-use exchange_code via privy:success; the merchant backend swaps it at /v1/sessions/exchange for a JWT with the data. Avoids the token travelling through the front channel. The code & verified data are held briefly in a fast store (in-memory / Redis) with a short TTL, never in the database. Exchange code → JWT — frontend menerima exchange_code sekali-pakai via privy:success; backend merchant menukarnya di /v1/sessions/exchange untuk memperoleh JWT berisi data. Menghindari token melintas front-channel. Kode & data terverifikasi ditahan singkat di penyimpanan cepat (in-memory / Redis) dengan TTL pendek, bukan di basis data.
2. Server-to-server callback (source of truth) — Privy POSTs the same JWT to the merchant callback_url: { session_id, event:"identity.verified", token }. Callback server-to-server (sumber kebenaran) — Privy mem-POST JWT yang sama ke callback_url merchant: { session_id, event:"identity.verified", token }.

Encrypted PII & keysPII terenkripsi & kunci

Identity credentials only. The user's personal data (my_identity) is never delivered in the clear — it arrives encrypted for your key inside the verified-data JWT, only on a successful (verified) event. Your backend decrypts it with your private key; decryption happens on your side, never in the browser. Hanya credential Identity. Data pribadi pengguna (my_identity) tidak pernah dikirim terbuka — data tiba terenkripsi untuk kunci Anda di dalam JWT verified-data, hanya pada event sukses (terverifikasi). Backend Anda yang mendekripsi dengan private key Anda; dekripsi terjadi di sisi Anda, bukan di browser.

Key provisioningPenyediaan kunci

Each merchant credential has its own RSA key pair (unique per merchant). At credential creation you receive the private key once — keep it in your backend secret manager. Privy holds the matching public key and encrypts the PII with it. You are the party that decrypts the delivered payload — keep the private key server-side and never ship it to a browser or mobile app. Setiap credential merchant punya pasangan kunci RSA sendiri (unik per merchant). Saat credential dibuat, Anda menerima private key sekali — simpan di secret manager backend Anda. Privy memegang public key pasangannya dan memakainya untuk mengenkripsi PII. Andalah pihak yang mendekripsi payload yang dikirim — simpan private key di sisi server dan jangan pernah dikirim ke browser atau aplikasi mobile.

Encryption schemeSkema enkripsi

Per-section, direct RSA. Only the sensitive my_identity is encrypted; my_contact_data is delivered plaintext alongside it. The identity payload is compact JSON that fits in a single RSA-4096 block, so it is encrypted directly with RSA-4096 (PKCS#1 v1.5) using your public key — no hybrid/AES. Inside the JWT data claim, my_identity is a base64 ciphertext string: Per-section, RSA langsung. Hanya my_identity sensitif yang dienkripsi; my_contact_data dikirim plaintext di sampingnya. Payload identitas berupa JSON ringkas yang muat dalam satu blok RSA-4096, jadi dienkripsi langsung dengan RSA-4096 (PKCS#1 v1.5) memakai public key Anda — tanpa hybrid/AES. Di dalam klaim data JWT, my_identity berupa string ciphertext base64:

// JWT data claim (Identity credential)
{
  "my_contact_data": { "email": "…", "phone": "…" },   // plaintext
  "my_identity": "<base64 RSA-4096 ciphertext>"          // decrypt → JSON below
}

Decrypting my_identity yields: Mendekripsi my_identity menghasilkan:

{
  "privy_id":        "…",
  "name":            "…",
  "identity_number": "…",                 // NIK
  "dob":             "1998-09-04",
  "email":           "…",
  "phone":           "+62…",
  "identity_card":   "https://…/ktp?token=…",      // KTP image — fetch this URL
  "selfie":          "https://…/selfie?token=…"    // selfie image — fetch this URL
}

Decrypt on your backendDekripsi di backend Anda

import forge from 'node-forge';

// my_identity is a base64 RSA-4096 / PKCS#1 v1.5 ciphertext string
function decryptIdentity(myIdentityB64, rsaPrivateKeyPem) {
  const priv = forge.pki.privateKeyFromPem(rsaPrivateKeyPem);
  const plain = priv.decrypt(forge.util.decode64(myIdentityB64), 'RSAES-PKCS1-V1_5');
  return JSON.parse(plain); // { name, identity_number, dob, … }
}

Verify the JWTVerifikasi JWT

The token is an EdDSA / Ed25519 JWT. Verify its signature on your backend with the JWKS, then read the claims: Token adalah JWT EdDSA / Ed25519. Verifikasi tanda tangannya di backend memakai JWKS, lalu baca klaim:

{
  "iss": "https://id.privy.id",   // issuer
  "sub": "<identity ref>",
  "aud": "<merchant_id>",
  "session_id": "…",
  "merchant": "…",
  // shared data, grouped by section (fields determined by Privy)data yang dibagikan, dikelompokkan per section (field ditentukan Privy)
  "data": {
    "my_contact_data": { "email":"…", "phone":"…" },   // plaintext (both types)
    "my_identity": "<base64 RSA-4096 ciphertext>"          // Identity only — decrypt (see #encrypted)
  },
  "verification": { "method":"phone_lookup+liveness_face_match" },
  "iat": …, "exp": …
}

Security notesCatatan keamanan

• API key stays in the backend. Sessions are created server-side; never expose X-API-Key to the browser.API key hanya di backend. Sesi dibuat server-side; jangan expose X-API-Key ke browser.
• Validate event.origin on the postMessage listener — accept only the widget origin.Validasi event.origin pada listener postMessage — hanya terima dari origin widget.
• Verify the JWT (signature via JWKS + aud/exp/iss) before trusting the data.Verifikasi JWT (signature via JWKS + aud/exp/iss) sebelum mempercayai data.
• The exchange code is useless without the API key — safe to travel the front channel; still single-use & short-lived.Exchange code tak berguna tanpa API key — aman melintas front-channel; tetap single-use & short-lived.
• The iframe must set allow="camera"; register the merchant origin in the allowlist.iframe wajib allow="camera"; daftarkan origin merchant di allowlist.
• Data/token only reach a verified embedder; an unknown host receives the event signal without payload.Data/token hanya sampai ke embedder terverifikasi; host tak dikenal hanya menerima sinyal event tanpa payload.

Error codesKode error

Error shapeFormat error: { "error": { "code": "…", "message": "…" } }

Changelog