API Publik Lama

Panduan ini membahas integrasi /api/v1 yang sudah ada yang menukarkan kunci akses API dengan bearer token. Kredensial dan format permintaannya berbeda dari API Publik /v1. Untuk integrasi baru, mulailah dengan Panduan cepat API dan Autentikasi. API /v1 yang baru menggunakan kunci API akun layanan atau token akses OAuth.

Sebelum Anda Memulai

Anda memerlukan:

Akses Living Security yang mengizinkan pengelolaan kunci akses API
Kunci akses API yang dibuat di Pengaturan → Access Keys
Rahasia kunci akses sekali tampil yang ditampilkan saat kredensial dibuat
ID penerbit API yang diberikan oleh Living Security bersama kredensial API Publik Anda
URL dasar regional untuk organisasi yang Anda integrasikan
Runtime sisi server dan pengelola rahasia

Rahasia kunci akses tidak boleh ditempatkan di kode browser, aplikasi seluler, kontrol sumber, variabel lingkungan sisi klien, tiket, atau log bersama.

Dialog Access Keys menampilkan rahasia sekali tampil, tetapi tidak menampilkan ID penerbit API. Jika Living Security belum memberikan ID penerbit bersama kredensial API Publik Anda, mintalah ID tersebut dari Dukungan Living Security. ID penerbit bukan ID kunci akses atau ID organisasi.

Host Regional

Kontrak lama menggunakan host produksi regional /api/v1 berikut:

Wilayah	URL Dasar
AS	`https://api.us-east-1.livingsecurity.ai/api/v1`
UE	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Gunakan wilayah yang ditetapkan untuk organisasi Living Security. Jangan berpindah wilayah untuk mengatasi kesalahan otorisasi atau ketersediaan.

Sumber Daya Lama

Sumber Daya	Operasi yang didukung
Orang	Mencari orang dalam organisasi dan mengambil keanggotaan seseorang
Kunci akses API	Membuat, mencantumkan, merotasi, dan mencabut kunci akses API

Gunakan Developers → Public API Reference untuk daftar lengkap operasi, parameter, permintaan, respons, dan skema. Jika suatu operasi tidak ada di sana, operasi tersebut saat ini bukan bagian dari API Publik.

Autentikasi

Akses API Publik memiliki dua tahap:

Tukarkan rahasia kunci akses dan ID penerbit API dengan bearer token berumur pendek dan ID organisasi.
Kirim bearer token dan ID organisasi pada setiap permintaan API.

Header permintaan yang diperlukan adalah:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

Header organisasi harus berupa organisasi yang dikembalikan oleh pertukaran kunci akses. Suatu kunci tidak memberikan otorisasi untuk mengakses ID organisasi sembarang.

SDK TypeScript

Instal versi mayor terbaru:

npm install @livingsecurity/sdk@^1

Kemudian tukarkan kunci dan konfigurasikan SDK:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

Gunakan URL dasar UE untuk organisasi UE. Pertukaran melalui SDK dimaksudkan untuk runtime Node.js sisi server.

Permintaan REST Langsung

Jika Anda melakukan pertukaran di luar SDK, kirim bearer token dan ID organisasinya pada setiap permintaan:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

Bearer token berumur pendek. Tukarkan kembali kunci akses saat memperoleh token baru, alih-alih menyimpan bearer token sebagai kredensial permanen.

Siklus Hidup Kunci Akses

Beri nama kunci sesuai integrasi atau otomatisasi pemiliknya.
Pilih cakupan dengan hak istimewa paling rendah yang ditawarkan oleh formulir kunci akses.
Simpan rahasia sekali tampil segera; rahasia tersebut tidak dapat diambil kembali setelah pembuatan atau rotasi.
Rotasi kunci melalui Pengaturan → Access Keys dan terapkan penggantinya sebelum mencabut kredensial lama.
Cabut kunci yang tidak lagi digunakan atau yang rahasianya mungkin telah terekspos.
Gunakan kunci akun layanan untuk integrasi non-manusia jika jenis kunci tersebut tersedia bagi organisasi Anda.

Paginasi

Pencarian orang mendukung parameter limit, cursor, offset, dan includeTotal. Sebaiknya gunakan kursor yang dikembalikan oleh respons sebelumnya untuk penelusuran berurutan.

limit secara default bernilai 50 dan menerima 1–100.
cursor melanjutkan dari respons sebelumnya.
offset melewati sejumlah rekaman dan secara default bernilai 0.
includeTotal=true meminta jumlah terfilter yang tepat; hilangkan jika jumlah tidak diperlukan.

