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

# Autentikasi

> Setiap request membawa API key organisasi di header Authorization.

Kirim API key di header `Authorization` dengan skema `Bearer` pada **setiap** request ke `/v1`:

```bash theme={null}
curl -s "https://api.leviacloud.com/v1/regions" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Jangan menaruh key di URL atau query string.

## Format key

Key berbentuk `sk_` diikuti 64 karakter heksadesimal. Di dashboard, key ditampilkan **sekali** saat dibuat. Setelah itu yang terlihat hanya **prefix**-nya (kolom *Prefix* di daftar API key), yang juga muncul sebagai pelaku di Log Audit: `API key <prefix>/<nama>`.

Levia hanya menyimpan hash key, jadi key yang hilang tidak bisa ditampilkan lagi. Cabut lalu buat key baru.

## Siklus hidup key

Key dikelola di dashboard: **Pengaturan Organisasi → API Key**.

| Aksi | Keterangan |
| - | - |
| Buat | Pilih nama, deskripsi (opsional), akses per layanan ([scope](https://docs.leviacloud.com/konsep/scope.md)), dan masa berlaku. |
| Masa berlaku | 30, 60, 90 (bawaan), atau 365 hari, tanggal sendiri, atau *Selamanya*. Tanggal yang sudah lewat ditolak. Key kedaluwarsa ditolak `401`. |
| Ubah | Ganti nama, deskripsi, scope, atau masa berlaku. Nilai key tidak berubah. |
| Rotate | Membuat nilai key baru dengan scope yang sama. Key lama berhenti berlaku paling lambat sekitar 10 detik kemudian. |
| Revoke (cabut) | Key langsung ditolak `401` untuk semua operasi pada resource. Endpoint katalog bisa masih menerima key itu sampai sekitar 10 detik karena cache verifikasi. |

## Key bertindak sebagai pembuatnya

API key milik organisasi, tetapi setiap request dijalankan **atas nama user yang membuat key**:

* Role user itu di organisasi tetap berlaku. Misalnya, role tanpa akses tagihan tidak bisa membaca billing walau key punya `billing:read`.
* SSH key yang terlihat dan bisa dipakai adalah milik user itu.
* Bila user itu dikeluarkan dari organisasi, key-nya tidak bisa dipakai lagi (`403`).
* Resource organisasi lain tidak pernah terlihat: hasilnya `404` atau daftar kosong.

## Jaga key tetap aman

> [!WARNING]
>
> API key dengan scope `write` bisa membuat resource berbayar dan menghapus data. Perlakukan seperti password.

* **Jangan pernah membagikan key**, termasuk di tiket dukungan, chat, atau screenshot. Untuk dukungan, kirim `X-Request-Id` (lihat [Format respons & error](https://docs.leviacloud.com/konsep/respons-error.md#pelacakan-request)).
* Jangan commit key ke repository atau menaruhnya di kode frontend. Simpan di secret manager atau variabel lingkungan.
* Buat satu key per integrasi dengan scope seminimal mungkin dan masa berlaku terbatas, supaya mudah dicabut tanpa mengganggu integrasi lain.
* Cabut key yang bocor atau tidak dipakai lagi.

## Error autentikasi

| HTTP | `code` | Arti |
| - | - | - |
| 401 | `missing_api_key` | Header `Authorization: Bearer …` tidak dikirim. |
| 401 | `invalid_api_key` | Key tidak dikenal, sudah dicabut, atau kedaluwarsa. Alasannya sengaja tidak dibedakan. |
| 403 | `insufficient_scope` | Key valid tetapi tidak punya scope endpoint ini. Lihat [Scope](https://docs.leviacloud.com/konsep/scope.md). |
| 403 | `forbidden` | Role pemilik key tidak boleh mengakses area ini, atau pemilik key bukan member organisasi lagi. |
| 429 | `too_many_auth_failures` | Lebih dari 30 autentikasi gagal per menit dari satu alamat IP. Tunggu sesuai `Retry-After` (60 detik). |


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