کلیدهای API

دو کلید شما — محرمانه و ابزارک — از کجا می‌آیند، دقیقاً هر کدام چه کاری از آن برمی‌آید، و چطور امن نگهشان دارید.

هر اپ دو کلید دارد. کلید محرمانه (sk_…) تنها اعتبارنامه‌ای است که این API می‌پذیرد و تمام اختیارات حسابِ مالک اپ را دارد. کلید ابزارک (pk_…) عمومی است و فقط می‌تواند از طریق ابزارک سؤال بپرسد.

پیدا کردن کلیدها

کنسول را باز کنید، یک اپ انتخاب کنید و کارت «کلید محرمانه» را در ستون کناری صفحهٔ اپ پیدا کنید. «ساخت کلید» را بزنید و همان لحظه کپی‌اش کنید: ما فقط اثر انگشتِ آن را نگه می‌داریم، پس دیگر هرگز نمایش داده نمی‌شود. گمش کردید؟ یک کلید جدید بسازید.

sk_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL

کلیدها رشته‌هایی مبهم با پیشوند dk_live_ هستند. کل رشته را رمز در نظر بگیرید — زوج شناسه و رمز جداگانه‌ای وجود ندارد.

کلید محرمانه چه کاری می‌تواند بکند

کلید محرمانه به‌عنوان کاربری که مالک اپ است احراز هویت می‌شود. این دامنه گسترده‌تر از چیزی است که به نظر می‌رسد، پس بگذارید صریح بگوییم. هرکس کلید محرمانه را داشته باشد می‌تواند:

فضاهای کاری زیر آن اپ را فهرست کند، بسازد، تغییر نام دهد و حذف کند.
در هر کدام از آن فضاها سند بارگذاری کند و سندها را حذف کند.
مقدار file_url هر سند را بخواند، که لینک مستقیم به فایل اصلی ذخیره‌شده است.
در هر کدام از آن فضاها سؤال بپرسد و تاریخچهٔ گفت‌وگوی هر کاربر نهایی را بخواند.

هرکس کلید محرمانه را به دست بیاورد می‌تواند یک فضای کاری کامل را حذف کند و همهٔ سندهای داخلش را دانلود کند. کلید ابزارک هیچ‌کدام از این کارها را نمی‌تواند — فقط سؤال می‌پرسد و پاسخ‌هایش منبعی ندارند.

امن نگه داشتنش

و از همین‌جا فهرست کوتاهی از قاعده‌ها بیرون می‌آید:

API را فقط از سمت سرور خودتان صدا بزنید. نه از مرورگر، نه از اپ موبایل، نه از اپ دسکتاپ، و نه از هیچ خروجی ساختی که کاربرانتان می‌توانند دانلودش کنند.
کلید را از متغیر محیطی یا یک secret manager بخوانید. هرگز در مخزن کد ثبتش نکنید و هرگز جایی نگذاریدش که مرحلهٔ ساخت بتواند آن را داخل بستهٔ سمت کاربر بگذارد.
اگر کاربرانتان باید از مرورگر بپرسند، از سرور خودتان پراکسی کنید: برنامهٔ سمت کاربر شما API خودتان را صدا می‌زند و API شما کلید محرمانه را نگه می‌دارد. همین کار به شما اجازه می‌دهد محدودیت نرخ خودتان را اعمال کنید، چیزی که این API هنوز ندارد.
برای هر کاربر نهایی external_user_id متفاوتی بفرستید تا با وجود اشتراک در یک کلید محرمانه، گفت‌وگوهایی که ذخیره می‌کنید از هم جدا بمانند.

چرخش و ابطالدر نقشهٔ راه: به‌زودی

هر کلید در صفحهٔ اپ دکمه‌های «ساخت کلید جدید» و «حذف» خودش را دارد. هر دو فوری‌اند: کلید قدیمی همان لحظه از کار می‌افتد. بعد از حذف، اپ تا وقتی «ساخت کلید» را نزنید آن کلید را ندارد. هر ساعت حداکثر ۱۰ بار می‌توانید کلیدها را عوض کنید.

دورهٔ هم‌پوشانی وجود ندارد. کلید محرمانهٔ جدید، هر سروری را که از کلید قدیمی استفاده می‌کند از کار می‌اندازد و کلید ابزارک جدید، هر کد ابزارکی را که در سایت گذاشته‌اید — تا وقتی کلید تازه را جایگزین کنید؛ پس پیش از زدن «ساخت کلید جدید»، آمادهٔ گذاشتنش باشید.

ابزارک کلید عمومی خودش را دارد، نه این کلید را. پیش از گذاشتن ابزارک روی سایت، صفحهٔ امنیت را بخوانید.

پیدا کردن کلیدها

sk_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL

کلید محرمانه چه کاری می‌تواند بکند

فضاهای کاری زیر آن اپ را فهرست کند، بسازد، تغییر نام دهد و حذف کند.

در هر کدام از آن فضاها سند بارگذاری کند و سندها را حذف کند.

مقدار file_url هر سند را بخواند، که لینک مستقیم به فایل اصلی ذخیره‌شده است.

در هر کدام از آن فضاها سؤال بپرسد و تاریخچهٔ گفت‌وگوی هر کاربر نهایی را بخواند.

امن نگه داشتنش

و از همین‌جا فهرست کوتاهی از قاعده‌ها بیرون می‌آید:

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

کلید را از متغیر محیطی یا یک secret manager بخوانید. هرگز در مخزن کد ثبتش نکنید و هرگز جایی نگذاریدش که مرحلهٔ ساخت بتواند آن را داخل بستهٔ سمت کاربر بگذارد.

اگر کاربرانتان باید از مرورگر بپرسند، از سرور خودتان پراکسی کنید: برنامهٔ سمت کاربر شما API خودتان را صدا می‌زند و API شما کلید محرمانه را نگه می‌دارد. همین کار به شما اجازه می‌دهد محدودیت نرخ خودتان را اعمال کنید، چیزی که این API هنوز ندارد.

برای هر کاربر نهایی external_user_id متفاوتی بفرستید تا با وجود اشتراک در یک کلید محرمانه، گفت‌وگوهایی که ذخیره می‌کنید از هم جدا بمانند.

چرخش و ابطالبه‌زودی

ابزارک کلید عمومی خودش را دارد، نه این کلید را. پیش از گذاشتن ابزارک روی سایت، صفحهٔ امنیت را بخوانید.