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

# Panduan Cepat API

> Buat akun layanan dan kunci API di Developer Hub, lakukan autentikasi dengan Basic auth, lalu kirim permintaan pertama Anda ke Living Security Public API.

Buat akun layanan dan kunci API di Developer Hub, lalu kirim permintaan
pertama Anda. Panduan cepat ini menggunakan autentikasi kunci API; Anda tidak memerlukan
klien OAuth. Lihat [Autentikasi](/id/developers/v1/authentication) jika
integrasi Anda memerlukan token akses OAuth berumur pendek.

## Prasyarat

* Akses admin ke Dasbor Living Security.
* Developer Hub yang terlihat di bawah **Pengaturan → Integrasi & Developers →
  Developer Hub**.

## Membuat kredensial

<Steps>
  <Step title="Buat akun layanan">
    Di Developer Hub, buka tab **Service accounts** lalu buat sebuah
    akun. Berikan nama yang deskriptif (misalnya `reporting-pipeline`) dan
    berikan izin yang dapat digunakan oleh kunci-kuncinya — untuk panduan ini, `organization:read`
    sudah cukup.

    Izin akun tersebut merupakan batas maksimum bagi setiap kunci yang dibuat di bawahnya:
    sebuah kunci tidak akan pernah dapat melakukan lebih dari yang diizinkan oleh akun layanannya.
  </Step>

  <Step title="Buat kunci API">
    Buka halaman detail akun layanan lalu buat sebuah kunci. Pilih
    izin yang dibutuhkan kunci ini secara spesifik (subset dari izin akun) serta
    masa berlaku — 30, 90, atau 365 hari, atau periode kustom. Masa berlaku
    wajib ditentukan.

    Rahasia kunci diawali dengan `lsk_live_` dan ditampilkan **sekali saja**. Salin
    ke pengelola rahasia (secret manager) segera; rahasia tersebut tidak dapat diambil kembali nanti.

    <Warning>
      Jangan pernah meng-commit rahasia kunci API ke version control atau menyematkannya dalam kode
      sisi klien. Siapa pun yang memegang rahasia tersebut dapat bertindak dengan izin kunci tersebut.
    </Warning>
  </Step>

  <Step title="Pilih region Anda">
    Panggil host `/v1` regional yang sesuai dengan residensi data
    organisasi. Kunci hanya diautentikasi pada host tersebut.

    | Region | URL Dasar |
    | - | - |
    | US | `https://api.us-east-1.livingsecurity.ai/v1` |
    | EU | `https://api.eu-west-1.livingsecurity.ai/v1` |

    Lihat [Region](/id/developers/v1/regions) jika Anda tidak yakin host mana yang
    harus digunakan. Kunci yang valid yang dikirim ke region lain akan gagal dengan `unauthorized`. Gunakan
    dropdown region pada contoh di bawah untuk mengganti host.
  </Step>

  <Step title="Kirim permintaan pertama Anda">
    Muat `LIVING_SECURITY_API_KEY` dari pengelola rahasia Anda ke dalam environment
    proses yang mengirim permintaan. Contoh di bawah membacanya tanpa menyematkan
    rahasia dalam kode sumber. Untuk Python, instal `requests` terlebih dahulu.

    Panggil API dengan rahasia pada kolom kata sandi atau nama pengguna HTTP Basic auth
    — keduanya dapat digunakan, sehingga klien yang mengharuskan kedua kolom terisi (seperti
    konektor Web Power BI) dapat memasukkan placeholder seperti `apikey` pada kolom
    lainnya.

    <CodeGroup>
      ```bash cURL theme={null}
      curl --fail-with-body --connect-timeout 5 --max-time 30 \
        https://api.eu-west-1.livingsecurity.ai/v1/organization \
        -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
        -H "Living-Security-Version: 2026-07-01"
      ```

      ```bash cURL (key as username) theme={null}
      curl --fail-with-body --connect-timeout 5 --max-time 30 \
        https://api.eu-west-1.livingsecurity.ai/v1/organization \
        -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
        -H "Living-Security-Version: 2026-07-01"
      ```

      ```python Python theme={null}
      import os
      import requests

      BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

      response = requests.get(
          f"{BASE}/organization",
          auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
          headers={"Living-Security-Version": "2026-07-01"},
          timeout=(5, 30),
          allow_redirects=False,
      )
      response.raise_for_status()
      if response.status_code != 200:
          raise RuntimeError("Unexpected response; check your regional API URL")
      print(response.json())
      ```
    </CodeGroup>

    Respons yang berhasil akan mengembalikan organisasi Anda:

    ```json Response theme={null}
    {
      "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
      "object": "organization",
      "name": "Example Corp",
      "region": "eu",
      "plan": "enterprise",
      "subscription_status": "active",
      "created_at": "2024-03-12T18:04:11.000Z"
    }
    ```

    <Check>
      Jika Anda menerima respons ini, kredensial Anda berfungsi. Permintaan tersebut juga muncul di
      tab **Request logs** Developer Hub dalam beberapa saat.
    </Check>
  </Step>
