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

# Scope

> Akses per layanan yang dimiliki setiap API key: baca atau baca & tulis.

Setiap API key punya scope per keluarga layanan. Di dashboard, scope dipilih per layanan sebagai **Tidak ada**, **Baca**, atau **Baca & tulis**:

* **Baca** memberi `<layanan>:read`: endpoint `GET`.
* **Baca & tulis** memberi `<layanan>:read` dan `<layanan>:write`. Scope `write` selalu juga memberi `read`.
* `catalog:read` dimiliki **setiap** key.

Scope diperiksa sebelum request dijalankan. Key tanpa scope yang dibutuhkan mendapat `403 insufficient_scope`, dengan nama scope di `message` dan di `details.required_scope`:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "API key ini tidak punya scope compute:write.",
    "details": { "required_scope": "compute:write" }
  }
}
```

## Daftar scope

| Scope | `read` membuka | `write` membuka |
| - | - | - |
| `catalog:read` | Region, zona, paket VM, image. Selalu ada. | – |
| `compute:read` / `compute:write` | Daftar dan detail VM | Buat, hapus, start, stop, restart, resize VM |
| `storage:read` / `storage:write` | Volume, snapshot volume, snapshot VM | Buat, hapus, resize, attach, detach volume; buat, hapus, restore snapshot; snapshot VM |
| `network:read` / `network:write` | VPC, subnet, security group, floating IP | Buat dan hapus VPC, subnet, security group; ganti rule; pesan, pasang, lepas, release floating IP |
| `ssh_keys:read` / `ssh_keys:write` | SSH key milik pemilik API key | Tambah dan hapus SSH key |
| `billing:read` | Saldo, pemakaian, pemakaian bulanan | – (hanya baca) |
| `database:read` / `database:write` | Engine, paket, database, user, database logis, backup, PITR, read replica | Semua perubahan database, **plus semua endpoint yang mengembalikan password** |
| `load_balancer:read` / `load_balancer:write` | Harga, load balancer, listener, target dan kesehatannya | Buat, ubah, hapus load balancer; tambah, ubah, hapus listener; tambah dan lepas target |

Beberapa catatan:

* `POST /vms` dengan `security_group_ids` juga butuh `network:read`.
* `load_balancer:*` terpisah dari `network:*`: `network:write` tidak membuka load balancer.
* Role pemilik key tetap berlaku di atas scope. Misalnya, `billing:read` tidak berguna bila role pemilik key tidak punya akses tagihan. Lihat [Autentikasi](https://docs.leviacloud.com/konsep/autentikasi.md#key-bertindak-sebagai-pembuatnya).

## Endpoint yang mengembalikan password

Jawaban endpoint berikut memuat password, jadi semuanya butuh `database:write`, termasuk yang memakai method `GET`:

| Endpoint | Isi |
| - | - |
| `GET /databases/{id}/connection` | Info koneksi beserta password admin |
| `POST /databases/{id}/reset-password` | Password admin baru |
| `POST /databases/{id}/users` | Password user baru |
| `POST /databases/{id}/users/{username}/rotate-password` | Password baru user |

Jawaban ini dikirim dengan `Cache-Control: no-store`. Password tidak pernah ada di daftar atau detail database.

## Key tanpa scope (bawaan hanya baca)

Key yang dibuat sebelum Open API, atau yang scope-nya kosong, **hanya bisa membaca**:

| Didapat | Tidak didapat |
| - | - |
| `catalog:read`, `compute:read`, `storage:read`, `network:read`, `ssh_keys:read`, `billing:read` | Semua `write`, serta `database:*` dan `load_balancer:*` |

Dashboard menandai key seperti ini dengan **Hanya baca (bawaan)**. Untuk memberi akses tulis, database, atau load balancer, pemilik key mengubah key itu di dashboard. Key baru selalu dibuat dengan scope eksplisit; Database dan Load Balancer bawaannya *Tidak ada*.

## Pilih scope seminimal mungkin

| Integrasi | Scope yang cukup |
| - | - |
| Dashboard internal / monitoring biaya | `billing:read` |
| Inventaris resource (hanya baca) | `compute:read`, `storage:read`, `network:read` |
| CI yang membuat dan menghapus VM uji | `compute:write`, `ssh_keys:read` |
| Backup terjadwal volume | `storage:write` |
| Aplikasi yang membaca kredensial database | `database:write` (karena info koneksi memuat password) |


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