Memulai
Sumber daya inti
Lainnya

Verifikasi dengan SEEK Pass

Verifikasi dengan SEEK Pass menyediakan cara yang lancar untuk memverifikasi kredensial (misalnya identitas digital) melalui SEEK Pass. Untuk integrasi ini, mitra menyematkan tombol dalam alur aplikasi mereka yang mengarahkan pengguna ke aplikasi SEEK Pass, tempat mereka perlu memilih kredensial untuk diverifikasi (misalnya paspor, SIM). Mitra dapat terintegrasi dengan SEEK Pass menggunakan REST API untuk mengautentikasi dan membuat permintaan verifikasi, lalu mengarahkan pengguna ke aplikasi SEEK Pass.Verifikasi dengan SEEK Pass - Alur Perjalanan PenggunaVerifikasi dengan SEEK Pass - Alur kerja Identifikasi Digital

Detail teknis

Ada 3 fase untuk integrasi ini:
  • Mengautentikasi dengan SEEK Pass
  • Mengirimkan permintaan verifikasi
  • Mengambil hasil verifikasi
SEEK Pass mengautentikasi dan mengotorisasi permintaan mitra menggunakan alur OAuth2 Client Credentials untuk autentikasi server-ke-server. Saat onboarding, mitra akan diberikan kredensial OAuth untuk memperoleh token akses JWT untuk panggilan API berikutnya. Kredensial OAuth akan diberikan melalui saluran aman (mis. 1Password).
# POST /api/partner/v1/oauth/token

curl --location $SEEK_PASS_URL/api/partner/v1/oauth/token.json 
--header 'Accept: application/json' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode grant_type=client_credentials 
--data-urlencode client_id=$CLIENT_ID 
--data-urlencode client_secret=$CLIENT_SECRET 
--data-urlencode 'scope=write.digital_identity read.digital_identity'
Setelah terautentikasi, mitra dapat mengirim permintaan verifikasi menggunakan API verifikasi kami (POST /api/partner/v2/verify/requests/digital_identity.json). Payload permintaan berisi URL callback opsional yang akan digunakan untuk mengalihkan pengguna kembali ke lokasi yang ditentukan mitra (mis. aplikasi web) setelah pengguna menyelesaikan alur verifikasi. API ini mengembalikan URI pengalihan yang harus digunakan untuk mengarahkan pengguna ke SEEK Pass. Lihat bagian berikutnya untuk detail lebih lanjut tentang format URI pengalihan.Setelah pengguna menyelesaikan alur verifikasi, mereka akan diarahkan kembali ke URL callback mitra dan hasil verifikasi akan diberikan melalui API atau webhook yang terdaftar. Payload respons berisi ID permintaan, data kredensial pengguna, dan hasil verifikasi. Implementasi keamanan webhook dibahas di bagian berikut.

Payload permintaan

Payload permintaan berisi kolom-kolom berikut:
  • request_id (opsional): Digunakan mitra untuk melacak permintaan mereka. Jika tidak diberikan, akan dibuat secara otomatis.
  • callback_url (opsional): Pengguna akan dialihkan kembali ke URL ini, jika disediakan, setelah menyelesaikan alur.
  • display_options (required): Nilai partner_name yang wajib diisi akan ditampilkan kepada pengguna. partner_logo_url juga dapat disediakan.
  • request_source (opsional): Kolom ini mencatat hierarki pihak-pihak yang terlibat dalam permintaan verifikasi (mis. ATS).
  • metadata (opsional): Kolom ini menangkap informasi tambahan yang dibutuhkan SEEK Pass untuk pelaporan atau tujuan lain. Untuk SEEK/Indirect, kami akan mencatat informasi terkait pekerjaan.
  • options (opsional): Parameter opsional untuk mengonfigurasi pengalaman SEEK Pass.
    • email_hint (opsional): Mengisi otomatis alamat email pengguna di layar masuk. Pengguna dapat memasukkan alamat email yang berbeda jika diinginkan.
    • locale (opsional): Menetapkan bahasa awal untuk alur verifikasi.
Info
Jika request_id tidak disertakan di payload permintaan, SEEK Pass akan membuat ID permintaan unik secara otomatis. Kami menyarankan menggunakan nilai unik secara global (mis. UUID) untuk request_id agar pelacakan permintaan pengguna berjalan baik.
Contoh permintaan verifikasi:
# POST /api/partner/v2/verify/requests/digital_identity.json

{
  "request_id": "7cbc7e51-82f5-43ec-8d63-b7cdf1170425",  // Optional. For tracking requests. If not passed, it will be auto-generated.
  "callback_url": "https://www.partner.com/callback",    // Optional. For redirecting users
  "display_options": {           // Required
    "partner_name": "string",    // Required
    "partner_logo_url": "string" // Optional
  },
  "request_source": [            // Optional
    {
      "name": "string"
    }
  ],
  "metadata": {                  // Optional - context about the verification
    "position_title": "string",
    "position_url": "string",
    "position_location": "string",
    "job_categories": "string",
    "applied_on_seek": true
  },
  "options": {                   // Optional - configure the SEEK Pass experience
    "email_hint": "string",      // Optional. Pre-fills the user's email address
    "locale": "string"           // Optional. Sets the language for the verification flow (e.g. en-AU)
  }
}
Contoh respons verifikasi:
{
  "request_id": "7cbc7e51-82f5-43ec-8d63-b7cdf1170425",
  "redirect_uri": "https://app.seekpass.co/partner/verify/digitalIdentity?clientId=[CLIENT_ID]&requestId=fa651300-b91a-49cb-8ee7-cac68b3fdf74"
}

