> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Publik Lama

> Pertahankan integrasi /api/v1 yang sudah ada yang menukarkan kunci akses API dengan bearer token.

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](/id/developers/v1/quickstart) dan [Autentikasi](/id/developers/v1/authentication). 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.

<Note>
  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](mailto:support@livingsecurity.com). ID penerbit bukan ID kunci akses atau ID organisasi.
</Note>

## 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:

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

Header permintaan yang diperlukan adalah:

```http theme={null}
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:

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

Kemudian tukarkan kunci dan konfigurasikan SDK:

```typescript theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/id/integrations/mcp) untuk menghubungkan alat AI ke Living Security.

## Mendapatkan Bantuan

Hubungi [Dukungan Living Security](mailto:support@livingsecurity.com) 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.

## Terkait

<CardGroup cols={2}>
  <Card title="Kunci Akses API" icon="key" href="/id/integrations/api-keys">
    Buat, rotasi, dan cabut kredensial API.
  </Card>

  <Card title="Integrasi MCP" icon="robot" href="/id/integrations/mcp">
    Hubungkan alat AI yang didukung melalui Model Context Protocol.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.