نمایک، نیاز اول کسب و کارها
پرش به محتوای اصلی

مستندات

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

کلید عمومی و محرمانه، دامنه‌ها و IPهای مجاز، دسترسی‌ها، چرخش و ابطال کلید و جدول کامل خطاهای کلید.

در این صفحه

کلید عمومی و محرمانه

هر پروژه دو نوع کلید دارد. کلید عمومی دیده می‌شود و با محدودیت دامنه امن می‌ماند؛ کلید محرمانه هرگز نباید دیده شود.

مقایسه کلید عمومی و محرمانه
ویژگیعمومی (pk)محرمانه (sk)
پیشوندnmk_pk_nmk_sk_
جای استفادهمرورگر و اپ (کد عمومی)فقط سرور شما
محدودیت لازمدست‌کم یک دامنه مجازفهرست IP (اختیاری، پیشنهادی)
راه ارسال?key=، سرآیند X-Namayek-Key یا Bearerفقط سرآیند X-Namayek-Key یا Bearer؛ در نشانی رد می‌شود
دسترسی‌هاسرویس‌های نقشههمه، شامل API عمومی و پشتیبان‌گیری
سقف پیش‌فرض50 درخواست در ثانیه100 درخواست در ثانیه
نمایشهر زمان در پنلفقط همان یک بار هنگام ساخت

قالب کلید

کلید nmk_pk_ یا nmk_sk_ و پس از آن ۴۰ نویسه از رقم و حرف لاتین است: ۳۴ نویسه تصادفی و ۶ نویسه کنترل. سرور کلید غلط‌تایپ‌شده را بی جست‌وجو در پایگاه داده رد می‌کند و ابزارهای کشف راز هم می‌توانند کلید واقعی را تشخیص دهند.

در پنل فقط ابتدا و انتهای کلید دیده می‌شود (مثلا nmk_sk_Ab3dE…HZsf). نمایک فقط چکیده HMAC کلید را نگه می‌دارد؛ کلید محرمانه گم‌شده بازیابی نمی‌شود، آن را بچرخانید.

ارسال کلید

  • سرآیند X-Namayek-Key (پیشنهادی برای سرور).
  • سرآیند Authorization: Bearer ….
  • پارامتر ?key= فقط برای کلید عمومی (مثلا در نشانی کاشی). کلید محرمانه در نشانی با خطای SECRET_KEY_IN_URL رد می‌شود.

دو کلید متفاوت در یک درخواست پذیرفته نمی‌شود.

کلید محرمانه در سرآیند
curl -sS "https://api.namayek.com/v1/project" \  -H "X-Namayek-Key: $NAMAYEK_SECRET_KEY"

دامنه‌های مجاز

