احراز هویت و کلیدهای API

هر درخواست به API یا بدون کلید فرستاده می‌شود (فقط برای مسیرهای خواندنی عمومی) یا با یک کلید API. کلید هم مشخص می‌کند درخواست از طرف کیست و هم چه کارهایی مجاز است.

ارسال کلید#

کلید را به یکی از این دو روش بفرستید. اگر هر دو سرآیند باشند، Authorization ملاک است.

# روش پیشنهادی
curl https://gameroute.ir/api/v1/me -H "Authorization: Bearer gr_live_..."

# روش جایگزین
curl https://gameroute.ir/api/v1/me -H "X-API-Key: gr_live_..."

کلید را هیچ‌وقت در query string (مثل ?key=) نفرستید؛ این روش پشتیبانی نمی‌شود چون نشانی‌ها در لاگ‌ها و تاریخچه مرورگر ذخیره می‌شوند.

مسیر GET /me برای آزمایش کلید ساخته شده و نام، دسترسی‌ها، سقف درخواست و سرور متصل به کلید را برمی‌گرداند.

دو نوع کلید#

دسترسی‌ها (scopes)#

دسترسی read همیشه روی هر کلیدی هست. برای انتخاب news:write یا profile:write هنگام ساخت کلید، خود شما باید همان مجوز را در تیم داشته باشید؛ کسی نمی‌تواند کلیدی بسازد که بیشتر از خودش اختیار داشته باشد.

کلید و نقش‌های تیم#

کلید سرور به نام عضوی ساخته می‌شود که آن را ساخته است و در هر درخواست مدیریتی، دسترسی فعلی همان شخص دوباره بررسی می‌شود. یعنی:

• اگر نقش سازنده تغییر کند و دیگر «مدیریت اخبار» نداشته باشد، درخواست‌های news:write آن کلید با خطای 403 و کد NO_SERVER_PERMISSION رد می‌شوند، حتی اگر کلید هنوز باطل نشده باشد.
• اگر سازنده از تیم خارج شود، کلید فقط برای خواندن داده‌های عمومی کار می‌کند.
• اگر حساب سازنده مسدود شود، همه کلیدهایش با خطای ACCOUNT_BANNED متوقف می‌شوند.
• اگر مالکیت سرور منتقل شود، کلیدهای قبلی باطل نمی‌شوند؛ مالک جدید باید فهرست کلیدها را بازبینی کند.

همه کارهایی که با کلید انجام می‌شود به نام سازنده کلید در گزارش فعالیت سرور ثبت می‌شود.

نگهداری امن#

• گیم روت فقط هش SHA-256 کلید را نگه می‌دارد و خود کلید را دیگر نمی‌تواند نشان دهد. اگر کلید را گم کردید، کلید تازه بسازید و قبلی را باطل کنید.
• ۱۴ کاراکتر اول کلید (مثل gr_live_ab12cd) در پنل نمایش داده می‌شود تا کلیدها را از هم تشخیص دهید.
• کلید را در متغیر محیطی یا مدیر رازها (Secret manager) نگه دارید، نه در کد.
• برای هر برنامه یک کلید جدا بسازید تا اگر یکی لو رفت، فقط همان را باطل کنید.
• زمان آخرین استفاده از هر کلید در پنل نمایش داده می‌شود (با دقت حدود یک دقیقه). کلیدی که مدت‌هاست استفاده نشده را باطل کنید.

باطل کردن کلید#

از همان بخشی که کلید را ساخته‌اید، دکمه «باطل کردن» را بزنید. کلید بلافاصله از کار می‌افتد و درخواست‌های بعدی با خطای 401 و کد API_KEY_REVOKED رد می‌شوند. کلید باطل‌شده دوباره فعال نمی‌شود. کلیدهای سرور را هر عضو دارای MANAGE_INTEGRATIONS می‌تواند باطل کند، حتی اگر سازنده‌اش کس دیگری باشد.

CORS و استفاده در مرورگر#

مسیرهای GET با سرآیند Access-Control-Allow-Origin: * پاسخ می‌دهند، پس می‌توانید داده عمومی را مستقیماً از جاوااسکریپت سایتتان بخوانید. برای این کار از کلید استفاده نکنید؛ بدون کلید درخواست با سقف هر بازدیدکننده (۳۰ درخواست در دقیقه برای هر IP) انجام می‌شود که برای یک صفحه وب کاملاً کافی است. سرآیندهای سقف درخواست هم برای جاوااسکریپت قابل خواندن هستند.