Dokumentasi / SDK Pengenalan Wajah Dan Liveness / Autentikasi Dan API Key

Autentikasi Dan API Key

Cara sistem Anda memanggil API Face SDK dengan API key, izin (scope) apa saja yang dapat dimiliki sebuah key, serta cara galat dan batas laju dikembalikan.

Mengirim Key

Setiap panggilan API memerlukan API key, di salah satu header, kecuali beberapa panggilan layanan hanya-baca (GET /healthz, GET /v2/info, GET /v2/licence, GET /v2/models, GET /v2/openapi.json) dan penyiapan penggunaan pertama:

curl http://localhost:8080/v2/identities -H "x-api-key: $API_KEY"

curl http://localhost:8080/v2/identities -H "Authorization: Bearer $API_KEY"

Key pertama dicetak sekali saat pertama kali dijalankan. Buat key lain di dasbor pada API keys (admin), masing-masing ditampilkan sekali: server hanya menyimpan hash-nya.

Scope

Beri setiap sistem key sendiri dengan hanya izin yang diperlukannya.

Scope	Mengizinkan
`enrol`	Menambah, menampilkan daftar dan menghapus orang
`verify`	Membandingkan dua foto, memeriksa foto terhadap seseorang, mendeteksi wajah
`identify`	Mencari wajah di antara orang yang terdaftar
`liveness`	Pemeriksaan liveness
`streams`	Kamera, aliran peristiwa dan aliran webcam
`admin`	Pengaturan, key, log audit dan log permintaan

Panggilan tanpa scope yang diperlukan dijawab 403 FORBIDDEN, dengan menyebutkan scope yang kurang.

Referensi API di dasbor dengan setiap panggilan, parameternya, dan contoh kode

Permintaan Dan Jawaban

Kirim foto sebagai data formulir multipart (-F image=@photo.jpg) atau sebagai base64 di JSON. JPEG, PNG, WebP dan BMP, hingga 10 MB.
Jawaban berupa JSON. Setiap keputusan cocok membawa nilai kemiripan dan ambang yang menentukannya.

Galat

Galat berupa dokumen application/problem+json dengan code yang tetap:

{
  "type": "https://errors.arsa.technology/face-sdk/pose_yaw",
  "title": "POSE_YAW",
  "status": 422,
  "code": "POSE_YAW",
  "detail": "the face is turned too far"
}

Status	Kode
400	`BAD_REQUEST`, `UNSUPPORTED_IMAGE`, `IMAGE_DIMENSIONS`
401	`UNAUTHORIZED`, `LICENSE_INVALID`
403	`FORBIDDEN`, `FEATURE_DISABLED`
404	`NOT_FOUND`
409	`CONFLICT`, `POSSIBLE_DUPLICATE`, `NEEDS_REENROLMENT`
413	`PAYLOAD_TOO_LARGE`
422	Masalah foto: `NO_FACE`, `MULTIPLE_FACES`, `FACE_TOO_SMALL`, `FACE_CROPPED`, `POSE_YAW`, `POSE_PITCH`, `POSE_ROLL`, `BLURRY`, `TOO_DARK`, `TOO_BRIGHT`, `UNEVEN_LIGHT`, `EYES_CLOSED`, `EXPRESSION`, `LOW_QUALITY`, `INCONSISTENT_ENROLMENT_IMAGES`
429	`RATE_LIMITED`, `LICENSE_LIMIT`
503	`QUEUE_FULL` (coba lagi sebentar lagi)

API v1

Klien yang ditulis untuk Face SDK v1 tetap berfungsi: API v1 dilayani di /api/v1 dengan path, header dan kolom yang sama. Pakai key v2 sebagai x-key-secret. Lihat Perubahan Dari v1.

Apakah halaman ini membantu?

API v2. Diperbarui 2026-11-12