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

# Kredensial klien OAuth

> Siapkan klien akun layanan dengan cakupan terbatas, tangani secret sekali pakai, dan lakukan pemulihan dengan aman dari permintaan yang hasilnya tidak pasti.

Gunakan kredensial klien OAuth saat integrasi backend Anda membutuhkan token
akses berumur pendek atau saat kebijakan keamanan Anda mewajibkannya. Setiap klien milik
satu akun layanan dan satu organisasi. **OAuth bersifat opsional:** kunci
API dengan cakupan terbatas sudah memadai untuk integrasi server privat yang dapat menyimpan
dan merotasi kunci dengan aman. Lihat [Autentikasi](/id/developers/v1/authentication) untuk memilih
di antara kedua metode tersebut dan memahami peran akun layanan.

<Note>
  Akses OAuth harus diaktifkan untuk organisasi Anda. Proses penyiapan Anda menyediakan
  endpoint token regional, issuer, audience, dan metode autentikasi klien.
  Jika Anda memerlukan pengaturan ini atau tidak dapat mengakses pengelolaan klien, hubungi
  Dukungan Living Security.
</Note>

Grant kredensial klien mewakili akun layanan Anda. Grant ini tidak memasukkan seseorang ke sistem
atau meminta pelanggan untuk mengotorisasi suatu aplikasi. Otorisasi terdelegasi melalui
browser merupakan kemampuan OAuth yang terpisah dan tidak disediakan oleh operasi-operasi ini.

## Sebelum Anda memulai

* Buat [akun layanan](/id/developers/developer-hub/service-accounts) dengan hanya
  izin yang dibutuhkan oleh integrasi.
* Gunakan kredensial manajemen dengan `service_account:manage` dan setiap izin
  yang ingin Anda berikan kepada klien baru. Akun target juga harus memiliki izin tersebut.
  Klien tidak dapat memperluas kewenangan akun mana pun.
* Pilih [wilayah](/id/developers/v1/regions) organisasi. Kredensial API dan
  token akses OAuth harus digunakan pada host API regional yang sesuai.
* Simpan secret klien dan token di penyimpanan secret sisi server Anda. Jangan pernah menaruhnya
  dalam kode browser, aplikasi seluler, kontrol sumber, atau log permintaan.

## Membuat klien

`POST /v1/oauth_clients` memerlukan `service_account_id`, daftar tidak kosong berisi
`scopes` eksplisit, dan `Idempotency-Key`. Wildcard tidak diterima. Satu klien mendukung
hingga 100 cakupan, dengan total panjang maksimal 4.096 karakter. Setiap akun
layanan dapat memiliki paling banyak 20 klien atau operasi pembuatan/pembersihan yang belum selesai.
Pencabutan langsung menolak akses API. Klien atau pembuatan yang tidak pasti di sisi penyedia
tetap dihitung terhadap batas hingga pembersihan jarak jauh dikonfirmasi.
Reservasi yang ditinggalkan atau pembuatan yang terbukti gagal sebelum pekerjaan penyedia
dimulai dapat melepaskan slotnya dengan aman. Kunci percobaan ulangnya tetap milik
upaya awal; pulihkan tanda terima tersebut sebelum memutuskan untuk membuat pengganti.

Pilih satu kunci percobaan ulang untuk upaya pembuatan ini dan simpan **sebelum** mengirim
permintaan. Gunakan 1–255 karakter ASCII yang terlihat, tanpa spasi. Gunakan kembali kunci tersebut dengan
akun, cakupan, prinsipal manajemen, wilayah, dan versi API yang sama setelah respons hilang. Merotasi kredensial manajemen pada akun layanan yang sama
tidak membuat identitas percobaan ulang yang baru.

Instal paket `requests` Python. Muat nilai lingkungan berikut melalui
pengelolaan secret dan konfigurasi Anda yang biasa:

| Variabel | Nilai |
| - | - |
| `LIVING_SECURITY_API_KEY` | Kunci API manajemen |
| `LIVING_SECURITY_REGION` | `us` atau `eu` |
| `LIVING_SECURITY_SERVICE_ACCOUNT_ID` | ID akun layanan target |
| `LIVING_SECURITY_OAUTH_CREATE_KEY` | Kunci percobaan ulang yang sebelumnya telah disimpan |

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

HOSTS = {
    "us": "https://api.us-east-1.livingsecurity.ai/v1",
    "eu": "https://api.eu-west-1.livingsecurity.ai/v1",
}
base = HOSTS[os.environ["LIVING_SECURITY_REGION"]]
response = requests.post(
    f"{base}/oauth_clients",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={
        "Living-Security-Version": "2026-07-01",
        "Idempotency-Key": os.environ["LIVING_SECURITY_OAUTH_CREATE_KEY"],
    },
    json={
        "service_account_id": os.environ["LIVING_SECURITY_SERVICE_ACCOUNT_ID"],
        "scopes": ["organization:read"],
    },
    timeout=(5, 30),
    allow_redirects=False,
)
try:
    if response.status_code != 201:
        raise RuntimeError(
            f"Client creation needs review: HTTP {response.status_code}; "
            f"request_id={response.headers.get('Request-Id', 'unknown')}"
        )
    client = response.json()
    if client.get("object") != "oauth_client" or not client.get("id"):
        raise RuntimeError("Unexpected client receipt; preserve the retry key")
    if client.get("status") != "active" or not client.get("client_secret"):
        raise RuntimeError(
            f"Client {client['id']} needs recovery; no usable secret was returned"
        )
    # Persist client['id'], client['client_id'], and client['client_secret']
    # directly in your secret manager before using the client. Do not print them.
