کلیدهای API
هر درخواستی که از یک اپلیکیشن به سرورهای دیوار زده می‌شود می‌بایست شامل رشته (string) مشخصی به نام «کلید API» یا «API Key» باشد. سرورهای دیوار از طریق این کلید می‌فهمند درخواست از سمت کدام اپلیکیشن ارسال شده‌است. درخواست‌های بدون کلید رد خواهند شد.
👈 کلید API را در هدر x-api-key درخواست‌های خود قرار دهید:
POST https://open-api.divar.ir/v1/open-platform/finder/post/{{token}}
x-api-key: {{apikey}}
ساختن کلید جدید
۱. به صفحه‌ی مدیریت برنامه‌ها در پنل کنار بروید.
۲. وارد صفحه جزئیات برنامه خود شوید.
۳. روی دکمهٔ «کلیدهای API» کلید کنید.
۴. روی دکمهٔ «ساخت کلید جدید» کلیک کنید.
۵. عنوانی برای کلید جدید خود انتخاب کنید و کلید خود را بسازید.
۶. مقدار کلیدی که به شما داده می‌شود را ذخیره کنید و در جایی امن نگهداری کنید.\
⚠️ دقت کنید!
در پنل کنار، مقدار یک کلید را تنها در هنگام ساختن آن می‌توانید ببینید، حتما مقدار کلید را قبل از اتمام ساخت کلید کپی کرده و در جای امنی ذخیره کنید. این قاعده برای تامین امنیت شماست: با دسترسی به کلید API هر کس می‌تواند خود را به جای شما جا بزند!
امنیت کلیدها
اشخاص ثالث با دسترسی به کلیدهای API شما می‌توانند به جای شما، و با هویت شما، در کنار دیوار فعالیت ک رده و با کاربرها تعامل کنند. در نتیجه حفظ امنیت کلیدهای API بسیار مهم است. مسوولیت هرگونه سوءاستفاده از کلیدهای API شما، بر عهده‌ی خود شماست. برای حفظ امنیت کلیدها به نکات زیر توجه کنید:
🔐 نگهداری کلیدها
برای امنیت شما، در پنل کنار، مقدار کلید را صرفا هنگام ساختن کلید می‌توانید ببینید. مطمئن شوید کلید را در جای امنی ذخیره کرده‌اید.
کلیدها را در کد ذخیره نکنید❗
از متغیرهای محیطی (Environment Variable)، فایل‌های کانفیگ یا ابزارهای مدیریت کلید استفاده کنید.
کلیدها را در git ذخیره نکنید❗
اگر کلیدها را در فایل‌های کانفیگی نگه می‌دارید، مطمئن شوید این فایل‌ها توسط git (یا سایر ابزارهای مدیریت ورژن) کنترل نمی‌شوند. برای مثال، اگر از git استفاده می‌کنید، حتما این فایل‌ها را به .gitignore پروژه‌ی خود اضافه کنید.
🛂 دسترسی‌های کلیدها
هر اپلیکیشن می‌تواند کلیدهای مختلف با دسترسی‌های مختلف داشته باشد. مثلا یک کلید می‌تواند مختص افزودن و [حذف][راهنما » حذف افزونه] افزونه به آگهی باشد، درحالیکه کلید دیگری فقط دسترسی دریافت اطلاعات کاربر را دارد، و کلید دیگری دسترسی ارسال پیام در چت. با توزیع دسترسی‌ها بین کلیدهای مختلف، ریسک افشای هر کلید را کاهش دهید.
- اگر کدبیس شما شامل سرویس‌های مختلف است، برای هر سرویس کلید مجزایی با کمینه‌ی دسترسی‌های مورد نیاز بسازید.
- برای تست و توسعه از کلیدهای مجزایی با دسترسی‌های محدود استفاده کنید.
- کلیدهای مورد استفاده برای تست و توسعه را به صورت منظم حذف کنید.
🕰️ چرخش کلیدها
برای کاهش ریسک افشای کلیدها، آن‌ها را به طور دوره‌ای حذف کنید. توصیه می‌شود کلیدهای خود را حداکثر هر ۶۰ روز پاک کنید و کلیدهای جدیدی بسازید. به علاوه در صورت تغییر اعضای تیم، کلیدهایی که اعضای سابق به آن‌ها دسترسی داشته‌اند را حذف کنید.
حذف کلید
۱. به [صفحه‌ی مدیریت کلیدها در پنل کنار][پنل کنار » مدیریت کلیدها] بروید.
۲. کلید مورد نظر را برای تغییر انتخاب کنید.
۳. وضعیت کلید را به Revoked تغییر دهید.
۴. روی دکمه‌ی Save کلیک کنید.
۵. در لیست کلیدها، از تغییر وضعیت کلید مطمئن شوید.
دسترسی‌های پرکاربرد
قابلیت‌های مختلف کنار دیوار (مثل ساخت افزونه یا ارسال پیام در چت) نیازمند دسترسی‌های متفاوتی هستند، و کلیدی که در هدر x-api-key هر درخواست قرار می‌گیرد می‌بایست دسترسی‌های مورد نیاز را داشته باشد. در صفحه‌ی توضیحات هر قابلیت، دسترسی‌های مورد نیاز را می‌توانید ببینید. در جدول زیر لیست دسترسی‌های پرکاربرد را مشاهده کنید.
🛂 فقط و فقط دسترسی‌های مورد نیاز را به هر کلید بدهید. توضیحات بیشتر در مورد امنیت کلیدها را اینجا بخوانید.
| قابلیت | دسترسی | توضیحات |
|---|---|---|
| ساخت افزونه | ADD_ON_CREATE | نیازمند دریافت اجازه از کاربر |
| دریافت اطلاعات آگهی | GET_POST | |
| دریافت اطلاعات کاربر | USER_RETRIEVE | نیازمند دریافت اجازه از کاربر |
| ارسال پیام در چت | CHAT_SEND_MESSAGE_OAUTH | نیازمند دریافت اجازه از کاربر |
💡 لیست دسترسی‌هایی که می‌توانید به کلیدهای خود بدهید محدود به دسترسی‌هایی است که به اپلیکیشن شما داده شده است. در صورتی که نیاز به دسترسی‌ای دارید که در پنل کنار آن را نمی‌بینید، با ما تماس بگیرید تا دسترسی اپلیکیشن شما را گسترش دهیم.