</Steps>

<Tip>
  Autentikasi Bearer dengan rahasia yang sama (`Authorization: Bearer
    lsk_live_...`) juga dapat digunakan. Basic auth tersedia agar alat yang hanya mendukung
  nama pengguna/kata sandi — seperti konektor Web Power BI — dapat terhubung.
</Tip>

## Cara kerja autentikasi

* **Kredensial menentukan organisasi.** Permintaan `/v1` tidak membawa
  pemilih tenant: tanpa segmen jalur organisasi dan tanpa header organisasi.
  Pengiriman header `x-organization-id` akan ditolak dengan `invalid_request`.
  Host tetap harus sesuai dengan region organisasi tersebut. Lihat
  [Region](/id/developers/v1/regions).
* **Izin diperiksa per operasi.** Setiap operasi `/v1` memerlukan
  izin bernama (misalnya, `GET /v1/organization` memerlukan
  `organization:read`). Kunci yang tidak memiliki izin tersebut akan menerima `403` dengan kode
  `insufficient_permission`.
* **Kunci kedaluwarsa dan dapat dirotasi tanpa downtime.** Lihat
  [Kunci API](/id/developers/developer-hub/api-keys) untuk rotasi dengan periode
  tumpang tindih.

## Membaca respons error

Setiap error `/v1` berformat `application/problem+json`
([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)) dengan kode mesin
yang stabil. Misalnya, permintaan dengan kredensial yang hilang atau tidak dikenal mengembalikan:

```json 401 Unauthorized theme={null}
{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}
```

Lakukan percabangan berdasarkan `code`, jangan pernah berdasarkan `detail`. Ikuti `doc_url` untuk langkah
penyelesaian, dan sertakan `request_id` saat menghubungi dukungan — nilai ini cocok dengan
header respons `Request-Id` dan log permintaan Developer Hub. Kumpulan kode lengkap
ada di [referensi error](/id/developers/v1/errors/overview).

## Versi kontrak

Setiap respons menyertakan versi kontrak yang melayaninya pada
header `Living-Security-Version`, bersama header `Request-Id` untuk
korelasi.

Anda dapat menyematkan permintaan ke versi kontrak yang dipublikasikan berdasarkan tanggal:

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body --connect-timeout 5 --max-time 30 \
    https://api.eu-west-1.livingsecurity.ai/v1/organization \
    -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
    -H "Living-Security-Version: 2026-07-01"
  ```
</CodeGroup>

Versi ditentukan dengan urutan berikut: header permintaan jika ada, jika tidak
default yang disematkan pada akun layanan, jika tidak versi terbaru yang dipublikasikan.
Meminta versi yang tidak dipublikasikan (atau sudah melewati tanggal sunset-nya)
mengembalikan `400` dengan kode `unsupported_version`. Versi yang dipublikasikan beserta
perubahannya tercantum di [changelog API](/id/developers/v1/changelog).

## Pemecahan masalah permintaan pertama Anda

| Hasil | Tindakan berikutnya |
| - | - |
| `401 unauthorized` | Periksa rahasia, masa berlakunya, dan region organisasi. Jangan mencoba host lain dengan kredensial aktif. |
| `403 insufficient_permission` | Berikan `organization:read` ke akun layanan maupun kuncinya. |
| `400 unsupported_version` | Pilih versi yang dipublikasikan dari [changelog](/id/developers/v1/changelog). |
| `429 rate_limited` | Tunggu `Retry-After`; ikuti [contoh percobaan ulang terbatas](/id/developers/v1/rate-limits). |
| Network timeout | Periksa konektivitas dan coba ulang pembacaan ini dalam batas anggaran percobaan ulang aplikasi Anda. |

Untuk error lainnya, ikuti `doc_url` pada respons. Simpan `Request-Id` untuk
dukungan; jangan pernah menyertakan header Authorization atau kunci API Anda dalam tiket.

## Langkah berikutnya

<CardGroup cols={2}>
  <Card title="Region" href="/id/developers/v1/regions">
    Pilih host `/v1` US atau EU untuk organisasi.
  </Card>

  <Card title="Paginasi" href="/id/developers/v1/pagination">
    Telusuri daftar dengan `page_token` dan envelope daftar.
  </Card>

  <Card title="Batas laju" href="/id/developers/v1/rate-limits">
    Pahami anggaran permintaan dan tangani respons `429`.
  </Card>

  <Card title="Referensi error" href="/id/developers/v1/errors/overview">
    Setiap kode error, status HTTP-nya, dan cara mengatasinya.
  </Card>

  <Card title="Developer Hub" href="/id/developers/developer-hub/overview">
    Kelola akun layanan, kunci API, dan log permintaan.
  </Card>
</CardGroup>


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