Dokumentasi API

Pola Autentikasi Lanjutan — OAuth 2.0, JWT, Rotasi Kunci

Kuasa mekanisme autentikasi canggih untuk mengintegrasikan Smart Money API di lingkungan perusahaan. Pelajari alur OAuth 2.0, pola token JWT, rotasi kunci yang aman, dan implementasi autentikasi multi-faktor.

Diterbitkan 21 Maret 2026 • 18 menit baca • Lanjutan

Ikhtisar Autentikasi

Smart Money API mendukung berbagai metode autentikasi yang dirancang untuk menyesuaikan dengan arsitektur aplikasi, persyaratan keamanan, dan kebijakan organisasi yang berbeda. Memahami pola ini memastikan integrasi Anda aman dan berkinerja tinggi.

Autentikasi di Smart Money API beroperasi pada tiga lapisan utama:

  • Kunci API — Autentikasi bearer token sederhana untuk pengembangan dan integrasi langsung
  • Token JWT — Token stateless yang ditandatangani secara kriptografis untuk sistem terdistribusi dan layanan mikro
  • OAuth 2.0 — Kerangka kerja otorisasi delegasi untuk integrasi pihak ketiga dan aplikasi SaaS

Prinsip Keamanan: Jangan pernah mengekspos kredensial autentikasi dalam kode klien, log, kontrol versi, atau pesan error. Terapkan rotasi kredensial sesuai jadwal dan segera jika terjadi kompromi.

Setiap metode memiliki keunggulan berbeda. Kunci API bekerja paling baik untuk komunikasi backend-to-backend di mana penyimpanan kredensial dikontrol. Token JWT unggul dalam arsitektur terdistribusi di mana tidak ada status bersama yang tersedia. OAuth 2.0 menyediakan akses delegasi pengguna untuk aplikasi pihak ketiga.

Autentikasi Kunci API

Kunci API adalah mekanisme autentikasi paling sederhana—merupakan string acak yang dihasilkan untuk akun Anda yang mengidentifikasi aplikasi Anda ke Smart Money API. Setiap permintaan harus menyertakan kunci API Anda baik sebagai header atau parameter query.

Kunci API Berbasis Header

Pendekatan yang direkomendasikan adalah memberikan kunci API Anda di header Authorization menggunakan skema Bearer:

curl Contoh
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"

Kunci API Parameter Query

Untuk koneksi WebSocket atau saat header tidak dapat dimodifikasi, berikan kunci API sebagai parameter query:

Koneksi WebSocket
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Membangun aliran WebSocket yang terautentikasi

Karakteristik Kunci API

Properti Deskripsi
Format String heksadesimal 128 karakter dengan awalan sk_test_ atau sk_live_
Cakupan Mewarisi semua izin dari akun yang membuatnya
Kedaluwarsa Tidak pernah kedaluwarsa secara otomatis; harus diputar secara manual
Rotasi Buat kunci baru, migrasikan lalu lintas, lalu nonaktifkan kunci lama
Batas Laju Dibagikan di semua permintaan yang menggunakan kunci yang sama

Praktik Keamanan Kunci API

  • Variabel Lingkungan — Simpan kunci dalam file .env (tidak disimpan dalam kontrol versi) dan muat saat runtime
  • Sistem Vault — Gunakan HashiCorp Vault, AWS Secrets Manager, atau Azure Key Vault di lingkungan produksi
  • Pisahkan Kunci — Pertahankan kunci uji dan kunci live terpisah; putar kunci uji secara berkala
  • Cakupan Minimal — Buat kunci terpisah untuk integrasi yang berbeda jika memungkinkan
  • Pencatatan Audit — Catat semua pembuatan dan penggunaan kunci API
Dapatkan kunci API Anda dalam 30 detik

Siap membangun? Dapatkan kunci API gratis (100 panggilan/hari, tanpa kartu) dan mulai menarik data live whale, funding, dan on-chain.

Dapatkan kunci API Anda →

Pola Bearer Token

Bearer token memperluas konsep kunci API sederhana dengan menambahkan konteks, kedaluwarsa, dan mekanisme penyegaran. Ideal untuk aplikasi yang membutuhkan manajemen kredensial secara terprogram.

Memperoleh Bearer Token

Tukar kunci API dan rahasia Anda dengan bearer token yang berlaku selama 24 jam:

