احراز هویت

کار با پلکسیت دو بخش جدا دارد:

کجا	آدرس	احراز هویت	کاربرد
کنسول (وب)	`https://console.plexit.ir`	ورود با حساب کاربری	ساخت، مشاهده و ابطال کلیدهای API توسط تیم شما
API عمومی	`https://api.plexit.ir/v1/*`	`Authorization: Bearer <raw_key>`	فراخوانی سرور-به-سرور از بک‌اند شما

کلیدها را فقط در کنسول مدیریت می‌کنید. هر فراخوانی واقعیِ محصول — گفتگو، اسناد، دستیارها — با کلید خام به API عمومی ارسال می‌شود.

۱. ساخت کلید API در کنسول

وارد کنسول شوید

به console.plexit.ir بروید و وارد حساب خود شوید. اگر هنوز حساب ندارید، از صفحه‌ی ثبت‌نام یک حساب بسازید.

صفحه‌ی «API و اتصال» را باز کنید

در منوی کناری پنل، تنظیمات و سپس API و اتصال (/settings/developers) را باز کنید. این صفحه فقط برای اعضایی که اجازه‌ی مدیریت کلیدهای API دارند نمایش داده می‌شود؛ اگر آن را نمی‌بینید از مالک فضای کاری بخواهید.

یک کلید جدید بسازید

روی «کلید جدید» بزنید و یک نام برای آن وارد کنید (مثلاً «Production server»). این نام فقط برچسبی برای خود شماست تا بعداً کلید را تشخیص دهید.

کلید خام را کپی کنید

پس از ساخت، کنسول کلید خام (به شکل pk_live_…) را نمایش می‌دهد. همین حالا آن را کپی کنید.

کلید خام فقط یک‌بار، دقیقاً همین لحظه، نمایش داده می‌شود و دیگر هرگز نمایش داده نخواهد شد. پلکسیت آن را به شکلی که بعداً قابل بازیابی باشد ذخیره نمی‌کند — فقط یک Hash از آن نگه‌داری می‌شود. اگر آن را گم کردید، کلید را باطل کرده و یک کلید جدید بسازید. آن را بلافاصله در یک Secrets Manager (Vault، AWS/GCP Secrets Manager، سکرت‌های رمزنگاری‌شده‌ی CI/CD شما و غیره) ذخیره کنید — هرگز در کد منبع یا یک فایل پیکربندیِ متن ساده.

۲. مشاهده و ابطال کلیدها

در همان صفحه‌ی «API و اتصال» فهرست همه‌ی کلیدهای خود را می‌بینید: نام، پیشوند کلید (keyPrefix، مثلاً pk_live_8f2a…)، تاریخ ساخت، زمان آخرین استفاده و وضعیت. آدرس پایه‌ی API و پیوند این مستندات هم در همین صفحه است. کلید خام دیگر هرگز نمایش داده نمی‌شود؛ پیشوند فقط برای تشخیص کلید است و نمایش آن بی‌خطر است.

برای ابطال یک کلید، آن را در همین فهرست باطل کنید. ابطال بلافاصله اعمال می‌شود — هر درخواست بعدی به API عمومی با آن کلید خام، پاسخ 401 دریافت می‌کند.

۳. استفاده از کلید در API عمومی

هر یک از مسیرهای زیر v1/* به این هدر نیاز دارند:


Authorization: Bearer <raw_key>

curl


curl https://api.plexit.ir/v1/assistants \
  -H "Authorization: Bearer pk_live_8f2a3d9c1b7e4f6a0d2c5b8e1a4f7d9c"

Node.js


const res = await fetch("https://api.plexit.ir/v1/assistants", {
  headers: {
    Authorization: `Bearer ${process.env.PLEXIT_API_KEY}`,
  },
});
const { data } = await res.json();

Python


import os
import requests
 
res = requests.get(
    "https://api.plexit.ir/v1/assistants",
    headers={"Authorization": f"Bearer {os.environ['PLEXIT_API_KEY']}"},
)
data = res.json()["data"]

پاسخ ۴۰۱ عمداً کلی و مبهم است

API برای HTTP 401 — بدنه‌ی {"data": null, "response": {"status": "bad_request", "message": "کلید API نامعتبر یا باطل‌شده است"}} — با دقیقاً همان کلید پیام، api_key.invalid، برای هر یک از حالت‌های خطای زیر بازمی‌گردد:

هدر ارسال نشده باشد
کلید وجود نداشته باشد
کلید نادرست/بدشکل باشد
کلید باطل شده باشد
حسابِ متعلق به آن کلید حذف شده باشد

این یک طراحی عمدی است، نه یک اشکال یا سهل‌انگاری — از این جلوگیری می‌کند که یک مهاجم (یا یک اسکریپت معیوب) بتواند از متن پیام خطا برای شمارش کلیدهای موجود یا استنباط وضعیت حساب استفاده کند. منطقی نسازید که بر اساس متن پیام ۴۰۱ شاخه‌بندی می‌شود تا این حالت‌ها را از هم تشخیص دهد؛ از دید بیرون، این حالت‌ها عمداً غیرقابل‌تشخیص هستند. اگر در زمان توسعه نیاز دارید بدانید چرا یک درخواست شکست می‌خورد، به‌جای استنباط از خطای API عمومی، وضعیت کلید را در صفحه‌ی «API و اتصال» کنسول بررسی کنید.

قالب کلید

کلیدهای خام به شکل pk_live_<base64url> هستند. کل رشته را مبهم (Opaque) در نظر بگیرید — آن را تجزیه نکنید، به طول یا مجموعه‌ی کاراکترهای آن فراتر از «این یک توکن Bearer است» تکیه نکنید؛ فقط پیشوند pk_live_ و keyPrefix نمایش‌داده‌شده در کنسول برای خواندن انسانی در نظر گرفته شده‌اند.