API Keys API

Endpoint ini memungkinkan Anda mengelola kunci API akun Anda dari kode. Semuanya hanya beroperasi pada kunci milik akun pemanggil.

Ada dua jenis kunci, dan keduanya berada di jalur yang terpisah:

Kunci utama Anda — satu-satunya kunci akses penuh di bawah Pengaturan → Integrasi → Kunci API. Cari pratinjau tersamar, periksa penggunaan batas kecepatan Anda, rotasi, atau cabut kunci tersebut. Ini adalah endpoint /api-keys/current, /api-keys/rotate, dan /api-keys/usage di bawah ini.
Kunci cakupan (Scoped keys) — kunci tambahan bernama yang Anda buat untuk tugas tertentu, masing-masing dibatasi pada bagian API yang Anda pilih. Ini adalah endpoint /api-keys dan /api-keys/{id} di bawah Kunci cakupan. Tidak ada perubahan pada kunci utama Anda saat Anda membuat kunci ini; integrasi yang ada tetap tidak terpengaruh.

Semua jalur di bawah ini bersifat relatif terhadap URL dasar API:

https://api.youraiconnector.com/v1

Setiap permintaan harus diautentikasi. Lihat Autentikasi untuk empat metode yang diterima. Contoh di sini menggunakan header X-API-Key (dan satu bentuk parameter kueri untuk cURL).

Baca ini terlebih dahulu. Merotasi atau mencabut kunci Anda akan berlaku seketika. Saat panggilan berhasil, kunci lama akan berhenti berfungsi — setiap integrasi yang masih menggunakannya akan mulai menerima kesalahan 401. Rencanakan hal ini: lakukan rotasi selama jendela pemeliharaan dan segera perbarui semua integrasi Anda.

Mendapatkan metadata kunci saat ini

Mengembalikan kunci aktif Anda: kunci lengkap di api_key jika salinan yang dapat diambil tersedia, pratinjau yang disamarkan (4 karakter pertama dan 4 karakter terakhir), dan, jika tersedia, tanggal pembuatannya. api_key adalah null untuk kunci yang dibuat sebelum salinan yang dapat diambil disimpan — lakukan rotasi sekali dan kunci baru tersebut dapat ditampilkan kembali di kemudian hari.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Respons

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Jika akun tidak memiliki kunci API, responsnya adalah 404 dengan { "success": false, "error": "No API key found for this account" }.

Mendapatkan penggunaan batas laju (rate-limit)

Mengembalikan penggunaan batas laju Anda untuk jendela saat ini: batas permintaan per jendela, berapa banyak permintaan yang telah dihitung sejauh ini, berapa banyak yang tersisa, dan kapan jendela tersebut diatur ulang. Gunakan ini untuk membangun pembatasan (throttling) sisi klien agar integrasi Anda melambat sebelum mencapai respons 429.

GET /api-keys/usage

cURL

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

JavaScript

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

Python

import requests

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

Respons

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Jika belum ada permintaan yang tercatat di jendela saat ini, penggunaan akan dilaporkan sebagai nol dan respons menyertakan kolom note yang menjelaskan alasannya.

Merotasi kunci

Menghasilkan kunci API baru dan membatalkan kunci sebelumnya dalam satu langkah yang sama. Gunakan ini jika Anda mencurigai kunci Anda telah bocor, atau sebagai bagian dari kebijakan rotasi kredensial rutin.

POST /api-keys/rotate

Kunci baru hanya ditampilkan sekali. Kunci ini dikembalikan dalam respons ini dan tidak dapat diambil secara penuh setelahnya — simpan dengan aman segera setelah Anda menerimanya. Kunci sebelumnya akan berhenti berfungsi seketika setelah panggilan ini berhasil, jadi perbarui setiap integrasi yang menggunakannya.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Respons

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Cabut kunci

Menghapus kunci API akun Anda secara permanen. Pencabutan bersifat langsung: setiap permintaan berikutnya yang menggunakan kunci yang dicabut — termasuk integrasi seperti Make, Zapier, atau skrip kustom — akan ditolak dengan 401. Untuk memulihkan akses API setelahnya, buat kunci baru dari pengaturan akun Anda saat masuk ke aplikasi.

DELETE /api-keys/current

Tidak ada opsi batalkan. Berbeda dengan rotasi, pencabutan tidak memberikan kunci pengganti. Hanya lakukan pencabutan jika Anda bermaksud menghentikan akses API (misalnya, kunci yang bocor dan tidak dapat segera diganti).

cURL

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

JavaScript

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

Python

import requests

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

Respons

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Jika akun tidak memiliki kunci untuk dicabut, responsnya adalah 404.

Kunci cakupan

