Authentication

Setiap permintaan membawa satu header:

curl https://api.mageran.ai/api/v1/balance \
  --header 'x-mager-api-key: YOUR_API_KEY'

Tidak ada alur OAuth dan tidak ada token yang perlu di-refresh. Key itu sendiri adalah kredensialnya.

Mendapatkan key

1. Ajukan akun developer dari dashboard Mager. Statusnya dimulai sebagai PENDING.
2. Tunggu persetujuan. Key belum bisa dibuat sebelum akun berstatus APPROVED.
3. Buat key. Nilai aslinya hanya dikembalikan sekali, saat pembuatan.

Mager hanya menyimpan hash dari key tersebut. Kalau hilang, rotasi key-nya dan perbarui aplikasi Anda — nilai aslinya tidak bisa dipulihkan.

Scope

Setiap key membawa sekumpulan scope. Permintaan ke endpoint yang tidak tercakup oleh key Anda akan gagal dengan 403, terlepas dari kondisi akun yang lain.

Key baru dibuat dengan kelima scope kecuali Anda mempersempitnya. Persempit jika memungkinkan: key yang hanya bisa membaca template tidak bisa menghabiskan saldo Anda.

Key yang diterbitkan sebelum CLIPPING ada tetap membawa scope saat key itu dibuat, jadi key lama tidak bisa mengakses Clipping Engine. Buat key baru untuk memakainya.

IP allowlist

Sebuah key bisa dibatasi ke daftar IP sumber tertentu. Saat daftarnya tidak kosong, permintaan dari alamat lain ditolak dengan 403, meskipun key-nya valid.

Mager membaca alamat klien dari x-forwarded-for bila ada, dan jatuh kembali ke alamat socket. Kalau trafik Anda keluar lewat NAT gateway dengan alamat tetap, fitur ini layak dinyalakan.

Rotasi dan pencabutan

Rotate mengganti secret pada key yang sudah ada dan mengembalikan nilai asli yang baru. Secret lama langsung berhenti bekerja, jadi deploy yang baru sebelum melakukan rotasi, atau terima adanya jeda.

Revoke menonaktifkan key. Permintaan yang memakainya gagal mulai panggilan berikutnya.

Keduanya dilakukan dari dashboard.

Masa berlaku

Sebuah key bisa diberi tanggal kedaluwarsa. Setelah tanggal itu lewat, key ditolak sama seperti key yang dicabut. Key yang dibuat tanpa tanggal kedaluwarsa tidak pernah kedaluwarsa.

Bentuk kegagalannya

Body response-nya mengikuti format error standar.