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 Pengguna

Verifikasi 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/v2/oauth/token

curl --location $SEEK_PASS_URL/api/partner/v2/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 diotentikasi, mitra dapat mengirimkan permintaan verifikasi menggunakan API verifikasi kami (POST /api/partner/v2/verify/requests/digital_identity.json). Silakan merujuk ke Spesifikasi OpenAPI V2 kami untuk skema payload permintaan. Payload permintaan berisi URL callback opsional yang akan digunakan untuk mengarahkan pengguna kembali ke lokasi yang ditentukan mitra (misalnya aplikasi web) setelah pengguna menyelesaikan alur verifikasi. API ini mengembalikan URI pengalihan yang harus digunakan untuk mengarahkan pengguna ke SEEK Pass. Rujuk ke bagian selanjutnya 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.

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

Asosiasi Pengguna: Saat pengguna mengakses redirect_uri dan melakukan autentikasi, permintaan tersebut menjadi terkait dengan akun mereka.
Kedaluwarsa Permintaan yang Tidak Terkait: Jika pengguna gagal mengakses redirect_uri dan memulai pengajuan mereka dalam waktu 30 hari, permintaan akan dibatalkan secara otomatis dan data asli akan dihapus secara permanen.
Menggunakan Kembali ID Permintaan: Setelah permintaan selesai atau dibatalkan, Anda dapat menggunakan kembali request_id yang sama untuk membuat permintaan baru.
Perilaku Pengajuan yang Sedang Berlangsung: Jika pengguna telah memulai pengajuan tetapi belum menyelesaikannya, dan mengakses redirect_uri yang sama, pengguna akan diarahkan ke pengajuan yang sedang berlangsung untuk melanjutkan.
Perilaku Setelah Pengajuan: Setelah pengajuan selesai dan pengguna mengakses redirect_uri yang sama, pengguna akan diarahkan ke kredensial yang diajukan.

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

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 aset tombol bermerek dan panduan desain kode QR kepada mitra kami yang dapat disematkan untuk ditampilkan di platform Anda. Gambar-gambar ini akan ditampilkan dengan merek SEEK Pass untuk memastikan konsistensi di seluruh interaksi pengguna. Kami menyarankan untuk mengikuti aset dan panduan yang disediakan jika memungkinkan guna memastikan pengalaman yang konsisten dan sesuai dengan merek.Kami menyarankan untuk menggunakan kode QR untuk pengalaman di perangkat bersama, dan tombol untuk pengalaman yang diakses di perangkat pribadi pengguna.Contoh tombol ditampilkan di bawah ini. Untuk informasi lebih lanjut, silakan merujuk ke dokumentasi API - Panduan Merek kami.

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 disediakan melalui API atau webhook yang didaftarkan mitra. SEEK Pass dapat memberikan pembaruan webhook untuk berbagai peristiwa pada berbagai tahap alur kerja verifikasi. Lihat Hasil verifikasi melalui API Status atau Hasil verifikasi melalui Webhook.

Sebelumnya: Cabut permintaan

Berikutnya: Periksa status pengajuan