Dokumentasyon ng API
Mga Advanced na Pattern sa Pagpapatotoo — OAuth 2.0, JWT, Key Rotation
Master ang sopistikadong mekanismo ng pagpapatotoo para sa pagsasama ng Smart Money API sa mga enterprise environment. Alamin ang mga daloy ng OAuth 2.0, pattern ng JWT token, secure na key rotation, at pagpapatupad ng multi-factor authentication.
Na-publish noong Marso 21, 2026
•
18 minutong pagbasa
•
Advanced
Pangkalahatang-ideya sa Pagpapatotoo
Ang Smart Money API ay sumusuporta sa maraming pamamaraan ng pagpapatotoo na idinisenyo upang akma sa iba't ibang arkitektura ng aplikasyon, mga kinakailangan sa seguridad, at mga patakaran ng organisasyon. Ang pag-unawa sa mga pattern na ito ay tinitiyak na ang iyong pagsasama ay parehong secure at mahusay.
Ang pagpapatotoo sa Smart Money API ay gumagana sa tatlong pangunahing layer:
- Mga API Key — Simpleng bearer token authentication para sa pag-unlad at tuwirang pagsasama
- Mga JWT Token — Mga stateless, cryptographically signed token para sa mga distributed system at microservices
- OAuth 2.0 — Delegated authorization framework para sa mga third-party integration at SaaS application
Prinsipyo ng Seguridad: Huwag kailanman ilantad ang mga kredensyal sa pagpapatotoo sa client-side code, log, version control, o mga mensahe ng error. Magpatupad ng credential rotation sa isang iskedyul at agad-agad kapag nakompromiso.
Ang bawat pamamaraan ay may natatanging mga pakinabang. Ang mga API key ay pinakamahusay para sa backend-to-backend communication kung saan kontrolado ang pag-iimbak ng kredensyal. Ang mga JWT token ay mahusay sa mga distributed architecture kung saan walang magagamit na shared state. Ang OAuth 2.0 ay nagbibigay ng user-delegated access para sa mga third-party application.
Pagpapatotoo sa API Key
Ang mga API key ay ang pinakasimpleng mekanismo ng pagpapatotoo—sila ay mga random na string na nabuo para sa iyong account na nagpapakilala sa iyong application sa Smart Money API. Ang bawat kahilingan ay dapat magsama ng iyong API key bilang isang header o query parameter.
Header-Based API Key
Ang inirerekomendang pamamaraan ay ang pagpasa ng iyong API key sa Authorization header gamit ang Bearer scheme:
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
Query Parameter API Key
Para sa mga WebSocket connection o kapag hindi mababago ang mga header, ipasa ang API key bilang isang query parameter:
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// Nagtatag ng authenticated WebSocket stream
Mga Katangian ng API Key
| Property |
Paglalarawan |
| Format |
128-character hex string na may prefix na sk_test_ o sk_live_ |
| Scope |
Inherits all permissions of the account that created it |
| Expiration |
Hindi kailanman awtomatikong mag-expire; dapat i-rotate nang manu-mano |
| Rotation |
Gumawa ng bagong key, ilipat ang trapiko, pagkatapos ay i-deactivate ang lumang key |
| Rate Limits |
Shared across all requests using the same key |
Mga Praktis sa Seguridad ng API Key
- Environment Variables — Mag-imbak ng mga key sa .env file (hindi nakommit sa version control) at i-load sa runtime
- Vault Systems — Gumamit ng HashiCorp Vault, AWS Secrets Manager, o Azure Key Vault sa produksyon
- Separate Keys — Panatilihin ang magkahiwalay na test at live key; i-rotate ang mga test key nang madalas
- Minimal Scope — Gumawa ng magkahiwalay na key para sa iba't ibang integration kung posible
- Audit Logging — I-log ang lahat ng paglikha at paggamit ng API key
Kunin ang iyong API key sa loob ng 30 segundo
Handa nang magtayo? Kumuha ng libreng API key (100 tawag/araw, walang card) at simulang kunin ang live na whale, funding at on-chain data.
Kunin ang iyong API key →Pattern ng Bearer Token
Ang mga bearer token ay nagpapalawak sa simpleng konsepto ng API key sa pamamagitan ng pagdaragdag ng konteksto, expiration, at refresh mechanism. Sila ay mainam para sa mga aplikasyon na nangangailangan ng programmatic credential management.
Pagkuha ng Bearer Tokens
Ipalit ang iyong API key at secret para sa isang bearer token na may bisa sa 24 na oras:
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 ng Token Response
Ang endpoint ay nagbabalik ng bearer token na may metadata:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
Paggamit ng Bearer Tokens
Isama ang token sa Authorization header para sa lahat ng kasunod na kahilingan:
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
Token Refresh Flow
Kapag malapit nang mag-expire ang isang token, gamitin ang refresh token upang makakuha ng bago nang hindi nangangailangan ng iyong API secret:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
Pagpapatupad ng OAuth 2.0
Ang OAuth 2.0 ay nagbibigay-daan sa mga user na magbigay ng access sa mga aplikasyon sa kanilang Smart Money API account nang hindi ibinabahagi ang mga kredensyal. Ito ay mahalaga para sa mga SaaS platform, third-party integration, at multi-tenant application.
OAuth 2.0 Authorization Code Flow
Ang standard flow para sa web application:
- User Initiates Login — Ang user ay nag-click ng "Connect with Smart Money API"
- Redirect to Authorization Server — Ang iyong app ay nag-redirect sa user sa authorization endpoint ng Smart Money
- User Grants Permission — Sinusuri ng user ang hiniling na mga scope at nagbibigay ng access
- Authorization Code Returned — Ang user ay na-redirect pabalik kasama ang authorization code
- Exchange Code for Token — Ang backend ay nagpapalit ng code para sa access token (hindi kailanman ilalantad ang code sa frontend)
- Mag-imbak ng Token — I-imbak nang ligtas ang refresh token; gamitin ang access token para sa mga tawag sa API
Hakbang 1: I-redirect ang User sa Authorization Endpoint
// URL para i-redirect ang user
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();
Hakbang 2: I-handle ang Callback at I-exchange ang Code
// Backend ang humahawak sa /callback route
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// I-verify ang state parameter
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// I-exchange ang code para sa 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();
// I-imbak nang ligtas ang mga token
OAuth Scopes
Humiling lamang ng mga scope na kailangan ng iyong aplikasyon. Ang Smart Money API ay nagtatakda ng mga sumusunod na scope:
| Scope |
Description |
| whales |
Access sa whale wallet tracking at accumulation metrics |
| derivatives |
Access sa futures, perpetuals, at funding rate data |
| onchain |
Access sa on-chain transaction flows at analytics |
| alerts |
Gumawa at pamahalaan ang mga webhook alerts |
| offline |
Access sa refresh tokens para makakuha ng mga bagong access token offline |
JWT Token Management
Ang JWT (JSON Web Tokens) ay nagbibigay ng stateless authentication—hindi kailangang mag-imbak ng session data ang server. Gumagamit ang Smart Money API ng RS256 (RSA Signature with SHA-256) para sa pag-sign ng token, na nagpapahintulot ng verification nang hindi kinakailangang makipag-ugnayan sa API.
JWT Structure
Ang mga JWT token ay binubuo ng tatlong bahagi na pinaghihiwalay ng tuldok:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE
JWT Header
Ang header ay nagpapakilala sa algorithm at uri ng token:
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
JWT Payload Claims
Ang payload ay naglalaman ng mga claims (mga pahayag tungkol sa user/app):
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
Verifying JWT Signatures
I-download ang public key ng Smart Money at i-verify ang mga token bago tanggapin ang mga ito:
const jwt = require('jsonwebtoken');
const fs = require('fs');
// Kunin ang public key mula sa Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// I-verify ang token
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// Valid ang token, gamitin ang decoded claims
} catch (err) {
// Hindi valid o expired ang token
}
Key Rotation Strategy
Ang regular na key rotation ay kritikal para mapanatili ang seguridad. Kahit na may perpektong mga kasanayan sa seguridad, ipagpalagay na maaaring ma-compromise ang mga key at ipatupad ang sistematikong rotation.
Rotation Frequency
Iminumungkahi ng Smart Money ang iba't ibang iskedyul ng rotation batay sa uri at paggamit ng key:
| 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
I-rotate ang mga key nang hindi naaabala ang serbisyo:
- Generate New Key — Gumawa ng bagong API key sa pamamagitan ng dashboard o API
- Deploy New Key — I-update ang mga application secrets sa staging, i-test nang mabuti
- Gradual Rollout — I-deploy sa 10% ng mga server, subaybayan ang mga error
- Buong Paglulunsad — I-deploy sa natitirang mga server
- Patunayan ang Trapiko — Kumpirmahin na lahat ng request ay gumagamit ng bagong key
- I-deactivate ang Lumang Key — Markahan ang lumang key bilang inactive ngunit huwag agad burahin
- Burahin ang Lumang Key — Pagkatapos ng 48 oras na walang error, permanenteng burahin
Emergency Key Rotation
Kung pinaghihinalaan mong na-compromise ang isang key:
// Agad na aksyon: I-deactivate ang compromised key
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// Gumawa ng kapalit na key agad
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "Emergency Replacement Key"
}'
Automated Rotation in Kubernetes
Gamitin ang Kubernetes Secrets at operators para sa automatic rotation:
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # Linggo-linggo tuwing Sunday
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
Multi-Factor Authentication (MFA)
Para sa mga account na uma-access sa production data, nagbibigay ang MFA ng karagdagang security layer sa pamamagitan ng pangangailangan ng pangalawang factor bukod sa credentials lamang.
MFA Methods Supported
- TOTP (Time-based One-Time Password) — Mga app tulad ng Google Authenticator, Authy
- WebAuthn/FIDO2 — Hardware security keys, biometrics
- SMS One-Time Codes — Hindi gaanong secure ngunit laganap ang suporta
- Email Confirmation — Mga confirmation code na ipinadala sa registered email
Enabling TOTP for Account Access
// Step 1: Request MFA setup
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// Response includes QR code URL
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA During API Operations
Ang ilang operasyon ay maaaring mangailangan ng MFA confirmation kahit na pagkatapos ng authentication:
// Pagtatangka ng sensitive operation (key rotation)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// Response: MFA required
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// Subukang muli gamit ang TOTP code
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
Security Best Practices
Ang authentication ay kasing-tibay lang ng implementasyon nito. Sundin ang mga practices na ito para mapanatili ang security:
Secrets Management
- Huwag kailanman i-commit ang mga secrets sa version control — Gumamit ng .env files na may .gitignore
- Gumamit ng environment variables — I-load mula sa secure na secret management systems
- I-scan ang mga repository — Gumamit ng mga tool tulad ng TruffleHog, detect-secrets para makita ang exposed keys
- Audit access logs — Subaybayan kung sino ang um-access sa mga secrets at kailan
Transport Security
- Laging gumamit ng HTTPS — Huwag kailanman magpadala ng credentials sa unencrypted connections
- I-verify ang SSL certificates — Huwag i-disable ang certificate validation sa production
- Gumamit ng certificate pinning — Para sa mobile apps, pigilan ang MITM attacks
- I-enforce ang TLS 1.2+ — I-disable ang mga lumang protocol
Credential Handling
- I-hash ang mga secrets — Mag-store ng bcrypt o Argon2 hashes, huwag kailanman plaintext
- Paiikliin ang lifetime — Panatilihin ang credentials sa memorya lamang habang kailangan
- I-clear ang sensitive data — Tahasang i-overwrite ang credentials pagkatapos gamitin
- Gumamit ng secure libraries — Huwag ipatupad ang cryptography nang mag-isa
Logging and Monitoring
- Huwag kailanman mag-log ng credentials — I-redact ang mga key sa logs, gumamit ng log masking
- Mag-log ng authentication events — Subaybayan ang successful at failed login attempts
- Mag-monitor para sa anomalies — Alert sa hindi pangkaraniwang access patterns
- Audit key usage — Subaybayan kung aling keys ang um-access sa anong data
Enterprise Authentication Patterns
Ang malalaking organisasyon ay madalas na nangangailangan ng karagdagang security controls at compliance capabilities.
SAML 2.0 Integration
Para sa enterprise customers, sinusuportahan ng Smart Money API ang SAML 2.0 integration sa iyong organization's identity provider (Okta, Azure AD, etc.):
- Single Sign-On (SSO) — Ang mga user ay nag-a-authenticate sa pamamagitan ng iyong corporate IdP
- Automatic provisioning — Gumawa/mag-disable ng mga account batay sa group membership
- Enforcement — Pilitin ang SAML para sa lahat ng user access
IP Whitelisting
I-restrict ang access sa API sa mga partikular na IP address o CIDR ranges:
// Magdagdag ng IP sa whitelist
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "Production servers"
}'
Audit Logging at Compliance
Kasama sa mga enterprise plan ang komprehensibong audit logs para sa compliance:
| Event |
Naka-log na Data |
| Authentication |
User, timestamp, success/failure, IP, MFA status |
| Key Operations |
Key ID, action, initiator, timestamp |
| Account Changes |
Ano ang nabago, sino ang nagbago, timestamp, before/after values |
| Data Access |
User, endpoint, scopes, timestamp, record count |
Pagtroubleshoot sa mga Isyu sa Authentication
Invalid API Key Error
Problema: Natatanggap ang "401 Unauthorized - Invalid API Key"
Mga Solusyon:
- I-verify ang format ng key (dapat nagsisimula sa sk_test_ o sk_live_)
- Suriin kung may trailing/leading whitespace sa key
- Kumpirmahing hindi na-deactivate o na-rotate ang key
- I-verify na ginagamit ang tamang environment (test key para sa test, live para sa production)
- Tiyaking tumutugma ang mga permission ng API key sa mga kinakailangan ng endpoint
Token Expired Error
Problema: Nag-expire na ang Bearer token, nabibigo ang mga request
Mga Solusyon:
- Gamitin ang refresh token para makakuha ng bagong access token
- Magpatupad ng automatic token refresh 5 minuto bago mag-expire
- Itago nang ligtas ang refresh token (hindi sa localStorage para sa SPAs)
- I-handle ang mga 401 response sa pamamagitan ng pagsubok sa refresh token flow
CORS/Preflight Errors
Problema: Hinaharang ng browser ang mga request na may CORS error
Mga Solusyon:
- Ang mga API call mula sa browser ay dapat manggaling sa mga whitelisted origin
- Idagdag ang iyong domain sa pamamagitan ng dashboard: Settings → CORS Origins
- Ang browser ay awtomatikong nagpapadala ng OPTIONS preflight request
- Para sa development, gamitin ang localhost:3000 o katulad
MFA Challenge Not Completing
Problema: Nabibigo ang mga operasyon na nangangailangan ng MFA kahit tama ang code
Mga Solusyon:
- Siguraduhing naka-synchronize ang oras ng server (umaasa sa oras ang TOTP)
- Valid lamang ang code sa loob ng 30 segundo, gumawa ng bago
- Gumamit ng backup codes kung hindi available ang authenticator app
- Available ang account recovery sa pamamagitan ng registered email
Ipatupad ang Secure Authentication Ngayon
Sinusuportahan ng Smart Money API ang enterprise-grade authentication na may OAuth 2.0, JWT, MFA, at SAML integration. Protektahan ang iyong API integration gamit ang mga industry best practices.
Tingnan ang mga Enterprise Plan
Kailangan ng SAML, IP whitelisting, o dedicated support? Makipag-ugnayan sa aming sales team.