Autentikasi dan API Key

Apa itu API key

API key adalah rahasia yang dikirim kode Anda ke Cognivo agar kami tahu bahwa sebuah permintaan berasal dari Anda. Setiap panggilan Developer API membawa satu key. Key berada di dalam sebuah proyek, dan proyek mengelompokkan key Anda beserta penggunaannya.

Baca halaman ini sebelum panggilan pertama Anda, ketika Anda perlu tahu apa saja yang boleh dilakukan sebuah key, atau ketika sebuah key mungkin bocor dan Anda perlu mematikannya.

Di mana menemukannya

Masuk ke dApp Cognivo, buka Account di sidebar kiri, lalu Developers. Jika belum masuk, halaman hanya menampilkan layar pengantar.

Halaman Developers memiliki empat tab: Keys, Usage, Endpoints, dan Quickstart. Semua hal di halaman ini terjadi pada tab Keys.

Akses live dan saldo kredit Anda

Sebuah spanduk di bagian atas halaman menyatakan model aksesnya secara gamblang: sebagian endpoint gratis dengan key aktif mana pun, dan sebagian lain dibebankan per panggilan yang berhasil dari saldo kredit Cognivo Anda. Lebih ke bawah, kartu Live API access menegaskan bahwa key live bekerja begitu Anda membuatnya. Tidak ada tahap persetujuan dan tidak ada daftar tunggu.

Di sebelahnya halaman menampilkan saldo kredit Anda saat ini, tombol Top up credits, dan tombol Enterprise access. Enterprise adalah satu-satunya jalur akses yang melewati sebuah pengajuan, untuk harga khusus atau batas yang lebih tinggi. Selebihnya dilakukan sendiri.

Panel Live API access, lebih jauh ke bawah di halaman Developers.Perbesar gambar

Setiap akun Cognivo juga menerima 5 kredit gratis setiap hari, yang disetel ulang pada tengah malam UTC. Lihat Billing dan kredit untuk cara kerja saldo, dan Batas laju, kesalahan, dan penagihan untuk harga per endpoint.

Tab Keys

Pilih sebuah proyek dari dropdown Project, atau buat satu dengan New project. Tab Keys kemudian mencantumkan setiap key yang termasuk di dalamnya.

Tab Keys di halaman Developers, yang mencantumkan setiap key milik proyek yang dipilih.Perbesar gambar

Setiap baris key menampilkan nama yang Anda berikan, apakah itu key Test atau Live, batas per jam yang berlaku, izin yang dibawanya, serta kapan key itu dibuat dan terakhir digunakan. Last used: Never berarti belum pernah ada panggilan yang dibuat dengan key tersebut.

Hanya prefiks dan empat karakter terakhir sebuah key yang ditampilkan. Cognivo tidak menyimpan apa pun lagi yang bisa dibaca kembali, itulah sebabnya key lengkap muncul tepat satu kali.

Membuat sebuah key

Pilih + New key. Formulirnya menanyakan tiga hal: nama opsional untuk membantu Anda membedakan key, mode Test atau Live, dan setidaknya satu izin.

Formulir key baru di halaman Developers, dibuka dengan tombol New key.Perbesar gambar

Memilih Live akan menampilkan saldo kredit Anda di bawah dropdown mode, sebagai pengingat bahwa panggilan live adalah panggilan sungguhan dan dibebankan dari saldo tersebut. Memilih Test membuat key sandbox yang tidak pernah dikenakan biaya dan memiliki batas yang ketat.

Pilih Create key dan key lengkap muncul sekali, di dalam sebuah dialog.

1. Gunakan ikon salin untuk menyalin key lengkap selagi masih tampil di layar, karena key ini tidak akan ditampilkan lagi.
2. Pilih Done setelah key tersimpan di tempat yang bisa Anda temukan lagi nanti.

Dialog key sekali tampil di tab Keys, muncul tepat saat key baru dibuat.Perbesar gambar

Jika Anda kehilangan key itu, Anda tidak bisa memulihkannya. Lakukan rotate pada key tersebut sebagai gantinya, yang dibahas di bawah.

Mengirim key Anda

Header kanoniknya adalah X-API-Key:

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/risk' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xTOKEN_CONTRACT"}'

Authorization: Bearer YOUR_API_KEY diterima sebagai alias untuk pustaka klien yang lebih menyukainya. Simpan key di server Anda. Jangan pernah menaruhnya di kode browser.

Saat ini API mencakup Ethereum, Base, dan BNB Chain pada parameter chain bersama. Robinhood Chain sudah aktif di Cognivo dan punya endpoint tersendiri di API, bukan sebuah nilai chain pada endpoint bersama.

Izin

Key bersifat tolak secara bawaan. Sebuah key hanya bisa memanggil grup endpoint yang Anda berikan saat membuatnya. Ada tiga izin, dan masing-masing membuka satu set endpoint.

Intelligence (intel:read) adalah izin sehari-hari. Izin ini menjawab "apa yang sedang terjadi dengan token atau dompet ini?": pemicu penurunan harga, sinyal risiko, perilaku dompet tim, PnL terealisasi, dan pergerakan persis. Izin ini membuka POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl, dan POST /v1/api/wallet/exact-movements.

Security (security:read) memungkinkan sebuah key memeriksa apa saja yang telah disetujui oleh sebuah dompet, termasuk kontrak mana yang bisa membelanjakan tokennya dan allowance mana yang tidak terbatas. Izin ini hanya baca. Key dengan izin ini tidak akan pernah bisa memindahkan dana atau mencabut sebuah approval. Izin ini membuka POST /v1/api/wallet/approvals.

Liquidity (liquidity:read) memungkinkan sebuah key membaca konteks pool, kustodi LP, serta konteks lock dan burn. Izin ini membuka POST /v1/api/intel/liquidity.

