# Autentikasi

Setiap permintaan API harus menyertakan kunci API Anda agar <span data-t="appName">Your AI Connector</span> mengetahui identitas Anda dan akun mana yang harus diproses. Anda dapat mengirimkan kunci tersebut dengan empat cara berbeda — semuanya berfungsi pada setiap endpoint yang menerima autentikasi kunci API, jadi pilihlah yang paling sesuai dengan pengaturan Anda.

Akses API adalah fitur berbayar. Jika paket Anda tidak menyertakannya, permintaan akan ditolak dengan `403` meskipun kuncinya sendiri valid — lihat [Gerbang fitur berbayar](#the-paid-feature-gate) di bawah. Untuk membuat kunci, lihat [Akses API](../integrations/api-access.md).

> **Hanya HTTPS.** Semua permintaan harus menggunakan koneksi aman. Permintaan HTTP biasa akan ditolak sebelum autentikasi dijalankan.

---

## Sekilas tentang empat metode

| Metode | Pembawa | Kapan digunakan |
|---|---|---|
| Parameter kueri | `?apiKey=YOUR_API_KEY` | Pengujian cepat dan URL peramban |
| Header | `X-API-Key: YOUR_API_KEY` | Integrasi produksi |
| Header Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrasi produksi |
| Token ID Firebase | `Authorization: Bearer <ID token>` | Hanya sesi aplikasi pihak pertama |

Jika lebih dari satu metode digunakan, parameter kueri akan diutamakan, diikuti oleh header `X-API-Key`, lalu token bearer. Dalam praktiknya, Anda hanya perlu mengirimkan satu saja.

---

## 1. Parameter kueri — `?apiKey=`

Tambahkan kunci Anda di akhir alamat web. Ini adalah bentuk yang paling sederhana dan selalu berfungsi, sehingga ideal untuk pengujian cepat, skrip, dan alat bantu lama lainnya.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()
```

> **Perhatian:** Alamat web akan tersimpan dalam riwayat peramban, log akses server, dan log proksi. Untuk keperluan selain pengujian cepat, gunakan salah satu metode header di bawah ini agar kunci Anda tidak tertulis di disk dalam bentuk teks biasa.

---

## 2. Header `X-API-Key`

Kirim kunci dalam header khusus. Cara ini menjaganya agar tidak muncul di URL dan merupakan pilihan yang direkomendasikan untuk produksi.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

---

## 3. Header `Authorization: Bearer`

Anda juga dapat meneruskan kunci sebagai bearer token standar. Ini berguna jika klien atau framework HTTP Anda sudah memiliki dukungan bawaan untuk header `Authorization`.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()
```

API secara otomatis membedakan kunci API Anda dari token login, jadi metode ini berfungsi persis seperti `X-API-Key`.

---

## 4. Token ID Firebase (khusus pihak pertama)

Jika Anda membangun aplikasi pihak pertama yang membuat pengguna masuk melalui login <span data-t="appName">Your AI Connector</span> sendiri, Anda dapat meneruskan token ID Firebase pengguna yang telah masuk tersebut sebagai bearer token, alih-alih menggunakan kunci API:

```
Authorization: Bearer <Firebase ID token>
```

Token diverifikasi pada setiap permintaan dan dipetakan ke akun yang masuk. **Metode ini hanya untuk sesi aplikasi pihak pertama** — Anda tidak dapat membuat token ini dari integrasi eksternal, dan tidak ada cara untuk mendapatkannya tanpa melalui proses login aplikasi yang normal. Untuk integrasi server-ke-server dan pihak ketiga, gunakan kunci API (metode 1–3).

---

## Kapan menggunakan metode yang mana

- **Pengujian cepat dan skrip sekali pakai** → parameter kueri (`?apiKey=`). Paling cepat diketik, berfungsi di browser.
- **Integrasi produksi dan panggilan server-ke-server** → `X-API-Key` atau `Authorization: Bearer YOUR_API_KEY`. Menjaga kunci agar tidak muncul di URL dan log.
- **Aplikasi pihak pertama dengan pengguna <span data-t="appName">Your AI Connector</span> yang sudah masuk** → `Authorization: Bearer <Firebase ID token>`.

---

## Cakupan kunci

Akun Anda memiliki satu **kunci API utama** — yaitu kunci yang terdapat di bawah **Pengaturan → Integrasi → Kunci API**. Kunci ini memiliki akses penuh ke semua kemampuan akun.

Anda juga dapat membuat **kunci cakupan** tambahan: kunci bernama yang hanya dapat mengakses bagian API yang Anda pilih, misalnya kunci khusus baca yang dibatasi untuk Analitik bagi dasbor pelaporan. Kunci cakupan dikirim persis seperti kunci utama (salah satu dari metode 1–3 di atas), tetapi diperiksa berdasarkan izinnya sendiri pada setiap permintaan:

- **Di luar area yang diizinkan, akses akan ditolak.** Penulisan dengan kunci khusus baca, atau panggilan ke bagian yang tidak diberikan kepada kunci tersebut, akan dikembalikan sebagai `403` — `key_read_only` atau `key_scope_denied` di kolom `error_code`. Pemeriksaan ini sengaja dibuat ketat: apa pun yang tidak secara jelas berada di dalam area yang diizinkan kunci akan ditolak alih-alih dibiarkan lewat, jadi jika Anda melihat salah satu `403` tersebut, berarti kunci tersebut memang tidak mencakup titik akhir (endpoint) itu.
- **Memiliki anggaran batas laju (rate-limit) sendiri.** Kunci cakupan dihitung secara terpisah dari kunci utama Anda, sehingga dasbor yang sibuk menggunakan kunci cakupan tidak akan menghabiskan jatah yang diandalkan oleh integrasi Anda yang lain. Anda memilih anggaran per menit tersebut saat membuat kunci.
- **Tidak dapat mengelola kunci API.** Hanya pemilik akun — yang masuk, atau menggunakan kunci utama — yang dapat mencantumkan, membuat, mengedit, merotasi, atau mencabut kunci. Kunci cakupan tidak akan pernah bisa membuat kunci yang lebih luas untuk dirinya sendiri.

Lihat [Kunci API](api-keys.md) untuk mengetahui cara membuat, mengedit, dan mencabut kunci cakupan.

---

## Gerbang fitur berbayar

Akses API adalah fitur berbayar. Jika paket Anda tidak menyertakannya, permintaan dengan kunci yang sebenarnya valid akan ditolak dengan `403`:

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

If you see this, check your plan or contact [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}
```

---

## Menjaga keamanan kunci Anda

- **Perlakukan kunci seperti kata sandi.** Kunci utama Anda memberikan akses penuh ke akun Anda. Jika Anda perlu memberikan kunci kepada alat atau orang yang hanya memerlukan sebagian akses, buatlah kunci cakupan sebagai gantinya — lihat [Cakupan kunci](#key-scopes).
- **Simpan di sisi server.** Jangan pernah menyematkannya dalam JavaScript peramban, bundel aplikasi seluler, atau kode apa pun yang dapat dibaca oleh pengguna akhir.
- **Simpan di pengelola rahasia** atau konfigurasi sisi server, bukan di kontrol sumber.
- **Rotasi jika bocor.** Buat kunci baru dari dasbor atau panggil `POST https://api.youraiconnector.com/v1/api-keys/rotate` — ini akan segera membatalkan kunci lama. Lihat [Kunci API](api-keys.md).
- **Selalu gunakan HTTPS** agar kunci terenkripsi saat transit.

---

## Langkah berikutnya

- [Memulai](getting-started.md) — permintaan pertama Anda dan panduan sumber daya.
- [Kesalahan & Penomoran Halaman](errors-and-pagination.md) — menangani kegagalan dan melakukan penomoran halaman melalui hasil.
- [Kunci API](api-keys.md) — merotasi, mencabut, dan memeriksa penggunaan kunci Anda.