Kunci cakupan adalah kunci API tambahan yang Anda buat untuk satu tugas tertentu, yang hanya membawa akses yang dibutuhkan tugas tersebut. Contoh klasik: Anda ingin mengarahkan dasbor klien, alat pelaporan, atau skrip internal ke akun Anda tanpa memberikan kunci yang juga dapat mengirim pesan, mengubah agen AI Anda, atau membeli nomor telepon.

Pembatasan tersebut menyertai kunci itu sendiri, sehingga siapa pun yang memegangnya hanya dapat melakukan apa yang Anda izinkan saat Anda membuatnya.

Apa yang dapat Anda batasi

Bidang	Apa artinya
`read_only`	`true` (default) berarti hanya permintaan baca yang diizinkan. Setiap pembuatan, pembaruan, atau penghapusan akan ditolak.
`tags`	Daftar bagian API yang boleh digunakan kunci, ditulis dengan nama bagian yang sama seperti yang Anda lihat di dokumen ini dan di API explorer — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments`, dan seterusnya. Daftar kosong berarti setiap bagian.
`sub_account_ids`	Akun terkelola mana yang boleh ditindaklanjuti oleh kunci tersebut. Kosong berarti hanya akun Anda sendiri; `["*"]` berarti akun apa pun yang benar-benar Anda kelola. Kepemilikan tetap diperiksa pada setiap permintaan.
`rate_limit_per_min`	Permintaan per menit untuk kunci ini, dihitung dalam anggarannya sendiri sehingga tidak dapat menghabiskan jatah integrasi Anda yang lain. Defaultnya adalah `60`, dan tidak dapat diatur di atas `300`.

Anda juga dapat memberikan tanggal expires_at pada kunci (ISO 8601, dan harus di masa mendatang). Setelah saat itu, kunci akan berhenti berfungsi dengan sendirinya. Kosongkan jika Anda ingin kunci tidak pernah kedaluwarsa sampai Anda mencabutnya.

Penolakan bersifat tertutup. Jika permintaan berada di luar apa yang diizinkan oleh kunci, permintaan tersebut akan ditolak alih-alih dibiarkan lewat: penulisan dengan kunci hanya-baca akan mengembalikan 403 dengan error_code: "key_read_only", dan apa pun di luar bagian yang diizinkan kunci akan mengembalikan 403 dengan error_code: "key_scope_denied". Jika kunci cakupan mendapatkan 403 yang tidak terduga, endpoint yang Anda panggil tidak termasuk dalam cakupannya — perluas cakupan kunci atau gunakan kunci utama Anda.

Hanya pemilik akun yang mengelola kunci. Keempat endpoint ini memerlukan kunci utama Anda, atau sesi pemilik di aplikasi. Kunci cakupan tidak akan pernah bisa mencantumkan, membuat, mengedit, atau mencabut kunci — termasuk dirinya sendiri — sehingga kunci terbatas tidak akan pernah bisa digunakan untuk membuat kunci yang lebih luas. Mencobanya akan mengembalikan 403 dengan error_code: "key_scope_denied". Karena alasan yang sama, API Keys bukanlah bagian yang dapat Anda berikan: memintanya akan mengembalikan 400 dengan error_code: "invalid_scopes".

Mencantumkan kunci cakupan

Mengembalikan kunci cakupan akun, yang terbaru terlebih dahulu (hingga 200), termasuk yang dicabut sehingga Anda dapat melihat apa yang ditarik dan kapan. Hanya pratinjau tersamar yang dikembalikan — nilai kunci cakupan ditampilkan satu kali, saat pembuatan, dan tidak dapat diambil setelahnya.

GET /api-keys

cURL

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

Respons

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Membuat kunci cakupan

Membuat kunci cakupan baru dan mengembalikan nilainya sekali.

POST /api-keys

Kunci hanya ditampilkan sekali. Kunci ini ada dalam respons ini dan tidak ada di tempat lain, selamanya — tidak ada cara untuk mencarinya lagi setelahnya. Simpan kunci tersebut segera setelah Anda menerimanya. Jika Anda kehilangannya, cabut kunci tersebut dan buat yang baru.

Kolom isi — semuanya opsional:

Kolom	Tipe	Catatan
`label`	string	Nama Anda sendiri untuk kunci tersebut, ditampilkan dalam daftar dan di Pengaturan.
`scopes`	object	Empat kolom dalam tabel di atas. Biarkan seluruh objek kosong dan Anda akan mendapatkan default yang aman: hanya-baca, terbatas pada `Analytics`, akun Anda sendiri saja, 60 permintaan per menit.
`expires_at`	tanggal ISO 8601	Kedaluwarsa opsional, harus di masa mendatang.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Respons — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Beberapa detail yang perlu diketahui saat Anda membangun aplikasi berdasarkan ini:

Menghilangkan scopes tidak sama dengan mengirim daftar tags kosong. Biarkan scopes kosong sepenuhnya dan Anda akan mendapatkan default yang aman (hanya-baca, Analytics saja). Kirim "tags": [] dengan sengaja dan kunci tersebut dapat menggunakan setiap bagian — itu dibaca sebagai permintaan yang disengaja untuk kunci tanpa batasan.
read_only tetap true kecuali Anda secara eksplisit mengirim false. Kesalahan ketik atau tanda yang hilang tidak akan pernah secara tidak sengaja menghasilkan kunci yang dapat menulis.

Memperbarui kunci cakupan

Mengubah label, cakupan, dan/atau kedaluwarsa kunci. Kirim kombinasi apa pun dari ketiganya; mengirim tidak satu pun dari ketiganya akan mengembalikan 400.

PATCH /api-keys/{id}

{id} adalah id kunci dari daftar (nilai key_...), bukan kunci itu sendiri.

Cakupan diganti, bukan digabungkan. Apa pun yang Anda kirim menjadi set izin lengkap kunci tersebut. Itu disengaja: mempersempit kunci tidak akan pernah secara diam-diam membiarkan akses lama yang lebih luas tetap ada. Selalu kirim objek scopes lengkap yang Anda inginkan, bukan hanya kolom yang ingin Anda ubah.

Nilai kunci tidak pernah berubah. Tidak ada rotasi di tempat untuk kunci cakupan — untuk menggantinya, buat kunci baru dan cabut kunci lama, sehingga akses kredensial tidak akan pernah berubah di bawah integrasi yang masih memegangnya.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Respons

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Jika tidak ada kunci dengan id tersebut di akun Anda, responsnya adalah 404.

Mencabut kunci cakupan

Pencabutan bersifat segera: permintaan berikutnya yang menggunakan kunci tersebut akan ditolak dengan 401. Kunci utama Anda dan setiap kunci cakupan lainnya tidak akan terpengaruh.

DELETE /api-keys/{id}

Kunci tersebut tetap ada dalam daftar Anda dengan tanda "revoked": true, sehingga Anda tetap memiliki catatan tentang apa yang pernah ada dan apa yang dapat diaksesnya. Mencabut kunci yang sudah dicabut akan berhasil dan tidak mengubah apa pun.

cURL

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

Respons

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Kesalahan API Kunci API

Endpoint kunci API mengembalikan amplop kesalahan standar:

{
  "success": false,
  "error": "No API key found for this account"
}

Pada endpoint kunci API, kunci yang hilang atau tidak valid akan mengembalikan 401 dan akun tanpa kunci dalam file akan mengembalikan 404. Kode bersama yang dapat dikembalikan oleh setiap endpoint — 400, 403 (paket Anda tidak menyertakan akses API), 429 (batas kecepatan), dan 500 — tercantum beserta panduan percobaan ulang di Kesalahan & Penomoran Halaman.

Titik akhir kunci cakupan menambahkan beberapa kode bernama di kolom error_code agar Anda dapat membedakan kasus-kasus tersebut:

`error_code`	Status	Apa yang terjadi
`key_read_only`	`403`	Kunci baca-saja mencoba melakukan penulisan.
`key_scope_denied`	`403`	Kunci tidak diizinkan pada titik akhir tersebut atau akun terkelola tersebut — atau kunci cakupan mencoba mengelola kunci API, yang tidak pernah diizinkan.
`invalid_scopes`	`400`	Cakupan yang diminta menyertakan bagian `API Keys`. Kunci tidak dapat mengelola kunci.
`404`	`404`	Tidak ada kunci dengan id tersebut di akun Anda.

Langkah berikutnya

Autentikasi — empat cara untuk mengautentikasi permintaan, dan bagaimana cakupan kunci diberlakukan.
Error & Batas Kecepatan — kode status dan batas 300 permintaan/menit.

API Keys API #

Mendapatkan metadata kunci saat ini #

Mendapatkan penggunaan batas laju (rate-limit) #

Merotasi kunci #

Cabut kunci #

Kunci cakupan #

Mencantumkan kunci cakupan #

Membuat kunci cakupan #

Memperbarui kunci cakupan #

Mencabut kunci cakupan #

Kesalahan API Kunci API #

Langkah berikutnya #

API Keys API

Mendapatkan metadata kunci saat ini

Mendapatkan penggunaan batas laju (rate-limit)

Merotasi kunci

Cabut kunci

Kunci cakupan

Mencantumkan kunci cakupan

Membuat kunci cakupan

Memperbarui kunci cakupan

Mencabut kunci cakupan

Kesalahan API Kunci API

Langkah berikutnya