GET /auth/token
curl -X POST "https://api.smartmoneyapi.com/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk_live_1234567890",
"api_secret": "secret_abc123xyz"
}'

Format Respons Token

Endpoint mengembalikan bearer token dengan metadata:

Respons
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}

Menggunakan Bearer Token

Sertakan token di header Authorization untuk semua permintaan berikutnya:

Permintaan Terautentikasi
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Alur Penyegaran Token

Ketika token mendekati kedaluwarsa, gunakan refresh token untuk mendapatkan yang baru tanpa memerlukan rahasia API Anda:

POST /auth/refresh
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'

Implementasi OAuth 2.0

OAuth 2.0 memungkinkan pengguna memberikan akses aplikasi ke akun Smart Money API mereka tanpa membagikan kredensial. Ini penting untuk platform SaaS, integrasi pihak ketiga, dan aplikasi multi-tenant.

Alur Kode Otorisasi OAuth 2.0

Alur standar untuk aplikasi web:

  1. Pengguna Memulai Login — Pengguna mengklik "Hubungkan dengan Smart Money API"
  2. Alihkan ke Server Otorisasi — Aplikasi Anda mengalihkan pengguna ke endpoint otorisasi Smart Money
  3. Pengguna Memberikan Izin — Pengguna meninjau cakupan yang diminta dan memberikan akses
  4. Kode Otorisasi Dikembalikan — Pengguna dialihkan kembali dengan kode otorisasi
  5. Tukar Kode dengan Token — Backend menukar kode dengan token akses (kode tidak pernah terpapar ke frontend)
  6. Simpan Token — Simpan refresh token dengan aman; gunakan access token untuk panggilan API

Langkah 1: Arahkan Pengguna ke Endpoint Otorisasi

Pengalihan Frontend
// URL untuk mengarahkan pengguna
const authUrl = new URL('https://api.smartmoneyapi.com/oauth/authorize');
authUrl.searchParams.append('client_id', 'your_client_id');
authUrl.searchParams.append('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.append('response_type', 'code');
authUrl.searchParams.append('scope', 'whales derivatives onchain');
authUrl.searchParams.append('state', generateRandomState());
window.location.href = authUrl.toString();

Langkah 2: Tangani Callback dan Tukar Kode

Pertukaran Kode Backend
// Backend menangani rute /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Verifikasi parameter state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// Tukar kode untuk token
const tokenResponse = await fetch('https://api.smartmoneyapi.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
grant_type: 'authorization_code',
code: code,
client_id: process.env.OAUTH_CLIENT_ID,
client_secret: process.env.OAUTH_CLIENT_SECRET,
redirect_uri: 'https://yourapp.com/callback'
})
});
const tokens = await tokenResponse.json();
// Simpan token dengan aman

OAuth Scopes

Minta hanya scope yang dibutuhkan aplikasi Anda. Smart Money API mendefinisikan scope berikut:

Scope Deskripsi
whales Akses pelacakan dompet whale dan metrik akumulasi
derivatives Akses data futures, perpetuals, dan funding rate
onchain Akses aliran transaksi dan analitik on-chain
alerts Buat dan kelola alert webhook
offline Akses refresh token untuk mendapatkan access token offline

JWT Token Management

JWT (JSON Web Tokens) menyediakan otentikasi stateless—server tidak perlu menyimpan data sesi. Smart Money API menggunakan RS256 (RSA Signature dengan SHA-256) untuk penandatanganan token, memungkinkan verifikasi tanpa menghubungi API.

JWT Structure

Token JWT terdiri dari tiga bagian yang dipisahkan oleh titik:

JWT Format
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE

JWT Header

Header mengidentifikasi algoritma dan jenis token:

Decoded Header
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}

JWT Payload Claims

Payload berisi klaim (pernyataan tentang pengguna/aplikasi):

Decoded Payload
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}

Verifying JWT Signatures

Unduh public key Smart Money dan verifikasi token sebelum menerimanya:

Node.js Verification
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Dapatkan public key dari Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Verifikasi token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Token valid, gunakan klaim yang didekode
} catch (err) {
// Token tidak valid atau kedaluwarsa
}

Key Rotation Strategy

Rotasi kunci rutin sangat penting untuk menjaga keamanan. Bahkan dengan praktik keamanan sempurna, asumsikan kunci dapat disusupi dan terapkan rotasi sistematis.

