Dokumentasi API

Pola Pengesahan Lanjutan — OAuth 2.0, JWT, Putaran Kunci

Kuasaikan mekanisme pengesahan canggih untuk mengintegrasikan Smart Money API dalam persekitaran perusahaan. Pelajari aliran OAuth 2.0, pola token JWT, putaran kunci yang selamat, dan pelaksanaan pengesahan pelbagai faktor.

Diterbitkan pada 21 Mac 2026 • 18 minit baca • Lanjutan

Gambaran Keseluruhan Pengesahan

Smart Money API menyokong pelbagai kaedah pengesahan yang direka untuk menampung pelbagai seni bina aplikasi, keperluan keselamatan, dan polisi organisasi. Memahami pola ini memastikan integrasi anda selamat dan berprestasi tinggi.

Pengesahan dalam Smart Money API beroperasi di tiga lapisan utama:

  • Kunci API — Pengesahan token pembawa yang mudah untuk pembangunan dan integrasi yang mudah
  • Token JWT — Token tanpa keadaan yang ditandatangani secara kriptografi untuk sistem teragih dan mikropelayanan
  • OAuth 2.0 — Rangka kerja pengesahan yang didelegasikan untuk integrasi pihak ketiga dan aplikasi SaaS

Prinsip Keselamatan: Jangan dedahkan kredensial pengesahan dalam kod pelanggan, log, kawalan versi, atau mesej ralat. Laksanakan putaran kredensial mengikut jadual dan segera apabila dikompromi.

Setiap kaedah mempunyai kelebihan tersendiri. Kunci API berfungsi terbaik untuk komunikasi backend ke backend di mana penyimpanan kredensial dikawal. Token JWT cemerlang dalam seni bina teragih di mana tiada keadaan bersama tersedia. OAuth 2.0 menyediakan akses yang didelegasikan pengguna untuk aplikasi pihak ketiga.

Pengesahan Kunci API

Kunci API adalah mekanisme pengesahan yang paling mudah—ia adalah rentetan rawak yang dijana untuk akaun anda yang mengenal pasti aplikasi anda kepada Smart Money API. Setiap permintaan mesti termasuk kunci API anda sama ada sebagai header atau parameter pertanyaan.

Kunci API Berasaskan Header

Pendekatan yang disyorkan adalah menghantar kunci API anda dalam header Authorization menggunakan skema Bearer:

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

Parameter Pertanyaan Kunci API

Untuk sambungan WebSocket atau apabila header tidak boleh diubah, hantar kunci API sebagai parameter pertanyaan:

Sambungan WebSocket
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Menetapkan aliran WebSocket yang disahkan

Ciri-ciri Kunci API

Sifat Penerangan
Format Rentetan hex 128 aksara yang diawali dengan sk_test_ atau sk_live_
Skop Mewarisi semua kebenaran akaun yang menciptanya
Tamat Tempoh Tidak pernah tamat secara automatik; mesti diputar secara manual
Putaran Hasilkan kunci baru, migrasikan trafik, kemudian nyahaktifkan kunci lama
Had Kadar Dikongsi di semua permintaan menggunakan kunci yang sama

Amalan Keselamatan Kunci API

  • Pembolehubah Persekitaran — Simpan kunci dalam fail .env (tidak diserahkan ke kawalan versi) dan muat pada masa jalan
  • Sistem Vault — Gunakan HashiCorp Vault, AWS Secrets Manager, atau Azure Key Vault dalam pengeluaran
  • Kunci Berasingan — Mengekalkan kunci ujian dan kunci hidup yang berasingan; putar kunci ujian dengan kerap
  • Skop Minimal — Cipta kunci berasingan untuk integrasi yang berbeza apabila mungkin
  • Log Audit — Log semua acara penciptaan dan penggunaan kunci API
Dapatkan kunci API anda dalam 30 saat

Sedia untuk membina? Dapatkan kunci API percuma (100 panggilan/hari, tiada kad) dan mulakan menarik data paus, pembiayaan dan on-chain secara langsung.

Dapatkan kunci API anda →

Pola Token Pembawa

Token pembawa melanjutkan konsep kunci API yang mudah dengan menambah konteks, tamat tempoh, dan mekanisme penyegaran. Ia sesuai untuk aplikasi yang memerlukan pengurusan kredensial secara programatik.

