Kunci API — tnea_ & tnsr_¶

NumerologyAPI menggunakan dua keluarga kunci API. Keduanya terlihat serupa, dibuat dengan format aman 80 karakter yang sama, dan mengautentikasi dengan header X-API-Key yang sama — tetapi keduanya dimeter dengan cara berbeda dan ditujukan untuk produk yang berbeda.

1. Format & Keamanan Kunci¶

Setiap kunci memiliki panjang persis 80 karakter:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix 4 karakter mengidentifikasi jenis kunci; 75 karakter sisanya dibuat dengan sumber acak yang aman secara kriptografis.
• Kunci disimpan ter-hash SHA-256 di sisi server. Teks kunci asli hanya ditampilkan sekali saja, saat dibuat.
• Jika sebuah kunci pernah terekspos, putar segera dari dashboard.

2. Kunci Platform (tnea_)¶

Kunci platform adalah kunci standar untuk mengintegrasikan NumerologyAPI ke dalam produk Anda sendiri — situs web, aplikasi seluler, dan layanan sisi server.

Autentikasi¶

Kirim kunci pada setiap permintaan dengan header X-API-Key:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Metering¶

Panggilan /api/v1 yang dapat ditagih dipotong dari dompet kredit organisasi Anda (pay-as-you-go). Anda dapat mengisi ulang dompet kapan saja dari dashboard.

Aturan kanal: kunci platform tidak boleh mengirim header X-Numora-Client. Mengirimnya akan mengembalikan 403 — header tersebut khusus untuk kanal desktop.

3. Kunci Numora Studio (tnsr_)¶

Kunci Numora Studio mengautentikasi aplikasi desktop Numora Studio (macOS/Windows) yang digunakan praktisi untuk membuat laporan klien. Kunci ini merupakan turunan dari kunci platform dengan format yang identik, tetapi ditagihkan ke jatah paket Numora Studio organisasi, bukan ke kredit platform.

Penyediaan¶

Kunci tnsr_ dibuat melalui salah satu cara berikut:

• melalui alur masuk aplikasi desktop (halaman persetujuan browser menyediakan kunci secara otomatis), atau
• secara manual di halaman Kunci API pada dashboard (/api-keys).

Tanda tangan kanal (wajib)¶

Setiap panggilan yang dilakukan dengan kunci tnsr_ harus menyertakan header kanal desktop:

Penegakan di server:

• Kunci tnsr_ tanpa X-Numora-Client → 403.
• Kunci tnea_ dengan X-Numora-Client → 403.

Metering¶

• Panggilan /api/v1 yang dapat ditagih dipotong dari jatah paket Numora Studio organisasi (satu pool bersama untuk semua kunci tnsr_ di organisasi).
• Terdapat tombol fallback kredit per kunci tnsr_: saat jatah paket habis, kunci dapat beralih ke kredit platform organisasi (nonaktif secara bawaan).
• Jika jatah habis dan tidak ada fallback yang diaktifkan, panggilan mengembalikan 429.

Penguncian perangkat (opsional)¶

Kunci tnsr_ dapat dikunci ke perangkat terdaftar. Dengan penguncian diaktifkan, setiap permintaan harus menyertakan X-Numora-Device-Id yang terdaftar pada organisasi; perangkat yang tidak terdaftar ditolak dengan 403.

Endpoint khusus desktop¶

Beberapa endpoint khusus untuk kanal desktop dan mengembalikan 403 untuk kunci tnea_:

• POST /api/v1/numora/report-bundle — laporan klien lengkap dalam satu panggilan
• POST /api/v1/numora/order — alur pembelian paket/jatah dalam aplikasi
• POST /api/v1/numora/devices/register — mendaftarkan instalasi desktop
• GET /api/v1/numora/studio-status — saldo dan meter kuota desktop

Tip: respons yang dapat ditagih juga menyertakan header X-Remaining-Credits dan X-Remaining-Tokens sehingga Anda dapat melacak saldo secara langsung tanpa panggilan tambahan.

4. Mengelola Kunci (Dashboard)¶

Halaman Kunci API pada dashboard (/api-keys) adalah pusat kendali untuk kedua jenis kunci.

Peran: peran admin dan developer dapat membuat dan mengelola kunci. finance tidak dapat membuat kunci API produksi. Operasi finansial (pembelian paket, pengisian ulang) dibatasi untuk admin dan finance.

Beberapa kunci: organisasi dapat memiliki banyak kunci dari kedua jenis — misalnya satu kunci tnsr_ per praktisi atau per instalasi desktop. Jatah dibagi per organisasi, sehingga kunci tidak pernah "bersaing" untuk saldo mereka sendiri.

5. Praktik Terbaik¶

• Perlakukan kunci seperti kata sandi. Jangan pernah menyematkannya dalam kode sisi klien, repositori publik, atau log.
• Gunakan variabel lingkungan atau pengelola rahasia di backend Anda.
• Putar segera jika kunci dibobol atau anggota tim keluar.
• Gunakan satu kunci tnsr_ per instalasi desktop untuk menyederhanakan pengelolaan dan pencabutan perangkat.
• Aktifkan penguncian perangkat untuk organisasi dengan keamanan tinggi.
• Pantau penggunaan di dashboard untuk mendeteksi lonjakan tak terduga sejak dini.

6. Pertanyaan Umum¶

Dapatkah kunci tnsr_ memanggil endpoint platform biasa? Ya. Kunci Numora Studio mengautentikasi seluruh permukaan /api/v1; panggilan tersebut ditagihkan ke jatah paket Numora Studio.

Dapatkah kunci tnea_ memanggil endpoint khusus desktop /numora/*? Tidak. Endpoint khusus desktop mengembalikan 403 untuk kunci platform.

Mengapa saya mendapat 403 saat memanggil dengan kunci tnsr_ saya? Kemungkinan besar header X-Numora-Client tidak ada atau id aplikasi tidak cocok. Pastikan setiap permintaan menyertakan X-Numora-Client: numora-studio/<version>.

Mengapa saya mendapat 403 dengan kunci tnea_ saya? Kunci platform tidak boleh membawa header X-Numora-Client — hapus header tersebut.

Apa yang terjadi saat jatah saya habis? Panggilan yang dapat ditagih mengembalikan 429 kecuali fallback kredit diaktifkan pada kunci tnsr_ Anda (atau Anda mengisi ulang dompet platform untuk kunci tnea_).

Terkait¶

• Memulai
• Harga
• Solusi Perusahaan