finally:
    response.close()
```

Contoh ini membuat satu permintaan dan menyimpan hasilnya di memori. Tambahkan operasi tulis
pengelola secret Anda pada titik yang ditandai sebelum menjalankannya di produksi.
Contoh ini sengaja mengharuskan adanya keputusan setelah hasil yang tidak pasti, alih-alih diam-diam
membuat klien lain. Pengecualian jaringan juga memerlukan langkah pemulihan di bawah ini.

Respons pembuatan dan tanda terima menggunakan `201` dan berisi resource `oauth_client`
dengan `id`, `service_account_id`, `client_id`, `scopes`, `status`, `created_at`, dan
`client_secret`. Respons ditandai `Cache-Control: no-store`.

* **`id`** mengidentifikasi resource platform. Simpan untuk pengambilan dan pencabutan.
* **`client_id`** mengidentifikasi klien selama pertukaran token. Ini bukan
  ID resource platform. Nilainya dapat berupa `null` saat pembuatan masih tertunda.
* **`client_secret`** hanya dikembalikan kepada permintaan yang menyelesaikan pembuatan.
  Setiap permintaan pembuatan berulang mengembalikan `null`, termasuk percobaan ulang setelah
  respons keberhasilan hilang. Pengambilan tidak pernah mengembalikan secret.

## Memulihkan respons yang hilang atau terputus

Ulangi permintaan pembuatan yang sama dengan kunci percobaan ulang yang tersimpan untuk memulihkan
tanda terima resource. Tanda terima mencerminkan status terkini, sehingga klien yang telah dicabut tetap berstatus dicabut.
Operasi ini tidak menggunakan kontrak pemutaran ulang respons tersimpan selama 24 jam yang umum
dan tidak mengembalikan header `Idempotent-Replayed`.

| Hasil | Tindakan berikutnya |
| - | - |
| `active`, secret ada | Simpan secret dengan aman dan lanjutkan proses orientasi. |
| `active`, secret tidak ada | Secret tidak dapat dipulihkan. Cabut klien ini, konfirmasikan pencabutan, lalu buat pengganti menggunakan kunci percobaan ulang yang baru. |
| `pending` | Pembuatan belum terkonfirmasi. Pertahankan kunci percobaan ulang yang sama. Ambil resource untuk memeriksa statusnya; jangan membuat duplikat untuk menghindari ketidakpastian. |
| `revoked`, `disabled`, atau `expired` | Jangan gunakan klien ini. Konfirmasikan konfigurasi akun yang dimaksud sebelum menyiapkan pengganti. |
| `409 idempotency_key_reuse` | Permintaan berubah di bawah kunci yang sudah ada. Pulihkan operasi awal sebelum memutuskan apakah pembuatan terpisah diperlukan. |
| `409 invalid_request` | Periksa status dan hak akses akun target. Jika batas klien telah tercapai, selesaikan pembersihan sebelum mencoba lagi; mengganti kunci percobaan ulang tidak membebaskan kapasitas. |
| `429` | Patuhi `Retry-After`; pertahankan kunci dan permintaan yang sama. |
| `500`, `503`, atau batas waktu jaringan habis | Hasilnya mungkin tidak diketahui. Pertahankan kunci dan input; pulihkan tanda terima sebelum membuat klien lain. |
| `401` atau `403` | Selesaikan masalah akses kredensial, izin, atau hak penggunaan sebelum mencoba lagi. |
| `404` | Konfirmasikan pengaktifan OAuth, host regional, dan kepemilikan resource. |

Lihat [kesalahan](/id/developers/v1/errors/overview) untuk ID permintaan dan detail pemulihan.
Jangan pernah mengirim secret klien atau token akses bersama permintaan dukungan.

## Memeriksa dan mencabut

Gunakan kredensial manajemen Anda dan `id` resource platform:

| Operasi | Permintaan | Keberhasilan |
| - | - | - |
| Memeriksa status terkini | `GET /v1/oauth_clients/{id}` | `200`, resource klien tanpa secret |
| Mencabut akses | `DELETE /v1/oauth_clients/{id}` | `200`, resource klien yang dicabut tanpa secret |

Pencabutan memblokir permintaan API berikutnya dari klien, termasuk permintaan dengan
token yang sudah diterbitkan. Pencabutan tidak membatalkan pekerjaan yang sudah diterima oleh API.
Pembersihan kredensial jarak jauh dapat selesai kemudian. Mengulangi pencabutan aman dilakukan dan
tidak memerlukan kunci percobaan ulang. Lanjutkan menggunakan kredensial manajemen jika klien
yang dicabut itu sendiri merupakan pemanggil API.

## Rotasi tanpa kehilangan akses

Buat klien kedua dengan batas atas cakupan yang diperlukan. Simpan secret-nya, peroleh
token menggunakan endpoint token regional Anda, dan verifikasi bahwa integrasi berfungsi
dengannya. Alihkan integrasi ke klien pengganti, lalu cabut resource yang lama.
Pertahankan kredensial manajemen independen agar Anda dapat pulih dari peluncuran yang gagal.

Token akses tidak dapat memberikan lebih dari cakupan klien dan izin akun layanan
saat ini. Penghapusan izin akun atau pencabutan klien lebih diutamakan daripada
sisa masa berlaku token. Jangan menganggap token yang di-cache sebagai bukti bahwa
otorisasi masih valid. Peroleh token akses baru sebelum kedaluwarsa dengan
mengautentikasi klien kembali; grant ini tidak menggunakan refresh token.


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