GET /v1/api/health sama sekali tidak memerlukan key. GET /v1/api/me dan GET /v1/api/discover bekerja dengan key valid mana pun, apa pun izinnya.

Izin ditetapkan saat key dibuat. Untuk mengubahnya, buat key baru dengan izin yang Anda butuhkan lalu cabut key yang lama. Panggilan yang gagal dengan 403 scope_denied berarti key tersebut tidak membawa izin yang dibutuhkan endpoint itu.

Test key dan live key

Prefiks	Untuk apa	Penagihan	Batas laju
cogv_test_	Mencoba API. Diberi label Test dan Sandbox di portal. Tidak bisa menjalankan intelijen live.	tidak pernah dikenakan biaya	25 permintaan per jam, 100 per hari, 1 per detik
cogv_live_	Trafik sungguhan. Dilakukan sendiri, langsung bekerja.	Kredit Cognivo per panggilan yang berhasil. Panggilan yang gagal tidak pernah dikenakan biaya.	1,000 permintaan per jam sebagai awalan, lihat batas laju

Test key bukan key produksi gratis. Panggilan live yang dibuat dengan key semacam itu menjawab 403 sandbox_limited. Penagihan untuk panggilan Developer API dimatikan hari ini, jadi panggilan yang berhasil tidak memotong apa pun dan saldo Anda tidak berubah.

Portal juga menampilkan mode akses pada setiap key. Paid adalah bayar sesuai pemakaian biasa. Trial adalah jatah evaluasi sementara dengan tanggal berakhir. Partner dan Enterprise adalah kesepakatan yang disiapkan bersama Cognivo. Suspended berarti key tidak bisa menjalankan apa pun, dan portal menampilkan alasannya. Sejumlah kecil key lama ada sebelum penagihan mandiri dan hanya bisa memanggil endpoint metadata, sehingga panggilan live menjawab 403 access_required. Buat key live baru untuk memindahkannya ke bayar sesuai pemakaian.

GET /v1/api/me melaporkan mode akses key Anda, izinnya, credits_balance Anda, dan panduan pengisian ulang. Jika saldo Anda tidak cukup untuk sebuah panggilan, Anda mendapat 402 payment_required dan tidak ada biaya yang dikenakan. Isi ulang lalu coba lagi.

Rotate dan revoke

Kedua kontrol berada di sisi kanan setiap baris key.

1. Baca lencana Test dan Sandbox di samping nama untuk mengetahui jenis key ini, beserta batas per jam yang tampil di sebelahnya.
2. Pilih Rotate untuk mengganti key ini dengan key baru, yang ditampilkan sekali dan langsung membuat key lama berhenti bekerja.
3. Pilih Revoke untuk mematikan sebuah key selamanya, misalnya jika key itu tidak lagi diperlukan atau Anda menduga orang lain telah melihatnya.

Baris key di tab Keys pada halaman Developers.Perbesar gambar

Rotate meminta konfirmasi Anda terlebih dahulu, dan dialognya menyatakan persis apa yang akan terjadi.

Konfirmasi rotate di tab Keys, muncul setelah Anda memilih Rotate pada sebuah key.Perbesar gambar

Key yang dirotasi mempertahankan namanya, izinnya, tingkatannya, pembatasan jaringan apa pun, tanggal kedaluwarsa apa pun, dan sisa jatah apa pun, sehingga rotate itu aman dan tidak pernah diam-diam memperluas kemampuan key. Penggantinya ditampilkan sekali, di dialog yang sama seperti key baru. Revoke bersifat permanen dan langsung menghentikan key bekerja di setiap endpoint.

Lakukan rotate pada setiap dugaan kebocoran, dan secara berkala terjadwal.

Pembatasan yang bisa diterapkan Cognivo pada sebuah key

Pembatasan ini disetel pada catatan key, bukan pada formulir di portal, dan diberlakukan pada setiap permintaan. Anda bisa memastikan apa yang berlaku pada key Anda sendiri dengan GET /v1/api/me.

• Pembatasan jaringan. Sebuah key bisa dibatasi pada jaringan tertentu. Permintaan yang menyebut jaringan lain ditolak dengan 403 chain_denied. Penolakan terjadi sebelum Cognivo memanggil apa pun ke hulu dan sebelum jatah mana pun terpakai, sehingga panggilan yang tidak diizinkan bagi key Anda tidak pernah membebani biaya. Dilaporkan sebagai allowed_chains, di mana null berarti tanpa pembatasan.
• Kedaluwarsa. Sebuah key bisa diberi tanggal berakhir. Setelah tanggal itu lewat, key berhenti bekerja di mana pun, termasuk GET /v1/api/me, dan mengembalikan 403 key_expired. Dilaporkan sebagai expires_at, di mana null berarti tidak kedaluwarsa. Jika sebuah jatah trial juga punya tanggal berakhir, yang lebih dahulu tiba yang berlaku.
• Daftar izin origin dan IP. Sebuah key bisa dibatasi pada origin tertentu, termasuk subdomain wildcard seperti https://*.yourapp.com, atau pada alamat IP dan rentang CIDR tertentu. Permintaan dari tempat lain ditolak dengan 403 origin_denied. Daftar kosong berarti tanpa pembatasan.

Langkah berikutnya

Dengan key di tangan, lakukan panggilan pertama Anda di Panduan Cepat, lalu jelajahi Referensi endpoint untuk melihat apa yang dikembalikan setiap endpoint dan berapa biayanya. Jika sebuah panggilan kembali dengan kode kesalahan yang tidak Anda kenali, Batas laju, kesalahan, dan penagihan mencantumkan semuanya.