Autentikasi #

Setiap permintaan API harus menyertakan kunci API Anda agar Your AI Connector 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 di bawah. Untuk membuat kunci, lihat Akses API.

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

Sekilas tentang empat metode #

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

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

JavaScript

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

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

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

JavaScript

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

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

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

JavaScript

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

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 Your AI Connector 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 Your AI Connector 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 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:

{
  "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 hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "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.
• 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.
• Selalu gunakan HTTPS agar kunci terenkripsi saat transit.

Langkah berikutnya #

• Memulai — permintaan pertama Anda dan panduan sumber daya.
• Kesalahan & Penomoran Halaman — menangani kegagalan dan melakukan penomoran halaman melalui hasil.
• Kunci API — merotasi, mencabut, dan memeriksa penggunaan kunci Anda.