احراز هویت

یک هدر روی هر درخواست، و این‌که اگر اشتباه باشد چه می‌شود.

هر درخواست کلید محرمانهٔ شما را در یک هدر با خود می‌آورد. چیزی برای تبادل یا تازه‌سازی وجود ندارد و خبری از جریان OAuth نیست — کلید تمام ماجراست.

هدر

کلید محرمانه را در هر درخواست با نام X-API-Key بفرستید:

X-API-Key: sk_…

API خود کنسول به‌جای این، از JWT با هدر bearer استفاده می‌کند. این دو کاملاً جدا هستند: JWT روی /v1 احراز هویت نمی‌شود و این کلید هم روی مسیرهای کنسول کار نمی‌کند.

این هدر در CORS مجاز است، پس مرورگر از نظر فنی می‌تواند بفرستدش. این نتیجهٔ فهرست هدرهای مجاز است، نه دعوت به انجامش — در صفحهٔ کلیدهای API می‌خوانید چرا نباید این کار را بکنید. کلید ابزارک (pk_…) اینجا پذیرفته نمی‌شود.

بررسی این‌که کار می‌کند

ارزان‌ترین راه بررسی کلید محرمانه، گرفتن فهرست فضاهای کاری است. کلید سالم پاسخ ۲۰۰ با status برابر ok می‌دهد، حتی اگر هنوز هیچ فضای کاری نداشته باشید:

cURL

JavaScript

Python

curl "https://api.daneshyar.info/api/v1/workspaces/" \
  -H "X-API-Key: sk_9f3aC2xQ7mB1vT8sE4nK6pR0jY5wZ2hL"

وقتی احراز هویت شکست می‌خورد

نبود کلید و نامعتبر بودن کلید هر دو ۴۰۳ برمی‌گردانند، نه ۴۰۱. این بیشتر کلاینت‌ها را غافلگیر می‌کند، پس روی ۴۰۳ شرط بگذارید، نه دنبال ۴۰۱ بگردید:

403 — هدر X-API-Key اصلاً فرستاده نشده
403 — کلیدی که با کلید محرمانهٔ هیچ اپی مطابقت ندارد — از جمله کلید ابزارک (pk_…)
404 — کلید معتبر، اما فضای کاری متعلق به اپ دیگری

403

{
  "detail": "Invalid API key"
}

404

{
  "status": "failed",
  "message": "Workspace not found"
}

به دو شکل بدنهٔ پاسخ توجه کنید. خطاهای احراز هویت از خود فریم‌ورک می‌آیند و فیلد detail دارند؛ بقیه از لایهٔ خود سرویس می‌آیند و status و message دارند. هر دو را بخوانید، به همین ترتیب.