Panduan integrasi API eID: pola, kode, dan keamanan

Terakhir ditinjau: 5 Oktober 2026 · Bukan nasihat hukum

Panduan berbasis kode ini ditujukan bagi engineer yang menambahkan eID nasional ke proses onboarding.

Cara kerja API eID: lima pola interaksi

Sistem Anda adalah pihak pengandal (relying party, RP). Sistem Anda tidak pernah melihat kredensial itu sendiri, hanya jawaban bertanda tangan tentang orang tersebut.

Sebagian skema berada di balik gateway publik: TARA milik Estonia adalah gateway authorization code yang berada di depan kartu identitas, Smart-ID, Mobile-ID, dan eID Uni Eropa.^[7] Lihat skema eID per negara untuk mengetahui pola yang digunakan setiap skema.

Apa yang Anda bangun dan apa yang ditangani penyedia

Akses datang sebelum kode. Di Denmark, setiap penyedia layanan wajib melalui broker MitID yang tersertifikasi.^[12] Di Swedia, Anda membeli BankID dari bank atau peritel dan memesan sertifikat pihak pengandal (relying party).^[15] Di Jerman, Anda menjalankan server eID sendiri, menggunakan layanan eID yang di-hosting dengan sertifikat Anda sendiri, atau menggunakan layanan identifikasi tanpa memegang sertifikat sendiri.^[13] Untuk Dompet EUDI, pihak pengandal wajib mendaftar di Negara Anggota tempat pihak tersebut didirikan.^[1]

Broker bersertifikat tersedia untuk sebagian besar skema Nordik dan Baltik. Terhubunglah langsung jika Anda memakai satu skema dengan volume tinggi. Gunakan satu API jika pengguna berasal dari beberapa negara.

Alur pengalihan, langkah demi langkah

Ini adalah alur kode otorisasi OIDC. Backend Anda mengarahkan browser keluar dengan state dan nonce acak, lalu menukar kode yang dikembalikan dengan token ID dan memeriksanya.

Proses masuk melalui pengalihan (redirect). Broker dan gateway menambah lompatan (hop) di langkah 2, bukan langkah baru bagi Anda.

Pemeriksaan setelah langkah 5 adalah yang paling penting. Menurut dokumentasi ID-porten dari Digdir, klien "WAJIB memvalidasi bahwa tingkat keamanan (acr) cukup tinggi".^[5] Baca acr sebagai tingkat jaminan (level of assurance, LoA) yang dinyatakan oleh skema, dan tolak apa pun yang berada di bawah kebijakan Anda.

Alur notifikasi push aplikasi dengan kode pembanding

Smart-ID dan Mobile-ID tidak pernah meninggalkan halaman Anda. Pengguna mengetikkan kode identifikasi pribadi (Mobile-ID juga meminta nomor telepon), halaman Anda menampilkan kode pendek, dan kode yang sama muncul di aplikasi. Pengguna menyetujui dengan PIN di ponsel hanya jika kodenya cocok.^[20] Smart-ID juga dapat menampilkan tiga kode dan meminta pengguna memilih kode yang benar.^[10]

BankID Sweden memiliki pola yang sama, tetapi memakai QR alih-alih kode yang diketik: pengguna membuka aplikasi di perangkat yang sama dengan token autostart, atau memindai QR animasi yang ditampilkan di perangkat lain, dan backend Anda melakukan polling ke /collect sampai order selesai. Order yang selesai memuat nomor identitas pribadi, nama, nama depan dan nama keluarga, ditambah kolom perangkat, tanda tangan, dan kolom risiko opsional.^[8] Smart-ID+ memindahkan Smart-ID ke model ini (QR dinamis di desktop, app-to-app di perangkat seluler), sehingga pengguna tidak lagi mengetik kode pribadi di situs web.^[11]

Proses masuk dengan Smart-ID atau Mobile-ID, sesuai urutan yang dilihat pengguna: kode pribadi, kode pembanding di halaman Anda, kode yang sama di aplikasi, lalu PIN.^[20] Pada varian QR BankID, langkah 1 hilang dan langkah 2 menampilkan kode QR.

Kartu dan NFC, serta Dompet EUDI melalui OpenID4VP

Dengan kartu eID Jerman, pengguna menempelkan kartu ke ponsel NFC di AusweisApp. Sebelum PIN diketik, undang-undang mewajibkan aplikasi menampilkan nama dan alamat penyedia serta kategori data yang diminta, dan hanya kategori tersebut yang dikirim.^[14]