کلید عمومی فقط از دامنه‌هایی که به آن داده‌اید پذیرفته می‌شود. سرور دامنه را از سرآیند Origin مرورگر می‌خواند؛ این سرآیند را کد صفحه نمی‌تواند جعل کند.

  • فقط origin (پروتکل، نام میزبان و درگاه)؛ مسیر، کوئری، # و نام کاربری پذیرفته نیست.
  • ستاره فقط در ابتدای نام میزبان و فقط با https: ‏https://*.example.com.
  • ستاره روی دامنه سطح بالا (https://*.com) یا localhost پذیرفته نیست.
  • نشانی IP فقط 127.0.0.1 و ‎[::1]‎ برای آزمایش محلی.
  • دامنه فارسی (IDN) خودکار به punycode تبدیل و ذخیره می‌شود.
  • سرور origin را از سرآیند Origin و در نبود آن از Referer می‌خواند؛ درخواست بی هر دو با کلید عمومی رد می‌شود.
نمونه دامنه‌های مجاز
مقدارمی‌پذیردرد می‌کند
https://www.example.comhttps://www.example.comhttps://example.com، http://www.example.com
https://*.example.comhttps://a.example.com، https://a.b.example.comhttps://example.com، https://evil-example.com، http://a.example.com، https://a.example.com:8443
http://localhost:3000http://localhost:3000http://localhost:5173
https://EXAMPLE.com/ذخیره به شکل https://example.com—

IPهای مجاز

کلید محرمانه را به نشانی‌های IP یا بازه‌های CIDR سرورتان ببندید (تا ۵۰ مورد، IPv4 و IPv6). درخواست از IP دیگر با IP_NOT_ALLOWED رد می‌شود. درخواستی که سرآیند Origin دارد با کلید محرمانه پذیرفته نمی‌شود مگر در تنظیمات کلید صریحا اجازه داده باشید.

دسترسی‌ها

هر کلید فقط به سرویس‌هایی دسترسی دارد که هنگام ساخت انتخاب کرده‌اید. کمترین دسترسی لازم را بدهید.

دسترسی‌های کلید
دسترسینوع کلیدتوضیح
maps:tilespk، skکاشی، TileJSON و سند سبک.
maps:searchpk، skپیشنهاد خودکار، جست‌وجو، نشانی‌یابی و نشانی از مختصات.
maps:routingpk، skمسیریابی و ماتریس فاصله.
maps:staticpk، skنقشه ایستا.
backup:readskدیدن منبع‌ها، نسخه‌ها، کارها، بازگردانی‌ها، عامل‌ها و رویدادها و ساخت توکن ویجت. مسیرها
backup:writeskاجرای فوری پشتیبان‌گیری، ویرایش محدود منبع (زمان‌بندی بدون کاهش، توقف و ادامه)، سنجاق و انتقال به سطل بازیافت. اجرای پشتیبان‌گیری
backup:restoreskبازگردانی نسخه در پایگاه داده تازه؛ بازگردانی روی همان پایگاه فقط با روشن بودن «عملیات حساس API». بازگردانی
backup:downloadskساخت لینک دانلود یک‌بارمصرف که به IP فراخوان قفل است. دانلود
webhooks:manageskمدیریت وب‌هوک‌ها با API عمومی.

سقف درخواست

هر کلید سقف درخواست در ثانیه دارد (پیش‌فرض ۵۰ برای عمومی و ۱۰۰ برای محرمانه) و می‌توانید سقف روزانه هم بگذارید. پر شدن سقف ثانیه‌ای RATE_LIMITED و پر شدن سقف روزانه DAILY_CAP_REACHED می‌دهد؛ سقف روزانه نیمه‌شب به وقت تهران صفر می‌شود. سقف هزینه ماهانه پروژه هم جداگانه قابل تنظیم است (مصرف و صورت‌حساب).

چرخش کلید

با چرخش کلید تازه‌ای با همان تنظیمات ساخته می‌شود و کلید قبلی تا پایان دوره هم‌پوشانی (۰ تا ۱۶۸ ساعت) کار می‌کند. در این مدت کلید تازه را جایگزین کنید؛ پس از آن کلید قبلی خودکار باطل می‌شود. چرخش صفر ساعته کلید قبلی را همان لحظه باطل می‌کند (برای کلید لو رفته).

ابطال و انقضا

ابطال فوری است و در چند ثانیه به همه لبه‌های سرویس می‌رسد. کلید باطل‌شده با KEY_REVOKED و کلید منقضی با KEY_EXPIRED رد می‌شود. تاریخ انقضا را می‌توانید از یک ساعت تا سه سال بعد بگذارید و پیش از انقضا رویداد api_key.expiring می‌گیرید. کلیدها هرگز پاک نمی‌شوند تا گزارش مصرف و ممیزی کامل بماند.

خطاهای کلید

سرور شرط‌ها را به همین ترتیب بررسی می‌کند و اولین شرط ناموفق را برمی‌گرداند. درخواست رد‌شده هیچ هزینه‌ای ندارد.

خطاهای کلید به ترتیب بررسی
ترتیبکدHTTPمعنی و اقدام
1KEY_MISSING401کلید API ارسال نشده استکلید را با ?key= (فقط کلید عمومی)، سرآیند X-Namayek-Key یا Authorization: Bearer بفرستید.
2KEY_INVALID401کلید API نامعتبر استکلید را کامل و بی فاصله کپی کنید؛ قالب درست nmk_pk_ یا nmk_sk_ و ۴۰ نویسه است.
3SECRET_KEY_IN_URL400کلید محرمانه نباید در نشانی ارسال شودکلید محرمانه را فقط در سرآیند بفرستید و چون در نشانی دیده شده، همان را بچرخانید.
4KEY_REVOKED401کلید API باطل شده استکلید تازه بسازید یا کلید جانشین چرخش را به کار ببرید.
5KEY_EXPIRED401کلید API منقضی شده استکلید تازه با تاریخ انقضای دیرتر بسازید.
6ACCOUNT_LOCKED403حساب مالک کلید مسدود استبا پشتیبانی نمایک تماس بگیرید.
7PROJECT_DISABLED403پروژه این کلید غیرفعال استپروژه را در پنل فعال کنید یا با پشتیبانی تماس بگیرید.
8BROWSER_USE_FORBIDDEN403کلید محرمانه در مرورگر مجاز نیستدر مرورگر کلید عمومی بگذارید؛ کلید محرمانه فقط روی سرور شما.
9ORIGIN_NOT_ALLOWED403این دامنه برای کلید مجاز نیستدامنه صفحه (مثلا https://www.example.com) را به دامنه‌های مجاز کلید اضافه کنید.
10IP_NOT_ALLOWED403این IP برای کلید مجاز نیستIP خروجی سرورتان را به فهرست IP کلید اضافه کنید.
11SCOPE_DENIED403این کلید به این سرویس دسترسی ندارددسترسی لازم (مثلا maps:routing) را به کلید بدهید.
12ACCOUNT_SUSPENDED402سرویس به دلیل بدهی متوقف استکیف پول را شارژ کنید؛ سرویس فورا برمی‌گردد.
13SPEND_CAP_REACHED402سقف هزینه پروژه پر شده استسقف هزینه پروژه را بالا ببرید یا تا ماه بعد صبر کنید.
14DAILY_CAP_REACHED429سقف روزانه کلید پر شده استتا نیمه‌شب تهران صبر کنید یا سقف روزانه کلید را بالا ببرید.Retry-After: ثانیه تا نیمه‌شب تهران
15RATE_LIMITED429تعداد درخواست بیش از حد مجاز استسرعت را کم کنید و پس از Retry-After دوباره بفرستید.Retry-After: 1
16KEY_LOOKUP_UNAVAILABLE503سرویس موقتا در دسترس نیستبا فاصله رو به افزایش دوباره تلاش کنید.

آخرین به‌روزرسانی: