Autentikasi

Markdown

Panduan ini memandu Anda melakukan autentikasi di Human Dashboard dan membuat x-unico-accesskey yang akan Anda gunakan di semua permintaan Human Token API.

Alurnya terdiri dari dua fase:

Autentikasi — selesaikan login dan dapatkan token akses. Tersedia dua metode autentikasi:
- Login biometrik — pengambilan wajah melalui Unico SDK (tersedia untuk pendaftaran maupun masuk)
- Login OTP email — kode sekali pakai yang dikirim ke alamat email terdaftar (hanya untuk masuk)
Siapkan organisasi Anda — buat profil perusahaan Anda dan buat kunci akses (hanya pada pendaftaran pertama)

Dua cara menyiapkan kredensial Anda

Semua yang ada di panduan ini juga dapat dilakukan melalui Human Dashboard di dashboard.unico.app — tanpa perlu panggilan API.

Opsi	Kapan digunakan
Dashboard	Pengaturan pertama, rotasi kunci manual, pengelolaan sesekali
API	Penyediaan otomatis, pipeline CI/CD, pengelolaan kunci secara programatik

Menggunakan dashboard

Buka dashboard.unico.app
Daftar atau masuk — gunakan login biometrik (pengambilan wajah) atau OTP email
Buat organisasi Anda — isi nama perusahaan, negara, dan domain yang diizinkan
Buat kunci akses — buka Access Keys dan klik Create key; salin segera, kunci hanya ditampilkan satu kali
Kelola cabang — buat dan konfigurasikan cabang di Branches; setiap cabang menghasilkan kunci aksesnya sendiri

Kunci akses yang Anda dapatkan dari dashboard adalah x-unico-accesskey yang sama yang digunakan dalam semua permintaan API — kedua pendekatan sepenuhnya dapat dipertukarkan.

URL Dasar

Setiap endpoint di halaman ini dilayani oleh Human Dashboard API. Permintaan Human Token API, seperti Create Process dan Get Process, dikirim ke host API yang tercantum di Environment.

Lingkungan	API	URL Dasar
Produksi	Human Dashboard API (login, organisasi, kunci akses, dan cabang)	`https://api.humantoken.unico.app`

Metode autentikasi

Tersedia dua metode untuk mengautentikasi dan mendapatkan authToken:

Metode	Endpoint	Kapan digunakan
Biometrik	`POST /api/console/v1/auth/biometric/sessions`	Pendaftaran (akun baru) atau masuk (pengguna lama)
OTP email	`POST /api/console/v1/auth/email/sessions`	Hanya untuk masuk — akun harus sudah ada

Setiap panggilan ke POST /api/console/v1/auth/biometric/sessions harus mendeklarasikan intent:

`intent`	Kapan digunakan	Field `email`	Field `name`
`LOGIN_INTENT_SIGNUP`	Pendaftaran pertama — membuat akun baru	Wajib	Wajib
`LOGIN_INTENT_SIGNIN`	Pengguna lama — akun sudah ada	Tidak digunakan	Tidak digunakan
(dihilangkan)	Diperlakukan sebagai `LOGIN_INTENT_SIGNIN`	Tidak digunakan	Tidak digunakan

Intent mengontrol validasi yang dilakukan saat Anda melakukan polling sesi (Langkah 2):

SIGNUP — menolak login jika identitas biometrik tersebut sudah terdaftar (mencegah akun duplikat).
SIGNIN — menolak login jika identitas biometrik tersebut belum terdaftar (akun harus ada untuk bisa login).

Fase 1 — Autentikasi

SIGNUP (pendaftaran pertama)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'

Keunikan email

Jika sudah ada akun yang terdaftar dengan email tersebut, permintaan mengembalikan 400 Bad Request.

Respons:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

Untuk SIGNUP, field link dan token kosong dalam respons — tautan pengambilan biometrik dikirim ke alamat email yang diberikan.

SIGNIN (pengguna lama)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

Respons:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Simpan sessionId.

SIGNUP: tautan pengambilan biometrik dikirim ke email yang diberikan di Langkah 1. Minta pengguna memeriksa kotak masuk mereka dan menyelesaikan pengambilan.
SIGNIN: buka link di browser Anda dan selesaikan pengambilan biometrik.

Langkah 2: Lakukan polling hingga sesi terselesaikan

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

Lakukan polling setiap 2–3 detik hingga status mencapai status akhir.

`status`	`outcome`	Arti
`pending`	`pending`	Pengguna belum menyelesaikan pengambilan — lanjutkan polling
`processing`	`pending`	Pengambilan selesai, hasil sedang dihitung — lanjutkan polling
`completed`	`matched`	Login berhasil — `authToken` tersedia
`completed`	`no_match`	Biometrik tidak cocok dengan catatan mana pun
`completed`	`inconclusive`	Pengambilan berhasil tetapi tidak dapat diselesaikan
`expired`	—	Tautan kedaluwarsa — mulai ulang dari Langkah 1
`canceled`	—	Sesi dibatalkan — mulai ulang dari Langkah 1

Error tambahan khusus intent saat melakukan polling sesi:

HTTP	Kondisi
`400`	SIGNUP — identitas biometrik sudah terdaftar (akun duplikat)
`400`	SIGNIN — identitas biometrik belum terdaftar (akun tidak ada)