Menurut OpenID Foundation, OpenID4VP 1.0 adalah spesifikasi final.^[16] Architecture and Reference Framework (ARF) mencantumkan presentasi jarak jauh sebagai OpenID4VP melalui pengalihan (redirect) dan skema URI khusus seperti openid4vp://, OpenID4VP melalui W3C Digital Credentials API, atau ISO/IEC 18013-7 melalui API tersebut.^[2][17] Sebelum membagikan apa pun, dompet mengautentikasi sertifikat akses Anda, memeriksa bahwa Anda tidak meminta atribut lebih banyak daripada yang Anda daftarkan, dan membiarkan pengguna menyetujui setiap atribut.^[2] Foto wajah baru menjadi wajib dalam data identifikasi pribadi (PID) mulai 11 Agustus 2028, kecuali jika pengguna secara tegas memilih untuk tidak menyertakannya.^[18]

1. 23 Juli 2026ARF v3.0.0Versi terkini kerangka kerja dompet.
2. 24 Desember 2026Tenggat dompetSetiap Negara Anggota menyediakan setidaknya satu dompet.
3. 24 Desember 2027PenerimaanPihak pengandal swasta yang diwajibkan oleh hukum atau kontrak untuk menggunakan autentikasi pengguna yang kuat menerimanya atas permintaan pengguna. Usaha mikro dan kecil dikecualikan.
4. 11 Agustus 2028Foto wajahFoto wajah dalam PID menjadi wajib kecuali pengguna memilih untuk tidak menyertakannya.

Tanggal-tanggal Dompet EUDI yang membentuk peta jalan API eID.^[1][2][18]

Panduan Dompet EUDI membahas pendaftaran pihak pengandal dan kesiapan per negara.

Kesalahan, fallback, dan percobaan ulang

Proses masuk berakhir dengan status selesai, dibatalkan, habis waktu, atau gagal. Tangani tiga status terakhir dengan cara yang sama, lalu tentukan per negara apa langkah berikutnya.

Jangan pernah mengulang secara otomatis proses masuk yang dibatalkan. Buat callback bersifat idempoten, sehingga muat ulang halaman atau peristiwa duplikat tidak dapat membuka dua akun. Sediakan jalur bagi orang yang tidak memiliki eID, biasanya dokumen identitas dengan pembacaan chip NFC, deteksi liveness, dan pencocokan wajah. Verifikasi eID NFC dan keamanan chip membahas jalur tersebut.

Daftar periksa keamanan untuk integrasi API eID

• Buat state dan nonce baru untuk setiap proses masuk dan tolak callback yang tidak cocok dengan keduanya.
• Verifikasi tanda tangan setiap token atau hasil sebelum membaca satu atribut pun.
• Periksa tingkat jaminan pada hasil, bukan hanya pada permintaan.^[5]
• Wajibkan tingkat substansial atau tinggi jika jalur eID AMLR berlaku bagi Anda.^[3]
• Jangan pernah mengumpulkan PIN eID di halaman Anda. PIN tersebut hanya dimasukkan di aplikasi skema.^[20]
• Utamakan QR atau peluncuran app-to-app daripada kode yang diketik untuk login lintas perangkat.^[11]
• Minta hanya atribut yang Anda daftarkan dan Anda butuhkan.^[1]
• Verifikasi tanda tangan dan stempel waktu webhook sebelum Anda memercayai suatu hasil.

Dasar hukumnya adalah Peraturan Anti Pencucian Uang (AMLR), yang berlaku mulai 10 Juli 2027: Pasal 22(6)(b) mengizinkan "sarana identifikasi elektronik yang memenuhi persyaratan Peraturan (UE) No 910/2014 terkait tingkat jaminan 'substansial' atau 'tinggi'".^[3] Tidak semua skema telah dinotifikasi: MitID tercantum dalam daftar skema yang dinotifikasi di UE, sedangkan Smart-ID tidak.^[4]

Bagaimana Didit membantu integrasi API eID

Didit menyediakan lima eID aktif di balik satu API sesi (MitID, BankID Swedia, Finnish Trust Network, Smart-ID dan Mobile-ID, di tujuh negara), dengan jalur dokumen dalam workflow yang sama. Skema lain ada dalam roadmap Didit, dan penerimaan Dompet EUDI akan segera hadir. Didit tidak pernah meminta PIN. Informasi lebih lanjut ada di halaman dompet ID digital dan di dokumentasi dompet.^[19]

Aktifkan eID aktif per negara

Di konsol: Workflows, langkah ID Verification, Countries, "Wallets accepted". Melalui API, fitur ID Verification (OCR) menerima objek methods dengan kunci berupa kode negara ISO 3166-1 alpha-3, yang dikirim dengan POST /v3/workflows/. Fragmen yang terdokumentasi untuk Denmark:^[21]