Rotation Frequency

Smart Money merekomendasikan jadwal rotasi berbeda berdasarkan jenis dan penggunaan kunci:

Key Type Recommended Rotation Minimum Rotation
Test API Keys Monthly Quarterly
Production API Keys Quarterly Annually
OAuth Refresh Tokens Automatic (after 90 days) Manual (after 180 days)
Service Account Keys Semi-annually Annually

Zero-Downtime Rotation Process

Rotasi kunci tanpa mengganggu layanan:

  1. Generate New Key — Buat kunci API baru melalui dashboard atau API
  2. Deploy New Key — Perbarui rahasia aplikasi di staging, uji secara menyeluruh
  3. Gradual Rollout — Deploy ke 10% server, pantau kesalahan
  4. Peluncuran Penuh — Terapkan ke server yang tersisa
  5. Verifikasi Lalu Lintas — Konfirmasi semua permintaan menggunakan kunci baru
  6. Nonaktifkan Kunci Lama — Tandai kunci lama sebagai tidak aktif tetapi jangan langsung hapus
  7. Hapus Kunci Lama — Setelah 48 jam tanpa error, hapus permanen

Rotasi Kunci Darurat

Jika Anda mencurigai kunci telah disusupi:

Rotasi Darurat
// Tindakan segera: Nonaktifkan kunci yang disusupi
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Buat kunci pengganti segera
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Kunci Pengganti Darurat"
}'

Rotasi Otomatis di Kubernetes

Gunakan Kubernetes Secrets dan operator untuk rotasi otomatis:

CronJob untuk Rotasi Kunci
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Mingguan setiap hari Minggu
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest

Autentikasi Multi-Faktor (MFA)

Untuk akun yang mengakses data produksi, MFA menyediakan lapisan keamanan tambahan dengan membutuhkan faktor kedua selain kredensial.

Metode MFA yang Didukung

  • TOTP (Time-based One-Time Password) — Aplikasi seperti Google Authenticator, Authy
  • WebAuthn/FIDO2 — Kunci keamanan hardware, biometrik
  • Kode One-Time SMS — Kurang aman tetapi didukung secara universal
  • Konfirmasi Email — Kode konfirmasi dikirim ke email terdaftar

Mengaktifkan TOTP untuk Akses Akun

Aktifkan MFA
// Langkah 1: Minta pengaturan MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// Respons mencakup URL kode QR
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}

MFA Selama Operasi API

Beberapa operasi mungkin memerlukan konfirmasi MFA bahkan setelah autentikasi:

Tantangan MFA
// Mencoba operasi sensitif (rotasi kunci)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Respons: MFA diperlukan
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Coba lagi dengan kode TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"

Praktik Keamanan Terbaik

Autentikasi hanya sekuat implementasinya. Ikuti praktik ini untuk menjaga keamanan:

Manajemen Rahasia

  • Jangan pernah menyimpan rahasia di version control — Gunakan file .env dengan .gitignore
  • Gunakan variabel lingkungan — Muat dari sistem manajemen rahasia yang aman
  • Pindai repositori — Gunakan alat seperti TruffleHog, detect-secrets untuk menemukan kunci yang terbuka
  • Audit log akses — Pantau siapa yang mengakses rahasia dan kapan

Keamanan Transportasi

  • Selalu gunakan HTTPS — Jangan pernah mengirim kredensial melalui koneksi tidak terenkripsi
  • Verifikasi sertifikat SSL — Jangan nonaktifkan validasi sertifikat di produksi
  • Gunakan certificate pinning — Untuk aplikasi mobile, cegah serangan MITM
  • Paksa TLS 1.2+ — Nonaktifkan protokol lama

Penanganan Kredensial

  • Hash rahasia — Simpan hash bcrypt atau Argon2, jangan teks biasa
  • Minimalkan masa aktif — Simpan kredensial di memori hanya selama diperlukan
  • Hapus data sensitif — Timpa kredensial secara eksplisit setelah digunakan
  • Gunakan library yang aman — Jangan mengimplementasikan kriptografi sendiri

Pencatatan dan Pemantauan

  • Jangan pernah mencatat kredensial — Redaksi kunci di log, gunakan masking log
  • Catat peristiwa autentikasi — Lacak upaya login yang berhasil dan gagal
  • Pantau anomali — Beri peringatan pada pola akses yang tidak biasa
  • Audit penggunaan kunci — Lacak kunci mana yang mengakses data apa