Mendapatkan Token Pembawa

Tukar kunci API dan rahsia anda untuk token pembawa yang sah 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 token pembawa dengan metadata:

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

Menggunakan Token Pembawa

Sertakan token dalam header Authorization untuk semua permintaan berikutnya:

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

Aliran Penyegaran Token

Apabila token hampir tamat tempoh, gunakan token penyegaran untuk mendapatkan yang baru tanpa memerlukan rahsia 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..."
}'

Pelaksanaan OAuth 2.0

OAuth 2.0 membolehkan pengguna memberikan aplikasi akses kepada akaun Smart Money API mereka tanpa berkongsi kredensial. Ini penting untuk platform SaaS, integrasi pihak ketiga, dan aplikasi multi-penyewa.

Aliran Kod Pengesahan OAuth 2.0

Aliran standard untuk aplikasi web:

  1. Pengguna Memulakan Log Masuk — Pengguna klik "Sambung dengan Smart Money API"
  2. Alihkan ke Pelayan Pengesahan — Aplikasi anda mengalihkan pengguna ke endpoint pengesahan Smart Money
  3. Pengguna Memberi Kebenaran — Pengguna mengkaji skop yang diminta dan memberikan akses
  4. Kod Pengesahan Dikembalikan — Pengguna dialihkan kembali dengan kod pengesahan
  5. Tukar Kod untuk Token — Backend menukar kod untuk token akses (kod tidak pernah didedahkan ke frontend)
  6. Simpan Token — Simpan token penyegaran dengan selamat; gunakan token akses untuk panggilan API

Langkah 1: Arahkan Pengguna ke Titik Akhir Otorisasi

Pengalihan Frontend
// URL untuk mengalihkan 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: Urus Panggilan Balik dan Tukar Kod

Pertukaran Kod Backend
// Backend mengendalikan laluan /callback
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// Sahkan parameter state
if (storedState !== receivedState) {
throw new Error('State mismatch - serangan CSRF dikesan');
}
// Tukar kod 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 selamat

Skop OAuth

Minta hanya skop yang diperlukan oleh aplikasi anda. Smart Money API menentukan skop berikut:

Skop Penerangan
whales Akses penjejakan dompet ikan paus dan metrik pengumpulan
derivatives Akses data niaga hadapan, perpetual dan kadar pembiayaan
onchain Akses aliran transaksi dan analitik on-chain
alerts Buat dan urus amaran webhook
offline Akses token penyegaran untuk mendapatkan token akses baru secara luar talian

Pengurusan Token JWT

JWT (JSON Web Tokens) menyediakan pengesahan tanpa keadaan—pelayan tidak perlu menyimpan data sesi. Smart Money API menggunakan RS256 (Tandatangan RSA dengan SHA-256) untuk menandatangani token, membenarkan pengesahan tanpa menghubungi API.

Struktur JWT

Token JWT terdiri daripada tiga bahagian yang dipisahkan oleh titik:

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

Header JWT

Header mengenal pasti algoritma dan jenis token:

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

Tuntutan Payload JWT

Payload mengandungi tuntutan (pernyataan tentang pengguna/aplikasi):

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

Mengesahkan Tandatangan JWT

Muat turun kunci awam Smart Money dan sahkan token sebelum menerimanya:

Pengesahan Node.js
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Dapatkan kunci awam dari Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// Sahkan token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Token sah, gunakan tuntutan yang dikodkan
} catch (err) {
// Token tidak sah atau tamat tempoh
}

Strategi Putaran Kunci

Putaran kunci berkala adalah penting untuk mengekalkan keselamatan. Walaupun dengan amalan keselamatan yang sempurna, anggap kunci boleh dikompromi dan laksanakan putaran sistematik.

Kekerapan Putaran

Smart Money mengesyorkan jadual putaran yang berbeza berdasarkan jenis kunci dan penggunaan:

Jenis Kunci Putaran Disyorkan Putaran Minimum
Kunci API Ujian Bulanan Suku Tahunan
Kunci API Pengeluaran Suku Tahunan Tahunan
Token Penyegaran OAuth Automatik (selepas 90 hari) Manual (selepas 180 hari)
Kunci Akaun Perkhidmatan Setiap setengah tahun Tahunan

