آنچه در مقاله میخوانید
API Key یا کلید API رشتهای منحصربهفرد است که سرویسها با کمک آن برنامه یا پروژهای را که درخواست میفرستد شناسایی میکنند. این کلید به سرور امکان میدهد منبع درخواستهای HTTP را تشخیص دهد، مجوزهای مربوط به آن پروژه را بررسی کند و محدودیتهای مصرف را اعمال کند. اگر با APIها کار میکنید، شناخت نحوۀ عملکرد و نگهداری امن این کلیدها اهمیت زیادی دارد.
در ادامۀ این مطلب از مبین هاست، از تعریف API Key شروع میکنیم و قدمبهقدم به کاربردها، روش استفاده و نکات امنیتی آن میرسیم. با ما همراه باشید.
API Key چیست؟
برای پاسخ به این پرسش که کلید API چیست، ابتدا باید جای آن را در ارتباط میان نرمافزارها ببینیم. API یا رابط برنامهنویسی کاربردی، روشی استاندارد است که به برنامهها اجازه میدهد با یکدیگر داده ردوبدل کنند یا از قابلیتهای یک سرویس استفاده کنند. وقتی یک نرمافزار به سرویسی بیرونی، مثل یک پلتفرم ابری، درخواست میفرستد، آن سرویس باید بتواند پروژۀ درخواستکننده را تشخیص دهد. API Key در بسیاری از سرویسها همین شناسه را فراهم میکند.
برای مثال، سرویسهایی مانند Google Maps یا OpenWeatherMap هنگام فعالکردن دسترسی API، یک کلید اختصاصی در اختیار توسعهدهنده قرار میدهند. این کلید همراه درخواست ارسال میشود و به سرویس نشان میدهد درخواست به کدام پروژه مربوط است. از همین شناسه میتوان برای مدیریت سهمیۀ مصرف، اعمال محدودیتها و کنترل دسترسی همان پروژه استفاده کرد.
یک API Key دقیقاً چگونه کار میکند؟
فرایند از زمانی شروع میشود که برنامه یک درخواست به API میفرستد. کلید، بسته به مستندات سرویس، در Header یا یکی از پارامترهای درخواست HTTP قرار میگیرد. سرور پس از دریافت درخواست، API Key را با اطلاعات ثبتشده در سیستم خود تطبیق میدهد و اگر کلید معتبر باشد، مجوزها و محدودیتهای مرتبط با آن را بررسی میکند. چون این مقدار در مسیر ارتباط جابهجا میشود، درخواست باید از طریق HTTPS ارسال شود تا خطر شنود یا حملۀ مرد میانی (MITM) کاهش پیدا کند.
اگر کلید معتبر باشد و درخواست با محدودیتهای تعریفشده تضادی نداشته باشد، پردازش ادامه پیدا میکند. در مقابل، نبودن کلید، نامعتبر بودن آن یا نداشتن مجوز کافی میتواند به خطاهایی مانند ۴۰۱ (Unauthorized) یا ۴۰۳ (Forbidden) منجر شود. این اعتبارسنجی معمولاً بهصورت خودکار در سمت سرور (Server-side) انجام میشود و کاربر مستقیماً با جزئیات آن درگیر نیست.
3 کاربرد مهم API Key
نقش API Key فقط این نیست که جلوی درخواستهای ناشناس را بگیرد. همین شناسه به سرویسدهنده کمک میکند بفهمد هر درخواست از کدام پروژه آمده، هر پروژه چه مقدار از سرویس استفاده کرده است و چه محدودیتهایی باید برای آن اعمال شود. به همین دلیل، API Key معمولاً در سه بخش زیر بیشترین کاربرد را دارد.
1) شناسایی و احراز هویت پروژهها
در پاسخ به سؤال: «API Key Authentication چیست»، معمولاً چیزی که شناسایی میشود برنامه یا پروژۀ درخواستکننده است، نه کاربر نهایی. سرور با بررسی کلید متوجه میشود درخواست از کدام وبسایت، اپلیکیشن یا سرویس آمده است. در برخی سیستمهای ساده یا قدیمی ممکن است API Key برای شناسایی مستقیم کاربر هم به کار رفته باشد، اما در معماریهای امروزی بهتر است احراز هویت کاربران با سازوکارهای اختصاصی و متناسب با سطح دسترسی آنها انجام شود.
2) کنترل ترافیک و اعمال محدودیت دسترسی
وقتی سرویسدهنده بداند هر درخواست متعلق به کدام پروژه است، مدیریت مصرف منابع هم سادهتر میشود. برای نمونه، میتواند با Rate Limiting تعداد درخواستهای هر کلید را در یک بازۀ زمانی بشمارد و برای آن سقف مشخصی در نظر بگیرد. اگر مصرف از حد تعیینشده بیشتر شود، درخواستهای بعدی تا شروع بازۀ جدید محدود یا متوقف میشوند. این کار هم از فشار بیشازحد بر زیرساخت جلوگیری میکند و هم امکان تعریف پلنهای مصرف متفاوت را فراهم میسازد.
3) ردیابی و تحلیل رفتار کاربران
اتصال هر API Key به یک پروژۀ یا مشتری مشخص، امکان ثبت و بررسی الگوی مصرف را هم فراهم میکند. سرویسدهنده میتواند تعداد درخواستها، زمان استفاده و حجم مصرف را بررسی کند و از این دادهها برای محاسبۀ هزینه، عیبیابی و لاگگیری امنیتی (Logging) استفاده کند. همین اطلاعات در تشخیص رفتارهای غیرعادی نیز مفید هستند؛ برای مثال، افزایش ناگهانی تعداد درخواستها میتواند نشانهای از سوءاستفاده یا ترافیک مخرب باشد.
تفاوت API Key با توکن دسترسی چیست؟
API Key و Access Token هر دو در کنترل دسترسی نقش دارند، اما برای یک هدف ساخته نشدهاند. API Key بیشتر برای شناسایی یک برنامه یا پروژه استفاده میشود، در حالی که Access Token معمولاً مجوزی موقت است که به هویت یا سطح دسترسی کاربر وابسته است. همین تفاوت باعث میشود محل استفاده، مدت اعتبار و نوع مجوزهای این دو هم یکسان نباشد. جدول زیر این تفاوتها را خلاصه میکند:
| ویژگی | API Key (کلید API) | Access Token (توکن دسترسی) |
| هدف اصلی | شناسایی برنامه یا پروژه (App) | اعطای دسترسی بر اساس هویت یا مجوز کاربر |
| مدت زمان اعتبار | بسته به سرویس؛ اغلب تا زمان ابطال یا چرخش کلید | معمولاً موقت و دارای زمان انقضا |
| محل استفاده | بکاند، اسکریپتها و ارتباطات سرویس به سرویس | نشستهای کاربری و درخواستهای مبتنی بر مجوز |
| سطح دسترسی | بر اساس مجوزهای تعریفشده برای کلید | بر اساس Scope یا مجوزهای صادرشده برای توکن |
| محیط اجرایی | ترجیحاً محیطهای امن سمت سرور؛ بسته به نوع کلید | بسته به معماری، سمت کلاینت یا سرور |
چگونه یک API Key امن بسازیم؟
روش ساخت api key از یک سرویس به سرویس دیگر فرق میکند، اما مسیر کلی معمولاً مشابه است. بعضی پلتفرمها کلیدهایی برای استفاده در سمت کلاینت ارائه میدهند و برخی دیگر کلیدهای خصوصی را فقط برای ارتباطات سرور به سرور در نظر میگیرند. بنابراین قبل از ساخت کلید، بهتر است مستندات سرویس را بررسی کنید تا هم نوع مناسب را انتخاب کنید و هم از همان ابتدا محدودیتهای لازم را روی آن اعمال کنید.
- ثبتنام و ورود: در وبسایت ارائهدهنده سرویس حساب کاربری ایجاد کنید و وارد شوید.
- ورود به داشبورد توسعهدهندگان: بخش Developer Console یا مدیریت APIها را باز کنید.
- ایجاد پروژه: اگر سرویس از ساخت پروژه پشتیبانی میکند، یک پروژۀ جدید بسازید و تنظیمات موردنیاز را مشخص کنید.
- تولید کلید: گزینۀ Generate Key یا ساخت API Key را انتخاب کنید.
- ذخیرۀ امن: کلید تولیدشده را بدون تغییر کپی کنید و آن را در محلی امن نگه دارید.
نحوۀ استفاده از API Key در پروژههای نرمافزاری
بعد از دریافت کلید، نوبت به استفاده از آن در درخواستها میرسد. روش ارسال API Key را خود سرویسدهنده تعیین میکند؛ بنابراین مستندات API همیشه مرجع اصلی است. برای مثال، اگر بخواهید از یک سرویس آبوهوا داده دریافت کنید، ممکن است لازم باشد کلید را در Query String، در HTTP Header یا در بعضی موارد داخل بدنه درخواست قرار دهید.
- ارسال در Query String: در این روش، API Key به یکی از پارامترهای URL اضافه میشود. پیادهسازی آن ساده است، اما چون آدرس درخواست ممکن است در لاگها، تاریخچۀ مرورگر یا ابزارهای مانیتورینگ ثبت شود، برای کلیدهای حساس انتخاب مناسبی نیست.
- ارسال در HTTP Header: بسیاری از APIها کلید را از طریق Header دریافت میکنند. نام Header و قالب مقدار آن در هر سرویس میتواند متفاوت باشد، بنابراین باید دقیقاً از الگوی مستندات همان API پیروی کنید. نمونۀ زیر یک قالب متداول را نشان میدهد:
curl -X GET "https://api.example.com/data" \ -H "Authorization: Api-Key YOUR_API_KEY_HERE"
- ارسال در بدنۀ درخواست (Body): بعضی APIها، بهویژه در درخواستهای POST، اجازه میدهند API Key بهصورت یک فیلد در ساختار JSON بدنه ارسال شود. این روش هم فقط زمانی باید استفاده شود که در مستندات سرویس مشخص شده باشد.
در نتیجه، نمیتوان یک روش را برای تمام APIها بهعنوان بهترین گزینه دانست. جای درست قرارگرفتن کلید و قالب ارسال آن را معماری سرویس و مستندات ارائهدهنده مشخص میکند.
مهمترین نکات امنیتی برای محافظت از کلید API
API Key را باید مثل یک اعتبار دسترسی نگهداری کرد؛ چون افشای آن میتواند باعث مصرف غیرمجاز منابع، افزایش هزینه یا دسترسی ناخواسته به سرویس شود. با این حال، امنیت API Key فقط به مخفیکردن مقدار کلید خلاصه نمیشود. بهتر است محدودسازی دسترسی، محل نگهداری مناسب و امکان ابطال کلید هم از ابتدا در طراحی پروژه در نظر گرفته شوند.
محدودسازی دسترسی بر اساس IP و دامنه
هرچه دامنۀ استفاده از یک کلید محدودتر باشد، سوءاستفاده از آن دشوارتر میشود. اگر سرویس برای کلیدهای سمت کلاینت محدودیت HTTP Referrer ارائه میدهد، کلید را فقط به دامنههای موردنیاز محدود کنید. کلیدهای خصوصی نیز نباید داخل مرورگر یا کد فرانتاند قرار بگیرند. در سمت سرور، بسته به امکانات سرویس، میتوان از محدودیت IP ،mTLS یا روشهایی مانند Request Signing برای کاهش سطح دسترسی استفاده کرد.
استفاده از متغیرهای محیطی برای مخفی کردن کلید
یکی از خطاهای رایج این است که API Key مستقیماً داخل فایلهای کد نوشته شود (Hardcode). در پروژههای سمت سرور بهتر است مقدار کلید از کد جدا بماند و از طریق متغیرهای محیطی (Environment Variables) در اختیار برنامه قرار بگیرد. برای مثال، میتوانید کلید را در فایل env. تعریف کنید و برنامه هنگام اجرا مقدار آن را بخواند:
API_KEY=YOUR_SECURE_API_KEY_HERE
فایل env. را هم به gitignore. اضافه کنید تا همراه کد وارد مخازن عمومی مانند GitHub نشود. اگر کلیدی قبلاً در یک مخزن عمومی منتشر شده است، پاککردن فایل بهتنهایی کافی نیست و باید آن کلید را باطل کنید و کلید تازهای جایگزین آن کنید.
چرخش دورهای و ابطال کلیدهای قدیمی
برای کلیدهای حساس، بهتر است روند مشخصی برای Key Rotation و ابطال کلیدهای قدیمی داشته باشید. فاصلۀ زمانی چرخش به سیاست امنیتی، حساسیت سرویس و امکانات ارائهدهنده بستگی دارد و لزوماً برای همۀ پروژهها یکسان نیست. بعد از جایگزینی کلید و اطمینان از عملکرد درست برنامه، کلید قبلی را Revoke کنید تا دیگر قابل استفاده نباشد.
اشتباهات رایج توسعهدهندگان در استفاده از کلید API
همۀ خطاهایی که هنگام کار با API دیده میشوند پیچیده نیستند. بعضی اوقات یک Space اضافی در ابتدا یا انتهای کلید، استفاده از کلید محیط Development در Production یا عبور از Rate Limit باعث خطاهای ۴۰۱ و ۴۰۳ میشود. به همین دلیل، هنگام عیبیابی بهتر است ابتدا همین موارد ساده را بررسی کنید و بعد سراغ بخشهای پیچیدهتر کد یا تنظیمات بروید.
اشتباه جدیتر زمانی رخ میدهد که API Key را جایگزین سازوکاری کنیم که باید کنترل دسترسی دقیقتری داشته باشد. در سامانههای حساس مالی، بانکی یا پزشکی، یا هر جایی که نقشها و سطح دسترسی کاربران با RBAC مدیریت میشود، یک API Key بهتنهایی پاسخگو نیست. در چنین سناریوهایی معمولاً باید از روشهایی مانند OAuth 2.0 و لایههای امنیتی مکمل استفاده شود تا هویت و مجوزها جداگانه مدیریت شوند.
کلام آخر
API Key در ظاهر فقط یک رشتۀ متنی است، اما در عمل بخشی از سازوکار دسترسی میان برنامه و سرویس را تشکیل میدهد. اگر کلید در جای درستی نگهداری شود، فقط به منابع لازم دسترسی داشته باشد و در صورت نیاز قابل چرخش یا ابطال باشد، مدیریت آن بسیار سادهتر و امنتر خواهد بود. در مقابل، قراردادن کلید در کد عمومی یا استفاده از آن بهجای یک سیستم احراز هویت کامل میتواند به نقطهضعف جدی تبدیل شود.
اگر برای میزبانی اپلیکیشن یا بکاند سرویس خود به زیرساخت نیاز دارید، سرورهای مجازی و اختصاصی مبین هاست میتوانند بستر لازم برای راهاندازی و مدیریت APIها را در اختیار شما قرار دهند. هنگام انتخاب زیرساخت، در کنار منابع سختافزاری، امکانات امنیتی و نحوۀ مدیریت دسترسیها را هم در نظر بگیرید.
سوالات متداول
خیر. API Key بیشتر برای شناسایی برنامه یا پروژۀ و کنترل دسترسی آن به سرویس به کار میرود. اگر سیستم به احراز هویت کاربر یا مجوزهای دقیقتری نیاز دارد، باید در کنار HTTPS از توکنهای زماندار و سازوکارهای کنترل دسترسی متناسب با معماری سیستم استفاده شود.
کلیدهایی که برای استفاده در سمت کلاینت طراحی شدهاند معمولاً با محدودیتهایی مانند دامنه یا Referrer کنترل میشوند. در مقابل، کلید خصوصی باید در محیط امن سمت سرور نگهداری شود و در اختیار کاربر نهایی قرار نگیرد.
لاگهای سرور و داشبورد مصرف API میتوانند نشانههای مهمی در اختیار شما بگذارند. افزایش ناگهانی درخواستها، دیدهشدن IPهای ناشناس یا رشد غیرعادی هزینۀ سرویس میتواند نشانۀ سوءاستفاده باشد. در چنین شرایطی، کلید مشکوک را سریعاً Revoke کنید و کلید جدیدی جایگزین آن کنید.
پیامد نشت کلید به سطح دسترسی آن بستگی دارد. فرد غیرمجاز ممکن است درخواستهایی به نام پروژه شما ارسال کند، سهمیۀ سرویس را مصرف کند یا هزینه ایجاد کند. به همین دلیل، هر کلیدی که احتمال میدهید افشا شده است باید فوراً باطل و جایگزین شود.