Baca objek pagination yang dikembalikan oleh endpoint. Jangan menghitung halaman berikutnya dari jumlah baris yang diterima atau menggabungkan permintaan yang dipaginasi secara terpisah lalu mengurutkan sendiri hasil parsialnya.

Kesalahan

Kesalahan JSON yang didokumentasikan menggunakan bentuk umum berikut:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message dapat berupa string atau larik pesan validasi.

Status	Arti	Respons
`400`	Parameter atau isi permintaan tidak valid	Perbaiki kesalahan validasi yang disebutkan
`401`	Bearer token tidak ada, tidak valid, atau kedaluwarsa	Tukarkan kembali kunci akses dan coba lagi satu kali
`403`	Kredensial tidak memiliki izin atau akses organisasi	Periksa cakupan kunci dan konteks organisasi
`404`	Sumber daya tidak ada di organisasi yang diotorisasi	Verifikasi ID sumber daya dan organisasi
`408`	Permintaan habis waktu	Coba lagi dengan exponential backoff terbatas
`429`	Batas laju tercapai	Tunggu setidaknya selama `Retry-After`, jika ada
`5xx`	Kegagalan layanan sementara	Coba lagi pembacaan yang aman dengan exponential backoff terbatas

Kontrak terkurasi saat ini tidak menerbitkan satu batas laju numerik universal atau menjamin adanya header respons ID permintaan untuk setiap operasi. Catat waktu UTC, metode, jalur, status, dan isi respons yang telah disanitasi saat meminta dukungan. Jangan mencoba ulang operasi pembuatan, rotasi, pencabutan, atau penghapusan secara otomatis kecuali operasi tersebut secara eksplisit mendokumentasikan idempotensi. Periksa status sumber daya saat ini setelah kegagalan jaringan yang tidak jelas.

Kompatibilitas dan Penghentian

V1 berkembang secara aditif secara default. Klien harus mengabaikan kolom respons yang tidak dikenal. Perubahan yang merusak memerlukan jalur migrasi yang terdokumentasi; operasi yang tidak digunakan lagi tetap ada dalam referensi beserta alasan, pengganti jika tersedia, dan tanggal penghentian selama periode migrasi. Kunci SDK pada versi mayor yang kompatibel dan tinjau catatan rilisnya sebelum melakukan peningkatan. Perlakukan Public API Reference yang dihasilkan, bukan klien aplikasi pihak pertama, sebagai sumber kebenaran skema.

API Publik, MCP, dan Aplikasi Web

Permukaan	Digunakan untuk	Model kompatibilitas
API Publik	Sistem pelanggan, mitra, dan otomatisasi eksternal	Sumber daya stabil dan berversi
MCP	Interaksi alat AI yang berizin	Kontrak alat dan keluaran terstruktur yang ringkas
Aplikasi web	Alur kerja manusia dalam produk Living Security	Kontrak milik aplikasi yang dapat berkembang bersama UI

Lihat Integrasi MCP untuk menghubungkan alat AI ke Living Security.

Mendapatkan Bantuan

Hubungi Dukungan Living Security dengan menyertakan:

Organisasi dan wilayah
Nama dan versi SDK, jika digunakan
Stempel waktu UTC, metode, dan jalur
Status HTTP dan isi kesalahan yang telah disanitasi

Jangan pernah menyertakan rahasia kunci akses, bearer token, atau data pelanggan pribadi.

API Publik

Referensi API Publik

Sebelum Anda Memulai

Host Regional

Sumber Daya Lama

Autentikasi

SDK TypeScript

Permintaan REST Langsung

Siklus Hidup Kunci Akses

Paginasi

Kesalahan

Kompatibilitas dan Penghentian

API Publik, MCP, dan Aplikasi Web

Mendapatkan Bantuan

Terkait

Kunci Akses API

Integrasi MCP

API Publik

Referensi API Publik

​Sebelum Anda Memulai

​Host Regional

​Sumber Daya Lama

​Autentikasi

​SDK TypeScript

​Permintaan REST Langsung

​Siklus Hidup Kunci Akses

​Paginasi

​Kesalahan

​Kompatibilitas dan Penghentian

​API Publik, MCP, dan Aplikasi Web

​Mendapatkan Bantuan

​Terkait

Kunci Akses API

Integrasi MCP

Sebelum Anda Memulai

Host Regional

Sumber Daya Lama

Autentikasi

SDK TypeScript

Permintaan REST Langsung

Siklus Hidup Kunci Akses

Paginasi

Kesalahan

Kompatibilitas dan Penghentian

API Publik, MCP, dan Aplikasi Web

Mendapatkan Bantuan

Terkait