API Reference
Glossary
| Term | Definition |
|---|---|
| Digital ID | The Privy identity verification widget that a merchant embeds in a web iframe or native WebView. |
| Merchant | The organization that integrates Digital ID into its application. |
| Data package | The set of user data that a merchant receives. Privy sets it at onboarding: Contact or Identity. Both packages use the same verification journey. |
| Contact package | Delivers contact data only. |
| Identity package | Delivers contact data and identity data. Identity data is encrypted with the merchant public key. |
Contact data (my_contact_data) | The verified email and phone of the user, as readable JWT claims. The user sees it as "My Contact Data". |
Identity data (my_identity) | PrivyID, full name, NIK, date of birth, KTP image URL, and selfie URL, encrypted for the merchant. The user sees it as "My Personal Identity". |
| Credentials | The secrets that Privy issues to a merchant: the merchant API key for each environment and, for the Identity package, the RSA private key. |
| Identifier | The value that the user enters in step 1: a PrivyID, email, NIK, or mobile number. The mobile number can be Indonesian or international. |
| Session | One verification attempt. POST /v1/sessions creates it. Privy controls the order of its steps on its servers. |
session_url | The widget URL from session creation. Load it in an iframe or WebView. |
| Exchange code | A single-use, short-lived code from privy:success. The merchant backend exchanges it for the verified-data JWT. |
| Verified-data JWT | A Privy-signed EdDSA (Ed25519) token. Its data claim contains the verified result. |
| JWKS | The JSON Web Key Set (RFC 7517) of public Ed25519 keys at /.well-known/jwks.json. Use it to verify the JWT. |
| Liveness | Camera-based checks inside the widget that confirm a live person is present. |
| Face match | The Privy comparison of the live selfie with the selfie recorded for that identity. The user has up to three attempts in each session. |
| OTP | The Privy-hosted one-time password step after the face match, for both data packages. Privy sends it by WhatsApp by default, or by email or text message. |
| PrivyID | The Privy identity identifier of the user. |
| NIK | Indonesian national identity number (Nomor Induk Kependudukan). It is one of the accepted identifiers. |
| Consent | The widget step after OTP. The user reviews the shared data and continues or rejects the request. |
| Confirmation window | The time that the user has to respond on the consent screen. The default is 5 minutes. Privy can configure it for each merchant. |
| Front channel | The browser or WebView path for postMessage events. Use it only for user-interface updates. |
| Back channel | Server-to-server communication: session creation, code exchange, and the callback. |
| Embedder | The host page or application that loads the widget. Verified iframe embedders and native WebViews receive payloads. Unknown hosts receive only event types. |
| Callback | The Privy HTTP delivery of the verified result to the configured merchant callback_url. It is one of the two delivery channels for the verified JWT. |
session_id | The Privy identifier of one verification session. Use it to correlate and deduplicate. It does not prove verification success. |
Last modified on