Respons berhasil:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Simpan authToken — gunakan sebagai header x-console-authorization di semua permintaan Human Dashboard API berikutnya.

Fase 1 (alternatif) — Masuk dengan OTP email

Gunakan alur ini sebagai pengganti biometrik jika pengguna sudah memiliki akun dan lebih memilih mengautentikasi melalui kode sekali pakai yang dikirim ke email terdaftarnya. Pendaftaran tidak didukung melalui OTP email — gunakan alur biometrik untuk pendaftaran pertama.

Langkah 1: Kirim OTP

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

catatan

Email harus milik akun yang sudah ada. Jika akun tidak ditemukan, Langkah 2 (validasi OTP) mengembalikan 404 Not Found.

Respons:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

Simpan sessionId. Kode 6 digit dikirim ke alamat email yang diberikan.

Langkah 2: Validasi OTP

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	Kondisi
`200`	Kode valid — `authToken` tersedia
`400`	Kode salah (`invalid otp code`)
`400`	OTP sudah digunakan, batas percobaan tercapai, atau kedaluwarsa
`404`	Email tidak terdaftar

Respons berhasil:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Simpan authToken — gunakan sebagai header x-console-authorization di semua permintaan Human Dashboard API berikutnya.

Fase 2 — Siapkan organisasi Anda

Langkah 3: Buat organisasi Anda

catatan

Panggilan ini hanya dapat dilakukan satu kali. Panggilan ini menyediakan tenant Anda dan menghasilkan branchId Anda.

Negara mana pun diterima. Gunakan kode tiga huruf ISO 3166-1 alpha-3 (misalnya BRA, USA, MEX, DEU, IND). taxId bersifat opsional untuk semua negara.

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

Respons:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

Simpan branchId — nilai ini mengidentifikasi cabang default Anda dan digunakan saat mengelola cabang dan kunci akses.

Langkah 4: Buat kunci akses

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

Respons:

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}

peringatan

accessKey hanya dikembalikan satu kali dan tidak dapat diambil kembali. Segera simpan di pengelola rahasia Anda sebagai HUMAN_TOKEN_ACCESS_KEY.

Nilai ini adalah header x-unico-accesskey yang digunakan di semua permintaan Human Token API.

Yang sekarang Anda miliki

Nilai	Tempat menggunakannya
`branchId`	Mengidentifikasi cabang default Anda; membuat kunci akses khusus cabang
`accessKey`	Header `x-unico-accesskey` di semua permintaan Human Token

Mengelola organisasi Anda

Dapatkan organisasi

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

Respons:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

Perbarui organisasi

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

Mengelola kunci akses

Daftar kunci (hanya metadata — rahasia tidak pernah dikembalikan):

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

Rotasi kunci (kunci lama langsung tidak berlaku):

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

Cabut kunci (tidak dapat dibatalkan):

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

Mengelola cabang

Cabang memungkinkan Anda membagi konfigurasi organisasi (nama, logo, domain yang diizinkan) per produk atau lingkungan. Setiap cabang memiliki kunci aksesnya sendiri, sehingga konteks cabang ditentukan secara otomatis dari kunci yang digunakan dalam permintaan — tidak perlu mengirim branchId di CreateProcess.

Buat cabang

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

Respons:

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

Simpan branchId — gunakan saat membuat kunci akses khusus cabang.

Perbarui cabang

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

Buat kunci akses khusus cabang

Untuk membuat kunci akses yang dibatasi pada cabang tertentu, sertakan branchId dalam body permintaan:

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

Respons:

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}

peringatan

accessKey hanya dikembalikan satu kali. Segera simpan. Setiap permintaan CreateProcess yang diautentikasi dengan kunci ini akan otomatis menggunakan konfigurasi cabang yang terkait dengannya.

Dua cara menyiapkan kredensial Anda​

Menggunakan dashboard​

URL Dasar​

Metode autentikasi​

Intent login biometrik​

Fase 1 — Autentikasi​

Langkah 1: Mulai sesi login biometrik​

Langkah 2: Lakukan polling hingga sesi terselesaikan​

Fase 1 (alternatif) — Masuk dengan OTP email​

Langkah 1: Kirim OTP​

Langkah 2: Validasi OTP​

Fase 2 — Siapkan organisasi Anda​

Langkah 3: Buat organisasi Anda​

Langkah 4: Buat kunci akses​

Yang sekarang Anda miliki​

Mengelola organisasi Anda​

Dapatkan organisasi​

Perbarui organisasi​

Mengelola kunci akses​

Mengelola cabang​

Buat cabang​

Perbarui cabang​

Buat kunci akses khusus cabang​

Dua cara menyiapkan kredensial Anda

Menggunakan dashboard

URL Dasar

Metode autentikasi

Intent login biometrik

Fase 1 — Autentikasi

Langkah 1: Mulai sesi login biometrik

Langkah 2: Lakukan polling hingga sesi terselesaikan

Fase 1 (alternatif) — Masuk dengan OTP email

Langkah 1: Kirim OTP

Langkah 2: Validasi OTP

Fase 2 — Siapkan organisasi Anda

Langkah 3: Buat organisasi Anda

Langkah 4: Buat kunci akses

Yang sekarang Anda miliki

Mengelola organisasi Anda

Dapatkan organisasi

Perbarui organisasi

Mengelola kunci akses

Mengelola cabang

Buat cabang

Perbarui cabang

Buat kunci akses khusus cabang