{ "feature": "OCR", "config": { "methods": { "DNK": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" } } } } }

Dan untuk Estonia, dengan menerima kedua eID berbasis ponsel:^[20]

{ "EST": { "document": { "enabled": true }, "wallet": { "enabled": true, "providers": ["smart_id", "mobile_id"], "on_failure": "fallback_to_document" } } }

providers adalah daftar penerimaan, bukan urutan peringkat. on_failure bernilai fallback_to_document atau decline. Dompet yang tidak tersedia di lingkungan Anda membuat seluruh penyimpanan ditolak, jadi baca katalog terlebih dahulu.^[21]

Buat sesi dan baca hasilnya

POST /v3/session/ dengan workflow_id Anda (dan secara opsional vendor_data serta callback) mengembalikan session_id, url, dan session_token. Buka URL tersebut atau gunakan SDK.^[24] Hasilnya dikirim melalui webhook atau GET /v3/session/{id}/decision/, dengan verification_method: "wallet", assurance: "cryptographic", dan objek wallet_verification.^[19]

Tingkat yang lebih rendah dari yang diminta membuat proses masuk gagal. Hanya proses masuk yang selesai yang ditagih.^[19] Harga: MitID, Finnish Trust Network $0.25; BankID Sweden, Smart-ID, Mobile-ID $0.20.

Webhook dan sandbox

Verifikasi X-Signature-V2 dengan secret tujuan Anda, tolak X-Timestamp yang lebih lama dari 300 detik, dan gunakan event_id sebagai kunci idempotensi. Pengiriman yang gagal dicoba ulang hingga dua kali.^[22] Aplikasi sandbox dapat mengaktifkan semua dompet, memberikan persetujuan tanpa proses masuk yang sebenarnya, dan menyediakan wallet_cancelled, wallet_timeout, serta wallet_provider_error untuk menguji mekanisme fallback Anda.^[23]

Pertanyaan yang sering diajukan

Sumber

1. Regulation (EU) 2024/1183 (eIDAS 2), EUR-Lex, Jurnal Resmi tanggal 30 April 2024, Pasal 5a, 5b, dan 5f.
2. Architecture and Reference Framework v3.0.0, proyek Dompet EUDI Komisi Eropa, dirilis 23 Juli 2026, bagian 4.4.3, 5.7.1, dan 6.6.3.
3. Regulation (EU) 2024/1624 (AMLR), EUR-Lex, Pasal 22(6).
4. Ikhtisar skema eID yang telah dipranotifikasi dan dinotifikasi berdasarkan eIDAS, Komisi Eropa, diakses 5 Oktober 2026.
5. Token ID ID-porten, Badan Digitalisasi Norwegia (Digdir).
6. Anbindung mit OpenID Connect, dokumentasi pengembang ID Austria.
7. Spesifikasi teknis TARA, Otoritas Sistem Informasi Estonia (RIA).
8. Autentikasi dan penandatanganan: collect, dokumentasi pengembang BankID.
9. QR-koden gjorde susen: BankID-bedrägerierna ned med 90 procent, Computer Sweden, 3 Juli 2019 (sekunder).
10. Mengapa saya terkadang melihat satu kode konfirmasi dan terkadang tiga, Smart-ID.
11. Bagaimana Smart-ID yang baru melindungi saya dari penipuan, Smart-ID.
12. Broker MitID, Badan Pemerintahan Digital Denmark.
13. Menjadi penyedia layanan, AusweisApp, pemerintah federal Jerman.
14. Pasal 18 Undang-Undang Paspor dan Kartu Identitas (PAuswG), Gesetze im Internet.
15. Hubungkan bisnis Anda ke BankID, BankID.
16. Spesifikasi final OpenID for Verifiable Presentations 1.0 disetujui, OpenID Foundation.
17. Digital Credentials, W3C.
18. Peraturan Pelaksana Komisi (EU) 2026/1731, EUR-Lex, foto wajah dalam PID mulai 11 Agustus 2028.
19. Dompet identitas digital, dokumentasi Didit.
20. Integrasi Smart-ID dan Mobile-ID, dokumentasi Didit.
21. Konfigurasi fitur workflow, dokumentasi Didit.
22. Webhook, dokumentasi Didit.
23. Sandbox dan data uji, dokumentasi Didit.
24. Mulai cepat, dokumentasi Didit.

Lihat setiap eID nasional, levelnya, dan statusnya di halaman verifikasi eID.