Autentikasi, API key, dan scope

Base URL, format request, cara membuat API key, dan scope yang dibutuhkan setiap endpoint REST API kirim.id.

Developer Diperbarui 4 Oktober 2026 3 menit bacaKB-10

Di halaman ini

Dasar & format
Membuat API key
Memakai API key
Scope
Cek koneksi dengan info akun
Jawaban saat autentikasi gagal
Langkah berikutnya

Semua request ke REST API kirim.id diautentikasi dengan API key yang kamu buat sendiri di dashboard. Artikel ini menjelaskan aturan dasar API (base URL, format, waktu, uang), cara memakai API key, dan scope apa yang perlu kamu pilih supaya key hanya punya izin seperlunya.

Dasar & format#

Hal	Keterangan
Base URL	`https://api.kirim.id/v1` — hanya HTTPS.
Format request	JSON (`Content-Type: application/json`) atau form (`application/x-www-form-urlencoded`). Spasi di awal/akhir teks otomatis dibuang; teks kosong dianggap tidak diisi.
Format jawaban	Selalu JSON, termasuk saat error. Header `Accept` tidak wajib.
Waktu	UTC, format ISO 8601. Data objek memakai `2026-09-22T03:04:05.000000Z`; payload webhook memakai `2026-09-22T03:04:05+00:00`.
Uang	Rupiah bulat (integer), tanpa desimal.
Pemakaian	Server-ke-server. API tidak mengirim header CORS.
Modul	Workspace harus punya modul Email Marketing aktif. Tanpa itu semua endpoint menjawab `403`.

Membuat API key#

Buka Settings → API Keys
Masuk ke dashboard kirim.id, lalu buka menu Settings → API Keys.
Beri nama sesuai sistem pemakainya
Buat key terpisah per sistem, misalnya "Website" dan "CRM". Kalau salah satu sistem bermasalah, kamu cukup mencabut key-nya tanpa mengganggu sistem lain.
Pilih scope seperlunya
Centang hanya izin yang dibutuhkan sistem itu (lihat tabel scope di bawah).
Simpan di server
Simpan key sebagai environment variable atau secret manager di server, bukan di kode yang ikut ter-commit.

Key bisa dilihat ulang di dashboard kapan pun, dan bisa dicabut. Request dengan key yang sudah dicabut langsung ditolak.

Memakai API key#

Setiap request wajib membawa header Authorization dengan skema Bearer:

cURL

Authorization: Bearer api_kirimXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Format key: api_kirim diikuti 32 huruf/angka (total 41 karakter). Key tidak bisa dikirim lewat query string.

Scope#

Satu key boleh punya beberapa scope. Kalau key dipakai ke endpoint di luar scope-nya, API menjawab 403.

Scope	Label di dashboard	Endpoint
`send_email`	Kirim Email	`GET /domains`, `POST /messages`, `GET /messages`, `GET /messages/{id}`, `GET /suppressions`, `GET /campaigns`, `POST /campaigns/{id}/send`, `GET /journeys`, `POST /journeys/{id}/enroll`, `POST /conversions`
`manage_contacts`	Kelola Kontak/Audiens	`GET /contacts`, `GET /contacts/{id}`, `GET /contacts/engagement`, `POST /contacts`, `PATCH /contacts/{id}`, `POST /contacts/{id}/unsubscribe`, `DELETE /contacts/{id}`, `GET /audiences`, `GET /audiences/{id}`, `POST /audiences`, `GET`·`POST /audiences/{id}/contacts`, `DELETE /audiences/{id}/contacts/{contact_id}`
`manage_webhooks`	Kelola Webhook	`GET /webhooks`, `POST /webhooks`, `DELETE /webhooks/{id}`
scope apa pun	—	`GET /account`

Cek koneksi dengan info akun#

GET/v1/account

Memastikan key valid dan menampilkan saldo koin, kecepatan kirim, serta domain yang siap dipakai. Bisa dipanggil dengan scope apa pun dan tidak memotong koin.

Endpoint ini cocok untuk tombol "Cek koneksi" di aplikasi atau plugin buatanmu.

cURL

curl https://api.kirim.id/v1/account \
  -H "Authorization: Bearer $KIRIM_API_KEY"

JSON

{
  "workspace": {"id": 3, "name": "Toko Rina", "business_address_set": true},
  "modules": ["email"],
  "api_key": {"name": "Website", "scopes": ["send_email", "manage_contacts"]},
  "limits": {"requests_per_minute": 60, "max_attachments": 10, "max_attachments_bytes": 10485760},
  "email": {
    "coins": 8420, "premium": true, "send_per_minute": 1200, "send_per_day": null,
    "domains": [{"id": 1, "domain": "tokomu.com", "status": "active"}]
  }
}

Bagian email hanya muncul kalau modul Email aktif. send_per_day: null artinya tanpa batas harian.

Jawaban saat autentikasi gagal#

Status	Kapan	Isi `message`
401	Header `Authorization` tidak ada	Missing API key.
401	Key salah atau sudah dicabut	Invalid or revoked API key.
403	Akun disuspend	Workspace disuspend.
403	Key tidak punya scope yang dibutuhkan	API key ini tidak punya scope 'send_email'.
403	Modul Email tidak aktif	Modul Email Marketing belum aktif untuk akun ini. Aktifkan di app.kirim.id/produk.
403	Modul Email sedang ditutup sementara oleh kirim.id	Modul Email Marketing sedang tidak tersedia.

Error 401 dan 403 tidak akan berubah kalau diulang — perbaiki key atau pengaturan akun dulu, jangan pasang retry otomatis.

Langkah berikutnya#

Apakah artikel ini membantu?