Perilaku

  • Penggunaan ulang ID saat permintaan tertunda: Membuat permintaan dengan ID yang sudah ada kapan pun saat permintaan belum difinalisasi akan menghasilkan error. Selalu periksa status permintaan yang sudah ada dan tentukan apakah pengguna harus diarahkan ke permintaan yang sudah ada atau dibuatkan permintaan baru.
  • Asosiasi pengguna: Saat pengguna mengakses redirect_uri dan melakukan otentikasi, data kredensial menjadi terkait dengan akun mereka.
  • Kedaluwarsa Permintaan yang Belum Terkait: Jika pengguna gagal mengakses redirect_uri dan memulai pengajuan mereka dalam 48 jam, permintaan akan otomatis dibatalkan dan data asli akan dihapus secara permanen. Setelah titik ini, permintaan yang ada akan difinalisasi dan dibatalkan, dan Anda dapat menggunakan kembali ID yang sama untuk membuat permintaan baru yang akan dikirim kepada pengguna.
  • Kedaluwarsa Permintaan Terkait: Pengguna dapat mengakses redirect_uri, tetapi kemudian keluar dan tidak mengonfirmasi penambahan kredensial ke akun mereka. Pengguna memiliki waktu hingga 30 hari untuk kembali ke platform dan mengonfirmasi, tergantung pada jenis kredensial. Setelah periode ini, permintaan tersebut akan difinalisasi dan dibatalkan, dan Anda dapat menggunakan kembali ID yang sama untuk membuat permintaan baru yang dikirim kepada pengguna.
  • Alur persetujuan: Data kredensial terkait dengan akun pengguna saat otentikasi, terlepas dari status persetujuan. Jika persetujuan belum diberikan, redirect_uri akan meminta pengguna untuk menyetujui.
  • Perilaku setelah persetujuan: Setelah persetujuan diberikan, saat pengguna mengakses redirect_uri yang sama, pengguna akan diarahkan ke kredensial yang telah mereka ajukan.
  • Kebijakan retensi data: Jika pengguna menyelesaikan alur pengguna tetapi tidak mengunduh dan melakukan autentikasi melalui aplikasi seluler dalam 48 jam, semua dokumen terkait akan dihapus secara aman sesuai kebijakan perlindungan data.
Info
Setelah pengguna mengklik tautan dan masuk ke sistem, data tersebut hanya terkait dengan pengguna tersebut. Jika pengguna lain mencoba menggunakan tautan yang sama, mereka akan diarahkan ke halaman error.

Diagram urutan

Verifikasi dengan SEEK Pass - Diagram Urutan

akun SEEK Pass

SEEK Pass akan menyediakan kredensial OAuth bagi mitra untuk autentikasi di lingkungan staging dan produksi:
  • Endpoint token OAuth: POST /api/partner/v2/oauth/token.json
  • Host:
    • Produksi: https://app.seekpass.co
    • Staging: https://app.seekpass-staging.com
  • Kredensial klien akan diberikan melalui saluran yang aman (misalnya 1Password)

Tombol Verifikasi dengan SEEK Pass

SEEK Pass menyediakan pilihan gambar tombol untuk mitra kami yang dapat disematkan untuk ditampilkan di platform Anda. Gambar-gambar ini akan dirender dengan branding SEEK Pass, sehingga memastikan konsistensi di seluruh interaksi pengguna. Kami menyarankan penggunaan aset tombol yang disediakan jika memungkinkan untuk mempertahankan gaya yang terpadu dan sesuai merek. Contoh tombol ditampilkan di bawah ini. Untuk detail lebih lanjut, lihat dokumentasi API kami - Panduan Branding.

Struktur URI pengalihan

  • Path: /partner/verify/[Credential type]
  • Host:
    • Produksi: https://app.seekpass.co
    • Staging: https://app.seekpass-staging.com
  • Query: Parameter di bawah ini sebagai parameter query URL
    • clientId: ID Aplikasi OAuth
    • requestId: ID permintaan verifikasi
  • Contoh: https://app.seekpass-staging.com/partner/verify/digitalIdentity?clientId=[CLIENT_ID]&requestId=fa651300-b91a-49cb-8ee7-cac68b3fdf74

Hasil verifikasi

Data verifikasi dan hasil permintaan diberikan melalui API atau webhook yang didaftarkan mitra. SEEK Pass dapat memberikan pembaruan webhook untuk berbagai peristiwa pada tahap yang berbeda dalam alur kerja verifikasi. Contoh peristiwa tercantum di bawah ini:
  • incomplete
  • canceled (rejected, canceled, expired)
  • verified
ChevronSebelumnya: Periksa status pengajuan
Berikutnya: Periksa status pengajuanChevron