Proses Putaran Tanpa Masa Henti

Putar kunci tanpa mengganggu perkhidmatan:

  1. Hasilkan Kunci Baru — Buat kunci API baru melalui papan pemuka atau API
  2. Laksanakan Kunci Baru — Kemas kini rahsia aplikasi dalam staging, uji dengan teliti
  3. Pelancaran Berperingkat — Laksanakan ke 10% pelayan, pantau untuk ralat
  4. Pelancaran Penuh — Menyebar ke pelayan yang tinggal
  5. Sahkan Trafik — Sahkan semua permintaan menggunakan kunci baru
  6. Nyahaktifkan Kunci Lama — Tandakan kunci lama sebagai tidak aktif tetapi jangan padam serta-merta
  7. Padam Kunci Lama — Selepas 48 jam tanpa ralat, padam secara kekal

Putaran Kunci Kecemasan

Jika anda mengesyaki kunci telah dikompromi:

Putaran Kecemasan
// Tindakan segera: Nyahaktifkan kunci yang dikompromi
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Hasilkan kunci pengganti serta-merta
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Kunci Pengganti Kecemasan"
}'

Putaran Automatik dalam Kubernetes

Gunakan Kubernetes Secrets dan operator untuk putaran automatik:

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

Pengesahan Dua Faktor (MFA)

Untuk akaun yang mengakses data pengeluaran, MFA menyediakan lapisan keselamatan tambahan dengan memerlukan faktor kedua selain daripada kelayakan sahaja.

Kaedah MFA yang Disokong

  • TOTP (Kata Laluan Sekali Masa Berasaskan Masa) — Aplikasi seperti Google Authenticator, Authy
  • WebAuthn/FIDO2 — Kunci keselamatan perkakasan, biometrik
  • Kod Sekali Masa SMS — Kurang selamat tetapi disokong secara universal
  • Pengesahan Emel — Kod pengesahan dihantar ke emel berdaftar

Mengaktifkan TOTP untuk Akses Akaun

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

MFA Semasa Operasi API

Sesetengah operasi mungkin memerlukan pengesahan MFA walaupun selepas pengesahan:

Cabaran MFA
// Mencuba operasi sensitif (putaran 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"
}
// Cuba semula dengan kod TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"

Amalan Keselamatan Terbaik

Pengesahan hanya sekuat pelaksanaannya. Ikuti amalan ini untuk mengekalkan keselamatan:

Pengurusan Rahsia

  • Jangan sekali-kali menyimpan rahsia dalam kawalan versi — Gunakan fail .env dengan .gitignore
  • Gunakan pembolehubah persekitaran — Muat dari sistem pengurusan rahsia yang selamat
  • Imbas repositori — Gunakan alat seperti TruffleHog, detect-secrets untuk mencari kunci yang terdedah
  • Audit log akses — Pantau siapa yang mengakses rahsia dan bila

Keselamatan Pengangkutan

  • Sentiasa gunakan HTTPS — Jangan sekali-kali menghantar kelayakan melalui sambungan tidak disulitkan
  • Sahkan sijil SSL — Jangan lumpuhkan pengesahan sijil dalam pengeluaran
  • Gunakan penyemat sijil — Untuk aplikasi mudah alih, elakkan serangan MITM
  • Laksanakan TLS 1.2+ — Lumpuhkan protokol lama

Pengendalian Kelayakan

  • Hash rahsia — Simpan hash bcrypt atau Argon2, jangan teks biasa
  • Minimakan jangka hayat — Simpan kelayakan dalam ingatan hanya seberapa yang diperlukan
  • Kosongkan data sensitif — Tulis semula kelayakan secara eksplisit selepas digunakan
  • Gunakan pustaka selamat — Jangan laksanakan kriptografi sendiri

Pembalakan dan Pemantauan

  • Jangan sekali-kali log kelayakan — Redaksi kunci dalam log, gunakan penutup log
  • Log peristiwa pengesahan — Jejaki percubaan log masuk yang berjaya dan gagal
  • Pantau untuk anomali — Amaran pada corak akses yang luar biasa
  • Audit penggunaan kunci — Jejaki kunci mana yang mengakses data apa

Corak Pengesahan Enterprise

Organisasi besar sering memerlukan kawalan keselamatan tambahan dan keupayaan pematuhan.

