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. Ada dua pihak: Merchant (yang meng-embed) dan Privy (yang memverifikasi identitas). Seluruh proses berjalan di dalam widget Privy.

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. 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.

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):

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 shape received by the native bridgebentuk JSON yang diterima bridge native
{ "type":"privy:success", "payload":{ "session_id":"…", "exchange_code":"…" } }

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 }.

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_personal_identity": { "full_name":"…", "identity_number":"…" },
    "my_contact_data": { "email":"…", "phone":"…" }
  },
  "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