Pola Autentikasi Perusahaan

Organisasi besar sering membutuhkan kontrol keamanan tambahan dan kemampuan kepatuhan.

Integrasi SAML 2.0

Untuk pelanggan perusahaan, Smart Money API mendukung integrasi SAML 2.0 dengan penyedia identitas organisasi Anda (Okta, Azure AD, dll.):

  • Single Sign-On (SSO) — Pengguna melakukan autentikasi melalui IdP perusahaan Anda
  • Provisioning otomatis — Buat/nonaktifkan akun berdasarkan keanggotaan grup
  • Penegakan — Wajibkan SAML untuk semua akses pengguna

Whitelisting IP

Batasi akses API ke alamat IP atau rentang CIDR tertentu:

Manajemen Daftar Putih IP
// Tambahkan IP ke daftar putih
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Server produksi"
}'

Pencatatan Audit dan Kepatuhan

Paket enterprise mencakup log audit lengkap untuk kepatuhan:

Peristiwa Data yang Dicatat
Autentikasi Pengguna, timestamp, berhasil/gagal, IP, status MFA
Operasi Kunci ID Kunci, aksi, inisiator, timestamp
Perubahan Akun Apa yang berubah, siapa yang mengubah, timestamp, nilai sebelum/sesudah
Akses Data Pengguna, endpoint, cakupan, timestamp, jumlah rekaman

Pemecahan Masalah Autentikasi

Error Kunci API Tidak Valid

Masalah: Menerima "401 Unauthorized - Invalid API Key"

Solusi:

  • Verifikasi format kunci (harus dimulai dengan sk_test_ atau sk_live_)
  • Periksa spasi di awal/akhir kunci
  • Konfirmasi kunci belum dinonaktifkan atau dirotasi
  • Pastikan Anda menggunakan lingkungan yang benar (kunci test untuk test, live untuk produksi)
  • Periksa izin kunci API sesuai dengan persyaratan endpoint

Error Token Kedaluwarsa

Masalah: Token Bearer kedaluwarsa, permintaan gagal

Solusi:

  • Gunakan refresh token untuk mendapatkan access token baru
  • Terapkan pembaruan token otomatis 5 menit sebelum kedaluwarsa
  • Simpan refresh token dengan aman (bukan di localStorage untuk SPA)
  • Tanggapi 401 dengan mencoba alur refresh token

Error CORS/Preflight

Masalah: Browser memblokir permintaan dengan error CORS

Solusi:

  • Panggilan API dari browser harus berasal dari origin yang diizinkan
  • Tambahkan domain Anda melalui dashboard: Settings → CORS Origins
  • Browser mengirim permintaan preflight OPTIONS secara otomatis
  • Untuk pengembangan, gunakan localhost:3000 atau sejenisnya

Tantangan MFA Tidak Selesai

Masalah: Operasi yang memerlukan MFA gagal meskipun kode benar

Solusi:

  • Pastikan jam server disinkronkan (TOTP bergantung pada waktu)
  • Kode hanya valid selama 30 detik, buat yang baru
  • Gunakan kode cadangan jika aplikasi autentikator tidak tersedia
  • Pemulihan akun tersedia melalui email terdaftar

Terapkan Autentikasi Aman Hari Ini

Smart Money API mendukung autentikasi tingkat enterprise dengan OAuth 2.0, JWT, MFA, dan integrasi SAML. Amankan integrasi API Anda dengan praktik terbaik industri.

Lihat Paket Enterprise
Butuh SAML, daftar putih IP, atau dukungan khusus? Hubungi tim penjualan kami.

Sumber Daya Terkait

Panduan Autentikasi →

Memulai dengan autentikasi API

Praktik Keamanan Terbaik →

Panduan lengkap penguatan keamanan

Referensi Kode Error →

Memecahkan masalah error autentikasi
Mulai gratis — 100 panggilan/hari, tanpa kartu

Dapatkan aliran whale, funding, open interest, dan data on-chain dari 3 bursa dalam satu API. Tingkat gratis, tanpa kartu kredit, upgrade kapan saja.

Mulai gratis →
Coba konsol API langsung → (tidak perlu akun)