Autentikasi

Cara autentikasi ke API Baiyar: API key bearer, environment, key proyek dan key merchant, pembatasan, kedaluwarsa, dan praktik terbaik.

Kirim secret API key sebagai bearer token di setiap request:

Authorization: Bearer bk_test_…

Buat API key

Key dibuat di dashboard (API Key), untuk environment tempat kamu berada, dan key lengkapnya ditampilkan sekali saja. Langkahnya ada di Ambil API key.

Membuat request

Simpan key di environment variable dan kirim di header Authorization. GET /v1/account adalah panggilan paling sederhana: tidak butuh izin dan memberi tahu siapa pemilik key.

curl "https://api.baiyar.com/v1/account" \
  -H "Authorization: Bearer $BAIYAR_KEY"

const response = await fetch("https://api.baiyar.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.BAIYAR_KEY}` },
});
console.log(await response.json());

import os
import requests

response = requests.get(
    "https://api.baiyar.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['BAIYAR_KEY']}"},
)
print(response.json())

{
  "data": {
    "livemode": false,
    "merchant": { "id": "mer_01k7q3m8x2v5t9n4b6c1d0e7fa" },
    "project": { "id": "prj_01k7q3m8x2v5t9n4b6c1d0e7fa" },
    "key": {
      "id": "apk_01k7q3m8x2v5t9n4b6c1d0e7fa",
      "kind": "project",
      "scopes": ["payments:read", "payments:write"]
    }
  },
  "meta": { "request_id": "req_Hy3k9QzT2LmN8vXa" }
}

data.livemode: false menandakan ini test key. data.key.kind adalah project atau merchant, dan data.key.scopes mendaftar izin-nya.

Format API key

Key adalah bk_test_ (sandbox) atau bk_live_ (live) diikuti 43 karakter. Awalan menunjukkan environment tempat key berlaku.

Key	Environment	Host
`bk_test_…`	Sandbox	`https://api.baiyar.com`
`bk_live_…`	Live	`https://api.baiyar.com`

Sandbox dan live memakai satu host, https://api.baiyar.com: awalan key menentukan environment yang dituju. Tidak ada yang kamu lakukan dengan test key yang memindahkan uang sungguhan. Kami hanya menyimpan hash dari key, jadi kami tidak bisa menampilkannya lagi.

Jangan taruh key di URL. Request dengan api_key, token, atau sejenisnya di query string ditolak, karena URL berakhir di log.

Key proyek dan key merchant

	Key proyek	Key merchant
Berlaku untuk	Satu proyek	Semua proyek merchant
`project_id` di request	Tidak perlu	Menyebut proyeknya
Membaca saldo akun	Tidak	Ya
Bisa punya `payouts:write`	Ya	Tidak

Sebuah proyek bisa punya sampai 10 key aktif di tiap environment (key merchant dihitung untuk merchant).

Batasi key ke server kamu

Key bisa dibatasi ke alamat IP atau rentang (CIDR) tempat server kamu memanggil, sampai 20. Panggilan dari tempat lain ditolak dengan ip_not_allowed walaupun key-nya benar.

Kedaluwarsa dan rotasi

Key bisa diberi tanggal kedaluwarsa saat dibuat, dan setelah tanggal itu key berhenti bekerja. Memutar key membuat key baru dengan izin yang sama dan membiarkan key lama berlaku 24 jam. Lihat Putar API key.

Izin dan batas

Apa yang boleh dilakukan key ditentukan izin-nya, dan seberapa sering ia boleh memanggil ditentukan rate limit.

Praktik terbaik

Selalu

Simpan key di server, di environment variable atau secret store.
Beri key hanya izin yang dibutuhkan, dan batasi ke alamat server kamu.
Pakai key terpisah untuk tiap server atau layanan, supaya satu bisa dicabut tanpa mengganggu yang lain.
Cabut key seketika kalau kamu curiga bocor.

Jangan pernah

Menaruh key di aplikasi mobile, halaman web, repository, atau URL.
Mengirim live key ke tempat yang tidak kamu kendalikan.

Error yang umum

Situasi	Jawaban
Tanpa key, key rusak, tidak dikenal, kedaluwarsa, atau dicabut	`401` `invalid_api_key`
Key tanpa izin yang dibutuhkan	`403` `insufficient_scope`
Alamat yang tidak diizinkan	`403` `ip_not_allowed`
Terlalu banyak request	`429` `rate_limited`