Integrasi SAML 2.0

Untuk pelanggan enterprise, Smart Money API menyokong integrasi SAML 2.0 dengan pembekal identiti organisasi anda (Okta, Azure AD, dll.):

  • Log Masuk Tunggal (SSO) — Pengguna disahkan melalui IdP korporat anda
  • Peruntukan automatik — Cipta/lumpuhkan akaun berdasarkan keahlian kumpulan
  • Penguatkuasaan — Perlukan SAML untuk semua akses pengguna

Senarai Putih IP

Sekat akses API kepada alamat IP atau julat CIDR tertentu:

Pengurusan Senarai Putih IP
// Tambah IP ke senarai putih
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Pelayan Pengeluaran"
}'

Log Audit dan Pematuhan

Pelan perusahaan termasuk log audit komprehensif untuk pematuhan:

Peristiwa Data yang Dicatat
Pengesahan Pengguna, cap masa, berjaya/gagal, IP, status MFA
Operasi Kunci ID Kunci, tindakan, pemula, cap masa
Perubahan Akaun Apa yang berubah, siapa yang mengubahnya, cap masa, nilai sebelum/selepas
Akses Data Pengguna, endpoint, skop, cap masa, bilangan rekod

Menyelesaikan Masalah Pengesahan

Ralat Kunci API Tidak Sah

Masalah: Menerima "401 Tidak Sah - Kunci API Tidak Sah"

Penyelesaian:

  • Sahkan format kunci (harus bermula dengan sk_test_ atau sk_live_)
  • Periksa ruang kosong di awal/akhir kunci
  • Pastikan kunci belum dinyahaktifkan atau diputar
  • Sahkan anda menggunakan persekitaran yang betul (kunci ujian untuk ujian, kunci hidup untuk pengeluaran)
  • Periksa kebenaran kunci API sesuai dengan keperluan endpoint

Ralat Token Tamat Tempoh

Masalah: Token pembawa tamat tempoh, permintaan gagal

Penyelesaian:

  • Gunakan token penyegaran untuk mendapatkan token akses baru
  • Laksanakan penyegaran token automatik 5 minit sebelum tamat tempoh
  • Simpan token penyegaran dengan selamat (bukan dalam localStorage untuk SPA)
  • Urus respons 401 dengan mencuba aliran penyegaran token

Ralat CORS/Pra-penerbangan

Masalah: Penyekat permintaan pelayar dengan ralat CORS

Penyelesaian:

  • Panggilan API dari pelayar mesti datang dari asal yang dibenarkan
  • Tambahkan domain anda melalui dashboard: Tetapan → Asal CORS
  • Pelayan menghantar permintaan pra-penerbangan OPTIONS secara automatik
  • Untuk pembangunan, gunakan localhost:3000 atau yang serupa

Cabaran MFA Tidak Selesai

Masalah: Operasi yang memerlukan MFA gagal walaupun dengan kod yang betul

Penyelesaian:

  • Pastikan jam pelayan disegerakkan (TOTP bergantung pada masa)
  • Kod hanya sah selama 30 saat, hasilkan yang baru
  • Gunakan kod sandaran jika aplikasi pengesah tidak tersedia
  • Pemulihan akaun tersedia melalui e-mel yang didaftarkan

Laksanakan Pengesahan Selamat Hari Ini

Smart Money API menyokong pengesahan gred perusahaan dengan OAuth 2.0, JWT, MFA, dan integrasi SAML. Selamatkan integrasi API anda dengan amalan terbaik industri.

Lihat Pelan Perusahaan
Perlukan SAML, senarai putih IP, atau sokongan berdedikasi? Hubungi pasukan jualan kami.

Sumber Berkaitan

Panduan Pengesahan →

Memulakan pengesahan API

Amalan Keselamatan Terbaik →

Panduan pengukuhan keselamatan komprehensif

Rujukan Kod Ralat →

Menyelesaikan ralat pengesahan
Mulakan percuma — 100 panggilan/hari, tiada kad

Dapatkan aliran ikan paus, pembiayaan, minat terbuka dan data on-chain merentasi 3 pertukaran dari satu API. Tahap percuma, tiada kad kredit, naik taraf bila-bila masa.

Mulakan percuma →
Cuba konsol API langsung → (tiada akaun diperlukan)