مستندات API
الگوهای پیشرفته احراز هویت — OAuth 2.0، JWT، چرخش کلید
تسلط بر مکانیزمهای پیچیده احراز هویت برای ادغام Smart Money API در محیطهای سازمانی. یادگیری جریانهای OAuth 2.0، الگوهای توکن JWT، چرخش ایمن کلید و پیادهسازی احراز هویت چندعاملی.
منتشر شده در ۲۱ مارس ۲۰۲۶
•
۱۸ دقیقه مطالعه
•
پیشرفته
مرور احراز هویت
Smart Money API از چندین روش احراز هویت پشتیبانی میکند که برای تطابق با معماریهای مختلف برنامه، نیازمندیهای امنیتی و سیاستهای سازمانی طراحی شدهاند. درک این الگوها تضمین میکند که ادغام شما هم ایمن و هم کارآمد است.
احراز هویت در Smart Money API در سه لایه اصلی عمل میکند:
- کلیدهای API — احراز هویت ساده با توکن Bearer برای توسعه و ادغامهای مستقیم
- توکنهای JWT — توکنهای بدون حالت و امضا شده رمزنگاری برای سیستمهای توزیعشده و میکروسرویسها
- OAuth 2.0 — چارچوب مجوزدهی تفویضشده برای ادغامهای شخص ثالث و برنامههای SaaS
اصل امنیتی: هرگز اطلاعات احراز هویت را در کد سمت کلاینت، لاگها، کنترل نسخه یا پیامهای خطا قرار ندهید. چرخش اعتبار را بر اساس برنامه و بلافاصله پس از نقض امنیتی پیادهسازی کنید.
هر روش مزایای متمایزی دارد. کلیدهای API برای ارتباط backend-to-backend که ذخیره اعتبار تحت کنترل است، بهترین کارایی را دارند. توکنهای JWT در معماریهای توزیعشده که حالت اشتراکی وجود ندارد، عالی عمل میکنند. OAuth 2.0 دسترسی تفویضشده کاربر را برای برنامههای شخص ثالث فراهم میکند.
احراز هویت با کلید API
کلیدهای API سادهترین مکانیزم احراز هویت هستند—آنها رشتههای تصادفی هستند که برای حساب شما تولید میشوند و برنامه شما را به Smart Money API معرفی میکنند. هر درخواست باید شامل کلید API شما باشد، چه در هدر و چه در پارامتر کوئری.
کلید API مبتنی بر هدر
روش توصیهشده، ارسال کلید API در هدر Authorization با استفاده از طرح Bearer است:
curl -X GET "https://api.smartmoneyapi.com/v1/whales/btc" \
-H "Authorization: Bearer sk_live_1234567890abcdef" \
-H "Accept: application/json"
کلید API به عنوان پارامتر کوئری
برای اتصالات WebSocket یا زمانی که هدرها قابل تغییر نیستند، کلید API را به عنوان پارامتر کوئری ارسال کنید:
ws://localhost:8877/ws?api_key=sk_live_1234567890abcdef
// جریان WebSocket احراز هویت شده را برقرار میکند
ویژگیهای کلید API
| ویژگی |
توضیح |
| فرمت |
رشته hex ۱۲۸ کاراکتری با پیشوند sk_test_ یا sk_live_ |
| حوزه |
تمام مجوزهای حساب ایجادکننده را به ارث میبرد |
| انقضا |
بهصورت خودکار منقضی نمیشود؛ باید بهصورت دستی چرخش یابد |
| چرخش |
کلید جدید ایجاد کنید، ترافیک را انتقال دهید، سپس کلید قدیمی را غیرفعال کنید |
| محدودیت نرخ |
بین تمام درخواستهایی که از همان کلید استفاده میکنند، مشترک است |
روشهای امنیتی کلید API
- متغیرهای محیطی — کلیدها را در فایلهای .env ذخیره کنید (در کنترل نسخه commit نشود) و در زمان اجرا بارگیری کنید
- سیستمهای مخزن — در محیط تولید از HashiCorp Vault، AWS Secrets Manager یا Azure Key Vault استفاده کنید
- کلیدهای جداگانه — کلیدهای تست و عملیاتی جداگانه نگه دارید؛ کلیدهای تست را بهطور مکرر چرخش دهید
- حوزه حداقلی — در صورت امکان، کلیدهای جداگانه برای ادغامهای مختلف ایجاد کنید
- ثبت وقایع حسابرسی — تمام رویدادهای ایجاد و استفاده از کلید API را ثبت کنید
کلید API خود را در ۳۰ ثانیه دریافت کنید
آماده ساخت هستید؟ یک کلید API رایگان دریافت کنید (۵۰ درخواست در روز، بدون نیاز به کارت) و شروع به دریافت دادههای زنده نهنگها، تأمین مالی و زنجیرهای کنید.
دریافت کلید API →
الگوی توکن Bearer
توکنهای Bearer مفهوم ساده کلید API را با افزودن زمینه، انقضا و مکانیزمهای تمدید گسترش میدهند. آنها برای برنامههایی که نیاز به مدیریت اعتبار برنامهنویسی دارند، ایدهآل هستند.
دریافت توکنهای Bearer
کلید API و رمز خود را با یک توکن Bearer معتبر برای ۲۴ ساعت تعویض کنید:
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"
}'
فرمت پاسخ توکن
این نقطه پایانی یک توکن Bearer با ابرداده برمیگرداند:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "refresh_1234567..."
}
استفاده از توکنهای Bearer
توکن را در هدر Authorization برای تمام درخواستهای بعدی قرار دهید:
curl -X GET "https://api.smartmoneyapi.com/v1/derivatives/funding-heatmap" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
جریان تمدید توکن
زمانی که توکن نزدیک به انقضا است، از توکن تمدید برای دریافت توکن جدید بدون نیاز به رمز API استفاده کنید:
curl -X POST "https://api.smartmoneyapi.com/v1/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "refresh_1234567..."
}'
پیادهسازی OAuth 2.0
OAuth 2.0 به کاربران اجازه میدهد تا به برنامهها دسترسی به حسابهای Smart Money API خود را بدون اشتراکگذاری اعتبارها اعطا کنند. این برای پلتفرمهای SaaS، ادغامهای شخص ثالث و برنامههای چندمستاجری ضروری است.
جریان کد مجوز OAuth 2.0
جریان استاندارد برای برنامههای وب:
- کارگر ورود را آغاز میکند — کاربر روی "اتصال با Smart Money API" کلیک میکند
- تغییر مسیر به سرور مجوز — برنامه شما کاربر را به نقطه پایانی مجوز Smart Money تغییر مسیر میدهد
- کارگر مجوز میدهد — کاربر محدودههای درخواستشده را بررسی و دسترسی را اعطا میکند
- کد مجوز برگردانده میشود — کاربر با کد مجوز به عقب تغییر مسیر داده میشود
- تبدیل کد به توکن — backend کد را با توکن دسترسی تعویض میکند (کد هرگز در frontend نمایش داده نمیشود)
- ذخیره توکن — توکن رفرش را به صورت امن ذخیره کنید؛ از توکن دسترسی برای فراخوانیهای API استفاده کنید
مرحله ۱: هدایت کاربر به نقطه پایان احراز هویت
// آدرس برای هدایت کاربر
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();
مرحله ۲: مدیریت پاسخ و تبادل کد
// بکاند مسیر /callback را مدیریت میکند
const code = req.query.code;
const storedState = req.session.state;
const receivedState = req.query.state;
// بررسی پارامتر state
if (storedState !== receivedState) {
throw new Error('State mismatch - CSRF attack detected');
}
// تبادل کد برای توکن
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();
// ذخیره امن توکنها
حوزههای OAuth
فقط حوزههایی که برنامه شما نیاز دارد را درخواست کنید. Smart Money API این حوزهها را تعریف میکند:
| حوزه |
توضیح |
| whales |
دسترسی به ردیابی کیفپول نهنگها و معیارهای تجمیع |
| derivatives |
دسترسی به دادههای فیوچرز، پرپچوالها و نرخ تأمین مالی |
| onchain |
دسترسی به جریانهای تراکنش و تحلیلهای زنجیرهای |
| alerts |
ایجاد و مدیریت هشدارهای وبهوک |
| offline |
دسترسی به توکنهای رفرش برای دریافت توکنهای دسترسی آفلاین |
مدیریت توکن JWT
JWT (توکنهای وب JSON) احراز هویت بدون حالت را فراهم میکنند—سرور نیازی به ذخیره دادههای جلسه ندارد. Smart Money API از RS256 (امضای RSA با SHA-256) برای امضای توکن استفاده میکند که امکان تأیید بدون تماس با API را فراهم میکند.
ساختار JWT
توکنهای JWT از سه بخش جدا شده با نقطه تشکیل شدهاند:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFjY3QxMjM0In0.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
// HEADER.PAYLOAD.SIGNATURE
هدر JWT
هدر الگوریتم و نوع توکن را مشخص میکند:
{
"alg": "RS256",
"typ": "JWT",
"kid": "1"
}
ادعاهای محموله JWT
محموله شامل ادعاها (اظهارات درباره کاربر/برنامه) است:
{
"sub": "acct_1234567890",
"name": "Trading Bot",
"iat": 1703001600,
"exp": 1703088000,
"scopes": ["whales", "derivatives"],
"aud": "https://api.smartmoneyapi.com"
}
تأیید امضاهای JWT
کلید عمومی Smart Money را دانلود کنید و توکنها را قبل از پذیرش تأیید کنید:
const jwt = require('jsonwebtoken');
const fs = require('fs');
// دریافت کلید عمومی از Smart Money API
const publicKey = fs.readFileSync('smartmoney-public.pem');
// تأیید توکن
try {
const decoded = jwt.verify(token, publicKey, {
algorithms: ['RS256'],
audience: 'https://api.smartmoneyapi.com',
issuer: 'https://api.smartmoneyapi.com'
});
// توکن معتبر است، از ادعاهای رمزگشایی شده استفاده کنید
} catch (err) {
// توکن نامعتبر یا منقضی شده است
}
استراتژی چرخش کلید
چرخش منظم کلید برای حفظ امنیت حیاتی است. حتی با بهترین روشهای امنیتی، فرض کنید کلیدها ممکن است به خطر بیفتند و چرخش سیستماتیک را پیادهسازی کنید.
فرکانس چرخش
Smart Money برنامههای چرخش مختلفی را بر اساس نوع کلید و استفاده توصیه میکند:
| نوع کلید |
چرخش توصیه شده |
حداقل چرخش |
| کلیدهای API آزمایشی |
ماهانه |
سهماهه |
| کلیدهای API تولیدی |
سهماهه |
سالانه |
| توکنهای رفرش OAuth |
خودکار (پس از ۹۰ روز) |
دستی (پس از ۱۸۰ روز) |
| کلیدهای حساب سرویس |
نیمسالانه |
سالانه |
فرآیند چرخش بدون وقفه
کلیدها را بدون وقفه در سرویس بچرخانید:
- ایجاد کلید جدید — ایجاد کلید API جدید از طریق داشبورد یا API
- استقرار کلید جدید — بهروزرسانی رمزهای برنامه در محیط آزمایشی، تست کامل
- رولآوت تدریجی — استقرار روی ۱۰٪ سرورها، نظارت بر خطاها
- راهاندازی کامل — استقرار در سرورهای باقیمانده
- تأیید ترافیک — تأیید استفاده از کلید جدید برای تمام درخواستها
- غیرفعال کردن کلید قدیمی — علامتگذاری کلید قدیمی به عنوان غیرفعال اما عدم حذف فوری
- حذف کلید قدیمی — پس از 48 ساعت بدون خطا، حذف دائمی
چرخش اضطراری کلید
اگر مشکوک به افشای کلید هستید:
// اقدام فوری: غیرفعال کردن کلید افشا شده
curl -X POST "https://api.smartmoneyapi.com/v1/keys/sk_live_xxx/revoke" \
-H "Authorization: Bearer token"
// ایجاد کلید جایگزین فوری
curl -X POST "https://api.smartmoneyapi.com/v1/keys" \
-H "Content-Type: application/json" \
-d '{
"name": "کلید جایگزین اضطراری"
}'
چرخش خودکار در Kubernetes
از Kubernetes Secrets و اپراتورها برای چرخش خودکار استفاده کنید:
apiVersion: batch/v1
kind: CronJob
metadata:
name: api-key-rotator
spec:
schedule: "0 0 * * 0" # هفتگی در روز یکشنبه
jobTemplate:
spec:
template:
spec:
containers:
- name: rotator
image: smartmoney-key-rotator:latest
احراز هویت چندعاملی (MFA)
برای حسابهای دسترسی به دادههای تولید، MFA با نیاز به عامل دوم علاوه بر اعتبارنامهها، لایه امنیتی اضافه فراهم میکند.
روشهای پشتیبانی شده MFA
- TOTP (رمز یکبار مصرف زمانبندی شده) — برنامههایی مانند Google Authenticator, Authy
- WebAuthn/FIDO2 — کلیدهای امنیتی سختافزاری، بیومتریک
- کدهای یکبار مصرف SMS — امنیت کمتر اما پشتیبانی جهانی
- تأیید ایمیل — کدهای تأیید ارسال شده به ایمیل ثبتشده
فعالسازی TOTP برای دسترسی به حساب
// مرحله 1: درخواست تنظیم MFA
curl -X POST "https://api.smartmoneyapi.com/v1/account/mfa/enable" \
-H "Authorization: Bearer token"
// پاسخ شامل URL کد QR است
{
"qr_code_url": "https://...",
"secret": "JBSWY3DPEBLW64TMMQ...",
"backup_codes": ["12345678", ...]
}
MFA در عملیات API
برخی عملیات ممکن است نیاز به تأیید MFA حتی پس از احراز هویت داشته باشند:
// تلاش برای عملیات حساس (چرخش کلید)
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Token: mfa_challenge_abc123"
// پاسخ: نیاز به MFA
{
"error": "mfa_required",
"mfa_token": "mfa_xyz789"
}
// تلاش مجدد با کد TOTP
curl -X POST "https://api.smartmoneyapi.com/v1/keys/rotate" \
-H "Authorization: Bearer token" \
-H "X-MFA-Code: 123456"
بهترین روشهای امنیتی
احراز هویت تنها به اندازه پیادهسازی آن قوی است. این روشها را برای حفظ امنیت دنبال کنید:
مدیریت اسرار
- هرگز اسرار را در کنترل نسخه ثبت نکنید — استفاده از فایلهای .env با .gitignore
- استفاده از متغیرهای محیطی — بارگیری از سیستمهای مدیریت اسرار امن
- اسکن مخازن — استفاده از ابزارهایی مانند TruffleHog, detect-secrets برای یافتن کلیدهای افشا شده
- بررسی لاگهای دسترسی — نظارت بر اینکه چه کسی و چه زمانی به اسرار دسترسی داشته است
امنیت انتقال
- همیشه از HTTPS استفاده کنید — هرگز اعتبارنامهها را روی اتصالات رمزنگاری نشده ارسال نکنید
- تأیید گواهیهای SSL — غیرفعال کردن تأیید گواهی در محیط تولید ممنوع
- استفاده از certificate pinning — برای برنامههای موبایل، جلوگیری از حملات MITM
- اجبار به TLS 1.2+ — غیرفعال کردن پروتکلهای قدیمی
مدیریت اعتبارنامه
- هش کردن اسرار — ذخیره هشهای bcrypt یا Argon2، هرگز متن ساده
- کاهش طول عمر — نگهداری اعتبارنامهها در حافظه تنها به مدت نیاز
- پاکسازی دادههای حساس — بازنویسی صریح اعتبارنامهها پس از استفاده
- استفاده از کتابخانههای امن — پیادهسازی رمزنگاری خودتان انجام ندهید
ثبت و نظارت
- هرگز اعتبارنامهها را ثبت نکنید — حذف کلیدها در لاگها، استفاده از ماسک لاگ
- ثبت رویدادهای احراز هویت — ردیابی تلاشهای ورود موفق و ناموفق
- نظارت بر ناهنجاریها — هشدار در مورد الگوهای دسترسی غیرمعمول
- بررسی استفاده از کلید — ردیابی اینکه کدام کلیدها به چه دادههایی دسترسی داشتهاند
الگوهای احراز هویت سازمانی
سازمانهای بزرگ اغلب به کنترلهای امنیتی اضافی و قابلیتهای انطباق نیاز دارند.
ادغام SAML 2.0
برای مشتریان سازمانی، Smart Money API از ادغام SAML 2.0 با ارائهدهنده هویت سازمان شما (Okta, Azure AD و غیره) پشتیبانی میکند:
- ورود یکباره (SSO) — کاربران از طریق IdP سازمانی شما احراز هویت میکنند
- تهیه خودکار — ایجاد/غیرفعال کردن حسابها بر اساس عضویت گروه
- اجبار — نیاز به SAML برای تمام دسترسیهای کاربر
لیست سفید IP
محدود کردن دسترسی API به آدرسهای IP یا محدودههای CIDR خاص
// افزودن IP به لیست سفید
curl -X POST "https://api.smartmoneyapi.com/v1/account/ip-whitelist" \
-H "Authorization: Bearer token" \
-d '{
"cidr": "203.0.113.0/24",
"description": "سرورهای تولید"
}'
ثبت وقایع و انطباق
طرحهای سازمانی شامل گزارشهای جامع ثبت وقایع برای انطباق هستند:
| رویداد |
دادههای ثبت شده |
| احراز هویت |
کاربر، زمان، موفقیت/شکست، IP، وضعیت MFA |
| عملیات کلیدی |
شناسه کلید، اقدام، آغازگر، زمان |
| تغییرات حساب |
چه چیزی تغییر کرده، چه کسی آن را تغییر داده، زمان، مقادیر قبل/بعد |
| دسترسی به دادهها |
کاربر، نقطه پایانی، محدودهها، زمان، تعداد رکوردها |
رفع مشکلات احراز هویت
خطای کلید API نامعتبر
مشکل: دریافت "401 Unauthorized - Invalid API Key"
راهحلها:
- بررسی فرمت کلید (باید با sk_test_ یا sk_live_ شروع شود)
- بررسی وجود فاصله خالی در ابتدا یا انتهای کلید
- تأیید اینکه کلید غیرفعال یا چرخش نشده است
- تأیید اینکه از محیط صحیح استفاده میکنید (کلید تست برای محیط تست، کلید زنده برای تولید)
- بررسی تطابق مجوزهای کلید API با نیازهای نقطه پایانی
خطای منقضی شدن توکن
مشکل: توکن Bearer منقضی شده است، درخواستها با شکست مواجه میشوند
راهحلها:
- استفاده از توکن بازنشانی برای دریافت توکن دسترسی جدید
- پیادهسازی بازنشانی خودکار توکن 5 دقیقه قبل از انقضا
- ذخیره ایمن توکن بازنشانی (نه در localStorage برای برنامههای تک صفحهای)
- مدیریت پاسخهای 401 با تلاش برای جریان بازنشانی توکن
خطاهای CORS/Preflight
مشکل: مرورگر درخواستها را با خطای CORS مسدود میکند
راهحلها:
- تماسهای API از مرورگر باید از منابع مجاز باشند
- افزودن دامنه خود از طریق داشبورد: تنظیمات → منابع CORS
- مرورگر به طور خودکار درخواست OPTIONS preflight را ارسال میکند
- برای توسعه، از localhost:3000 یا مشابه استفاده کنید
عدم تکمیل چالش MFA
مشکل: عملیاتهایی که نیاز به MFA دارند حتی با کد صحیح با شکست مواجه میشوند
راهحلها:
- اطمینان از همگامسازی ساعت سرور (TOTP به زمان وابسته است)
- کد فقط برای 30 ثانیه معتبر است، کد جدید ایجاد کنید
- در صورت عدم دسترسی به برنامه احراز هویت، از کدهای پشتیبان استفاده کنید
- بازیابی حساب از طریق ایمیل ثبتشده امکانپذیر است
امروز احراز هویت ایمن را پیادهسازی کنید
Smart Money API از احراز هویت در سطح سازمانی با OAuth 2.0، JWT، MFA و ادغام SAML پشتیبانی میکند. ادغام API خود را با بهترین روشهای صنعت ایمن کنید.
مشاهده طرحهای سازمانی
به SAML، لیست سفید IP یا پشتیبانی اختصاصی نیاز دارید؟ با تیم فروش ما تماس بگیرید.