المصادقة والنطاقات

تحمل كل مكالمة إلى واجهة برمجة تطبيقات منصة Kaleidr بيانات اعتماد واحدة. توجد ثلاثة أنواع، وتتعامل واجهة البرمجة مع كل نوع بطريقة مختلفة:

يعرّف المفتاح القابل للنشر مؤسستك داخل المتصفح. ولا يمكنه استدعاء واجهة البرمجة مباشرةً؛ بل يُستبدل برمز جلسة.
رمز الجلسة هو بيانات الاعتماد التي يستخدمها المتصفح فعليًا لاستدعاء واجهة البرمجة. وهو قصير العمر ومرتبط بمصدر موقع ويب واحد ومنتج واحد.
مفتاح الخادم سرّ يرسله خادمك الخلفي مباشرةً مع كل طلب.

توضح هذه الصفحة كيفية إرسال كل نوع من بيانات الاعتماد، وشكل عملية الاستبدال، وما الذي تتيحه نطاقات الصلاحية، وكيفية منح نطاق vendor، وجميع أخطاء المصادقة وأسبابها وطرق إصلاحها. لمعرفة ما يمكن فعله بكل بيانات اعتماد في حال تسربها، راجع نموذج الأمان.

أنواع بيانات الاعتماد

بيانات الاعتماد	البادئة	مكان وجودها	كيفية استخدامها	الخطة
مفتاح قابل للنشر	`kld_pk_live_…`	مصدر الصفحة	يُرسل مرة واحدة إلى عملية استبدال الجلسة؛ ويُرفض في جميع نقاط النهاية الأخرى	Free وPro وEnterprise
رمز الجلسة	`kld_sess_live_…`	ذاكرة المتصفح	يُرسل مع كل استدعاء وقت التشغيل من الصفحة التي أُنشئ لها	يُنشأ من مفتاح قابل للنشر أو خريطة منشورة
مفتاح الخادم	`kld_sk_live_…`	خادمك الخلفي فقط	يُرسل مع كل استدعاء وقت التشغيل؛ ويُرفض إذا حمل الطلب ترويسة `Origin`	Pro وEnterprise
مفتاح قديم	`kld_live_…`	خادمك الخلفي	يعمل بوصفه بيانات اعتماد مباشرة، مثل مفتاح الخادم. وينتج عن تدويره مفتاح خادم	المفاتيح الموجودة مسبقًا فقط

تحمل المفاتيح المنشأة عبر واجهة برمجة إدارة المفاتيح مع environment: "test" القيمة test بدلًا من live (kld_pk_test_… وkld_sk_test_…). ولا يستطيع مفتاح الاختبار تحميل مربعات خرائط الأساس.

يُعرض المفتاح كاملًا مرة واحدة فقط عند إنشائه أو تدويره. لا تحتفظ Kaleidr إلا بقيمة تجزئة له، لذلك لا يمكن استرداد مفتاح مفقود؛ عليك تدويره.

إرسال بيانات الاعتماد

أرسل بيانات الاعتماد في أيٍّ من الترويستين. تُقبل كلتاهما في جميع نقاط النهاية.

Authorization: Bearer kld_sk_live_…

X-Api-Key: kld_sk_live_…

إذا احتوى الطلب على الترويستين، تُستخدم Authorization عندما تبدأ قيمتها ببادئة Kaleidr؛ وإلا تُقرأ X-Api-Key. لا تضع مفتاح خادم في عنوان URL مطلقًا.

ما يستطيع كل نوع من بيانات الاعتماد فعله في نقطة نهاية لوقت التشغيل (أي جميع النقاط باستثناء استبدال الجلسة):

بيانات الاعتماد	النتيجة عند نقطة نهاية لوقت التشغيل
مفتاح قابل للنشر	401 `publishable_requires_session`. استبدله بجلسة أولًا.
مفتاح خادم دون ترويسة `Origin`	يُقبل، ثم تُفحص قائمة عناوين IP المسموح بها، ونطاق الصلاحية، والمنتجات المسموح بها، والحصة، وحدّ معدل الطلبات.
مفتاح خادم مع ترويسة `Origin`	403 `server_key_in_browser`. تضيف المتصفحات `Origin` إلى الطلبات العابرة للمواقع؛ وبهذا تتعرف واجهة البرمجة على مفتاح خادم مستخدم داخل صفحة ويب.
رمز جلسة من المصدر الذي أُنشئ له	يُقبل.
رمز جلسة مع `Origin` مختلف	403 `session_origin_mismatch`.
رمز جلسة من خريطة منشورة دون `Origin`	403 `session_origin_mismatch`.

تُطبّق حزمة تطوير JavaScript القاعدة نفسها قبل ذلك: ترفض Kaleidr.mount مفتاحًا يبدأ بـ kld_sk_… داخل المتصفح من دون إرسال أي طلب.

تبادل الجلسة

يُستبدل المفتاح القابل للنشر برمز جلسة عند نقطة نهاية واحدة. تنفذ حزمة التطوير هذه العملية لكل تركيب يستخدم مفتاحًا، وتحافظ على صلاحية الرمز؛ ولا تحتاج إلى استدعائها بنفسك إلا عند إنشاء عميل متصفح خاص بك.

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions
X-Api-Key: kld_pk_live_…
Content-Type: application/json

{ "product": "chat" }

الحقل product مطلوب ويجب أن تكون قيمته إحدى chat أو editor أو viewer أو tile. يجب أن يتضمن الطلب ترويسة Origin، ويضيفها المتصفح تلقائيًا.

{
  "session_token": "kld_sess_live_eyJhbGciOi…",
  "expires_in": 900,
  "product": "chat",
  "basemap_style_id": null
}

الحقل	المعنى
`session_token`	بيانات الاعتماد المستخدمة في استدعاءات وقت التشغيل. الصيغة `kld_sess_{env}_{token}`.
`expires_in`	مدة الصلاحية بالثواني. تستمر الجلسة المنشأة بمفتاح 900 ثانية. اقرأ هذا الحقل ولا تثبت الرقم في الشيفرة.
`product`	المنتج الذي ترتبط به الجلسة.
`basemap_style_id`	خريطة الأساس الافتراضية لمؤسستك، أو `null` إذا لم تُحدد واحدة.

القيود المرتبطة بالجلسة

مصدر واحد. هو قيمة Origin في طلب الاستبدال. ويُرفض الاستدعاء من أي مصدر آخر.
منتج واحد. لا يمكن لجلسة tile استدعاء نقاط نهاية الدردشة.
مجموعة محدودة من نطاقات الصلاحية. تحمل الجلسة النطاق الذي يحتاج إليه منتجها فقط: ai للدردشة، وdesign للمحرر، وmaps للمربعات، ولا نطاق للعارض. تحتفظ جلسة الدردشة أيضًا بـ vendor إذا كان المفتاح يملكه وكانت خطتك تسمح به (Enterprise). ولا تحمل جلسة أي منتج آخر نطاق vendor.

التجديد

لا يستطيع العميل طلب مدة صلاحية أطول. أجرِ الاستبدال مجددًا قبل انتهاء expires_in. تجدّد حزمة التطوير الجلسة قبل انتهاء صلاحيتها بـ90 ثانية، وعندما تصبح علامة تبويب تعمل في الخلفية مرئية وكانت صلاحية الجلسة ستنتهي خلال 90 ثانية أو انتهت بالفعل، وكل 30 ثانية بعد إخفاق التجديد. وإذا فشل الاستبدال الأول، يفشل التركيب ولا تُعاد المحاولة.

تستهلك كل عملية استبدال مع product: "tile" تحميل خريطة واحدًا من حصة مؤسستك؛ أما استبدال المنتجات الأخرى فلا تكلفة له. وللاستبدال حدّ معدل طلبات مستقل لكل مفتاح، منفصل عن استدعاءات وقت التشغيل. راجع الحصص وحدود معدل الطلبات.

ترتيب عمليات التحقق

تتوقف عملية الاستبدال عند أول فحص يفشل:

الترتيب	الفحص	الإخفاق
1	المفتاح صالح	401 `Invalid or missing API key`
2	حد معدل عمليات استبدال المفتاح	429 `rate_limited`
3	المفتاح قابل للنشر	403 `publishable_key_required`
4	يحتوي الطلب على ترويسة `Origin`	403 `origin_required`
5	المصدر موجود في قائمة المصادر المسموح بها للمفتاح، إن وُجدت	403 `origin_not_allowed`
6	لا يستبعد تقييد المفتاح هذا المنتج	403 `product_not_allowed`
7	تتضمن خطتك هذا المنتج	403 `tier_capability_not_allowed`
8	يمتلك المفتاح نطاق الصلاحية الذي يحتاج إليه المنتج	403 `insufficient_scope`، أو `tier_capability_not_allowed` إذا امتلك المفتاح النطاق ولكن خطتك لم تعد تتضمنه
9	بالنسبة إلى `tile`: يتوفر تحميل خريطة	429 `map_load_quota_exceeded`

التجربة من الطرفية

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "X-Api-Key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"product":"chat"}'

يعمل ذلك لأن Origin ترويسة عادية يمكن لأي عميل خارج المتصفح ضبطها. ولهذا توصف قائمة المصادر المسموح بها بأنها وسيلة تحكم للمتصفح وليست سرًا؛ راجع CORS والمصادر المسموح بها.

يمكن لخريطة منشورة من Studio تفعّل لوحة Kaleidr AI الخاصة بها Control Tower أو Popup Window إتاحة الدردشة لزوارها من دون مفتاح في الصفحة. وبدلًا من ذلك، تستبدل الصفحة المعرّف العام للخريطة، والميزة التي تفتحها:

POST https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions
Content-Type: application/json

{ "share_id": "your-map-id", "feature": "control_tower" }

{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }

تُستخدم هذه الجلسة للدردشة فقط، وتحمل نطاق ai، وتستمر 300 ثانية، وتُحتسب تكلفتها على مؤسسة مالك الخريطة. ولا تحمل vendor مطلقًا. يجب استخدامها من الصفحة التي طلبتها؛ ويُرفض أي استدعاء دون Origin أو مع قيمة مختلفة. حالات الرفض هي:

الحالة	الرمز	السبب
403	`origin_required`	لا يحتوي الطلب على ترويسة `Origin`.
404	`not_found`	لا توجد خريطة منشورة ولا رابط مشاركة بهذا المعرّف، أو أُلغي نشر خريطة رابط المشاركة.
403	`chat_disabled`	لا يفعّل Kaleidr AI الخاص بالخريطة الميزة المطلوبة.
403	`origin_not_allowed`	الصفحة ليست ضمن نطاقات الخريطة المسموح بها.
403	`owner_has_no_organization`	مالك الخريطة لا ينتمي إلى مؤسسة يمكن تحميل التكلفة عليها.
403	`tier_capability_not_allowed`	خطة المالك لا تتضمن الدردشة.
429	`rate_limited`	عدد عمليات الاستبدال لهذه الخريطة أو من هذا العنوان كبير جدًا.

توضح صفحة Kaleidr AI على خريطة منشورة كيفية الإعداد.

النطاقات

يحمل كل مفتاح نطاقات صلاحية. وتحتاج كل مجموعة من نقاط النهاية إلى نطاق معين.

النطاق	ما يتيحه	من يحتاج إليه
`ai`	نقاط النهاية `/chat/` و`/retrieval/`	الدردشة، وأي خادم خلفي يستدعي نقاط نهاية الدردشة أو البحث
`design`	نقاط النهاية `/design/*`	جلسات المحرر، وأي خادم خلفي يستدعي نقاط نهاية التصميم
`maps`	جلسات خرائط الأساس	منتج Tile
`vendor`	لا يتيح أي نقطة نهاية بمفرده. بل يسمح لإجابات الدردشة باستخدام البيانات المنشورة الخاصة بمؤسستك.	الدردشة، عند رفع بياناتك

يحصل المفتاح الجديد على ai وmaps وdesign ما لم تطلب غير ذلك. وفي خطة Free، يحمل المفتاح دائمًا جميع صلاحيات Free: هذه النطاقات الثلاثة بالضبط والمنتجات الأربعة (chat وeditor وviewer وtile)، مهما كان المنتج المذكور في الطلب. ولا يُمنح vendor افتراضيًا أبدًا، ولا يمكن إنشاء مفتاح يحمله إلا لمؤسسة على خطة Enterprise.

يُرفض طلب إنشاء مفتاح يذكر نطاقًا أو منتجًا لا تتيحه خطتك مع الخطأ 403 tier_capability_not_allowed. ولا يُحذف أي عنصر من الطلب بصمت دون ظهور خطأ. ويحدث ذلك عمليًا عند طلب vendor في خطتي Free أو Pro.

تُثبّت نطاقات الصلاحية عند إنشاء المفتاح. لا يمكن تعديلها لاحقًا من أي نقطة نهاية أو إعداد، ويرث المفتاح الناتج عن التدوير هذه النطاقات باستثناء ما لم تعد خطتك الحالية تسمح به. لتغيير نطاقات مفتاح، أنشئ مفتاحًا جديدًا وألغِ القديم.

يتبع تدوير المفاتيح في Free قاعدة خطة Free. يحمل المفتاح البديل الناتج عن تدوير مفتاح قابل للنشر في خطة Free جميع صلاحيات Free (ai وmaps وdesign، والمنتجات الأربعة)، مهما كانت صلاحيات المفتاح السابق. ولا يمكن تدوير مفتاح خادم أو مفتاح قديم في Free؛ إذ يُرفض الطلب مع 403 free_plan_publishable_only.

تتحدد قدرات المفتاح بالحدود الأكثر تقييدًا بين المفتاح والخطة

يفحص كل طلب نطاقات الصلاحية والمنتجات المحفوظة في المفتاح مقارنة بما تتضمنه خطة مؤسستك اليوم. ولا يؤدي تغيير الخطة إلى تعديل المفتاح، لكنه يغيّر ما يستطيع المفتاح فعله:

insufficient_scope: لم يُمنح المفتاح نطاق الصلاحية أصلًا. الحل: استخدم مفتاحًا يحمل النطاق المطلوب.
tier_capability_not_allowed: يحمل المفتاح النطاق، لكن خطتك الحالية لا تتضمنه. الحل: غيّر الخطة.

يمثل vendor استثناءً من الحالة الثانية، لأنه لا يتيح نقطة نهاية. فلا يُرفض المفتاح الذي يحتفظ بـvendor إذا أصبحت خطته أقل من Enterprise؛ بل تنجح طلباته، لكن تُنشأ إجاباته من دون بياناتك.

يُسمح للمفتاح ذي قائمة المنتجات الفارغة باستخدام كل منتج تتضمنه خطتك. أما المفتاح الذي لا يحمل أي نطاق صلاحية فيُرفض في جميع نقاط النهاية.

منتج مسموح به لكل مفتاح

يقيّد allowed_products المفتاح ببعض المنتجات chat وeditor وviewer وtile. ويُطبَّق هذا القيد على جميع أنواع المفاتيح عند موضع استخدامها:

المفتاح	موضع التحقق من القيد	الرفض
مفتاح قابل للنشر	عند استبدال الجلسة، مقارنةً بقيمة `product` المطلوبة	403 `product_not_allowed`
مفتاح خادم أو مفتاح قديم	عند كل طلب لوقت التشغيل، مقارنةً بالمنتج الذي تنتمي إليه نقطة النهاية	403 `product_not_allowed`

تنتمي كل مجموعة من نقاط النهاية إلى المنتج الذي تحتاج نطاق صلاحيته:

نقاط النهاية	النطاق	المنتج الذي يجب أن يسمح به المفتاح المقيّد
`/chat/`، `/retrieval/`	`ai`	`chat`
`/design/*`	`design`	`editor`

لذلك يُرفض مفتاح خادم أُنشئ مع "allowed_products": ["tile"] عند استدعاء /chat/control/stream بالخطأ 403 product_not_allowed رغم أنه يحمل نطاق ai. ولا يستطيع مفتاح خادم مقيّد بـviewer وحده استدعاء أي نقطة نهاية لوقت التشغيل، لأن الخريطة المنشورة لا تحتاج إلى مفتاح. اترك القائمة فارغة عندما تريد للمفتاح الوصول إلى جميع نقاط النهاية التي تسمح بها نطاقاته.

لا يُعاد فحص رمز الجلسة هنا؛ فقد ارتبط بمنتج واحد عند استبداله.

	Free	Pro	Enterprise
مفاتيح قابلة للنشر	نعم	نعم	نعم
مفاتيح الخادم	لا	نعم	نعم
`ai`، `maps`، `design`	نعم	نعم	نعم
`vendor`	لا	لا	نعم

تضيف خطة Pro مفاتيح الخادم وحدًا أعلى لعدد المفاتيح النشطة مقارنة بما توفره Free. يوجد جدول الخطط الكامل في الحصول على مفتاح API.

النطاق `vendor`

لا يتيح vendor أي نقطة نهاية، بل يحدد ما إذا كانت إجابة دردشة تستخدم هذا المفتاح تستطيع الاعتماد على البيانات المنشورة الخاصة بمؤسستك إلى جانب المعرفة العامة لدى Kaleidr. توضح صفحة بياناتك: نظرة عامة المسار الكامل من رفع البيانات إلى الإجابة.

من يمكنه استخدامه:

لا يمكن لخطتي Free وPro حمل vendor. ويُرفض طلب إنشاء مفتاح به مع 403 tier_capability_not_allowed سواء أُرسل vendor_acknowledged أم لا. ولن يُنشأ مفتاح.
يمكن لخطة Enterprise إنشاء مفاتيح تحمل vendor.

يتعلق نطاق الصلاحية بقراءة البيانات عبر مفتاح. أما رفع البيانات فهو إذن منفصل يمتلكه مالك المؤسسة أو مسؤولها، وليس أي مفتاح؛ وهو متاح لخطة Enterprise فقط أيضًا: لا تستطيع مؤسسات Free وPro رفع بيانات الأعمال. والملفات التي يضيفها مستخدم سجّل دخوله إلى خريطة في Kaleidr Studio هي ميزة أخرى متاحة لجميع الخطط، ولا يقرأها أي نطاق صلاحية؛ راجع مجموعات البيانات على الخريطة.

لا يمكن منح vendor من صفحة مفاتيح API. أنشئ المفتاح عبر واجهة برمجة إدارة المفاتيح:

curl -s https://api.kaleidr.com/shared-api/api-keys \
  -H "Authorization: Bearer $KALEIDR_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "store-locator-chat",
    "key_type": "publishable",
    "scopes": ["ai", "vendor"],
    "vendor_acknowledged": true,
    "allowed_origins": ["https://www.example.com"]
  }'

الحقل vendor_acknowledged: true مطلوب لمفتاح قابل للنشر يحمل vendor. وبدونه يفشل الطلب مع 422 vendor_scope_requires_acknowledgement. يوجد هذا الحقل لأن المفتاح القابل للنشر يظهر في مصدر صفحة عامة؛ ولذلك يستطيع أي زائر للصفحة قراءة البيانات التي يمكن للمفتاح الوصول إليها. أما مفتاح الخادم فلا يحتاج إلى إقرار.

قبل إضافة vendor إلى مفتاح قابل للنشر:

استخدم مفتاحًا واحدًا لكل موقع ويب. لا تمنح vendor إلا للموقع الذي يحتاج إلى الإجابة اعتمادًا على بياناتك.
اعتبر جميع بياناتك المنشورة متاحة للعامة في ذلك الموقع. ولا تنشر أسعار التكلفة أو الأسعار غير المعلنة أو أي معلومات لا ترغب في عرضها على الصفحة.
تذكّر أن الجلسات الجارية لا تكتسب النطاق الجديد. فالمفتاح المنشأ مع vendor يمنحه فقط للجلسات التي تُستبدل بعد ذلك.

لسحب vendor، ألغِ المفتاح وأنشئ بديلًا من دونه. يسري الإلغاء اعتبارًا من الطلب التالي، بما في ذلك الجلسات التي سبق إصدارها.

عندما تغادر المؤسسة خطة Enterprise

لا يؤدي الانتقال من Enterprise إلى Pro أو Free إلى تعديل مفاتيحك أو التسبب في فشلها:

العنصر	ما يحدث بعد الانتقال
مفتاح يحمل `vendor`	يستمر في العمل لجميع الاستخدامات الأخرى. لكن إجاباته لا تعتمد بعد الآن على بياناتك. ولا يوجد خطأ أو حالة أو حقل يبيّن ذلك.
جلسات المتصفح الصادرة قبل الانتقال	تُنهى. ويعيد طلبها التالي 401، ثم تحصل حزمة التطوير على جلسة جديدة لا تحمل `vendor`.
تدوير مفتاح يحمل `vendor`	في Pro: ينجح مع 201. ويحمل البديل نطاقات الصلاحية نفسها من دون `vendor`، مع بقاء قائمة المنتجات كما هي. في Free: يحمل بديل المفتاح القابل للنشر `ai` و`maps` و`design` والمنتجات الأربعة، مهما كانت صلاحيات القديم؛ ويُرفض تدوير مفتاح الخادم أو المفتاح القديم مع 403 `free_plan_publishable_only`.
إنشاء مفتاح يحمل `vendor`	يُرفض مع 403 `tier_capability_not_allowed`.
إصدارات بياناتك	يمكن للمالكين والمسؤولين الاستمرار في سرد الإصدارات وإلغاء نشرها وحذفها في أي خطة عبر واجهة برمجة الرفع. وفي Free وPro، يُرفض الرفع والنشر مع 403 `vendor_data_not_on_plan`.

عند العودة إلى Enterprise، يستعيد المفتاح الذي لا يزال يحتفظ بـvendor إمكانية الوصول إلى البيانات. أما المفتاح البديل الذي دُوِّر في الخطة الأدنى فلا يستعيد هذا النطاق؛ أنشئ مفتاحًا جديدًا.

تقييد مفتاح

التقييد	ينطبق على	يُضبط من صفحة مفاتيح API	يُضبط عبر واجهة برمجة إدارة المفاتيح	الرفض
المصادر المسموح بها	المفاتيح القابلة للنشر	نعم	نعم (`allowed_origins`)	403 `origin_not_allowed` عند الاستبدال
المنتجات المسموح بها	أي مفتاح	لا	نعم (`allowed_products`)	403 `product_not_allowed`: عند الاستبدال للمفتاح القابل للنشر، وعند كل طلب وقت تشغيل لمفتاح الخادم أو المفتاح القديم. راجع حدود المنتجات.
قائمة عناوين IP المسموح بها	مفاتيح الخادم والمفاتيح القديمة	لا	نعم (`allowed_ips`)	403 `ip_not_allowed`
الحد الشهري	أي مفتاح	لا	نعم (`monthly_cap_tokens`)	429 `quota_exceeded`
انتهاء الصلاحية	أي مفتاح	لا	نعم (`expires_at`)	401 بعد التاريخ المحدد
نطاقات الصلاحية	أي مفتاح	لا	عند الإنشاء فقط (`scopes`)	403 `insufficient_scope`

المصادر المسموح بها. حتى 100 إدخال، كل منها بالصيغة scheme://host[:port] من دون مسار. وتعني القائمة الفارغة في المفتاح القابل للنشر السماح بأي مصدر. التفاصيل وحالات الإخفاق موضحة في CORS والمصادر المسموح بها.

قائمة عناوين IP المسموح بها. حتى 100 عنوان IP أو كتلة CIDR. تُرفض الكتلة التي تطابق كل العناوين (/0)؛ اترك القائمة فارغة للسماح «بأي عنوان». وإذا كان للمفتاح قائمة وتعذّر تحديد عنوان الجهة المتصلة، يُرفض الطلب.

الحد الشهري. سقف لما يستطيع هذا المفتاح وحده استهلاكه من أرصدة الذكاء الاصطناعي لمؤسستك خلال فترة فوترة. راجع الحصص وحدود معدل الطلبات.

ما يسري على جلسة صادرة بالفعل

تعيد الجلسة قراءة مفتاحها الأصلي عند كل طلب، لذلك يسري سحب الوصول سريعًا. أما إضافة الوصول فتتطلب عملية استبدال جديدة.

التغيير في المفتاح أو الحساب	أثره على جلسة سبق إصدارها
إلغاء المفتاح أو تدويره دون فترة سماح	401 عند طلبها التالي.
إزالة مصدر الجلسة من مصادر المفتاح المسموح بها	401 عند طلبها التالي.
إزالة منتج الجلسة من منتجات المفتاح المسموح بها	401 عند طلبها التالي.
خفض مستوى الخطة	تحصل الجلسات الصادرة قبل الخفض على 401. أما الجلسات المستبدلة بعده فتحصل على 403 `tier_capability_not_allowed` للميزات التي لم تعد الخطة تتضمنها.
إضافة حد شهري أو خفضه	يُطبّق عند الطلب التالي.
إزالة الحد الشهري	يُطبّق اعتبارًا من الاستبدال التالي.
ترقية الخطة	تُطبّق اعتبارًا من الاستبدال التالي.

لأن مدة الجلسة بالدقائق، فإن عبارة «اعتبارًا من الاستبدال التالي» تعني انتظارًا قصيرًا. ويلتقط تجديد حزمة التطوير التغيير من دون تعديل الشيفرة.

واجهة برمجة تطبيقات إدارة المفاتيح

تتيح صفحة مفاتيح API في kaleidr.com/api-keys ضبط اسم المفتاح ونوعه ومصادره المسموح بها. ويُضبط كل ما تبقى في هذه الصفحة عبر واجهة البرمجة نفسها التي تستخدمها تلك الصفحة.

عنوان URL الأساسي: https://api.kaleidr.com/shared-api/api-keys
المصادقة: Authorization: Bearer مع رمز وصول لحساب Kaleidr مسجّل الدخول ويكون صاحبه مالكًا أو مسؤولًا في المؤسسة. لا يُقبل مفتاح المنصة هنا. ولا توجد حاليًا بيانات اعتماد منفصلة طويلة الأجل لإدارة المفاتيح.
المؤسسة: إذا لم تذكر مؤسسة، تُستخدم مؤسستك الأساسية. لتحديد مؤسسة أخرى، أرسل org_id في متن JSON عند إنشاء المفتاح، وبصفته معامل الاستعلام ?org_id= في جميع المسارات الأخرى. يُتجاهل معامل الاستعلام org_id في مسار الإنشاء.

الطريقة والمسار	الغرض	النجاح
`POST /`	إنشاء مفتاح	201، كائن المفتاح مع `plaintext_key`
`GET /`	سرد المفاتيح النشطة، الأحدث أولًا	200
`GET /{id}/events?limit=1..200`	أحداث التدقيق الخاصة بالمفتاح	200
`PATCH /{id}`	تغيير القيود	200، كائن المفتاح
`POST /{id}/rotate`	استبدال المفتاح	201، المفتاح الجديد مع `plaintext_key`
`POST /{id}/revoke`	إلغاء المفتاح	200، كائن المفتاح

لا يوجد مسار للحذف؛ ألغِ المفتاح لإيقاف استخدامه.

الحقول المقبولة عند إنشاء مفتاح:

الحقل	النوع	القيمة الافتراضية	ملاحظات
`name`	سلسلة نصية من 1 إلى 200 حرف	مطلوب
`org_id`	UUID	مؤسستك الأساسية	المؤسسة التي يُنشأ فيها المفتاح. يُرسل في متن الطلب؛ ويُتجاهل معامل الاستعلام في هذا المسار.
`key_type`	`"publishable"` أو `"server"`	`"publishable"`	تُرفض القيمة `"server"` في Free مع 403 `free_plan_publishable_only`.
`environment`	`"live"` أو `"test"`	`"live"`
`scopes`	مصفوفة سلاسل نصية	`["ai", "maps", "design"]`	من `ai` و`maps` و`design` و`vendor`. أي قيمة أخرى تؤدي إلى 422 `unknown_scope`. والنطاق الذي لا تسمح به خطتك (`vendor` دون Enterprise) يؤدي إلى 403 `tier_capability_not_allowed`.
`allowed_origins`	مصفوفة سلاسل نصية حتى 100	`[]`	تعني القائمة الفارغة السماح بأي مصدر للمفتاح القابل للنشر.
`allowed_products`	مصفوفة سلاسل نصية	`[]`	من `chat` و`editor` و`viewer` و`tile`. تعني القائمة الفارغة جميع المنتجات. أي قيمة أخرى تؤدي إلى 422 `unknown_product`. يُطبّق على المفاتيح القابلة للنشر ومفاتيح الخادم والمفاتيح القديمة؛ راجع حدود المنتجات.
`allowed_ips`	مصفوفة سلاسل نصية حتى 100	`[]`	عناوين IP أو كتل CIDR.
`monthly_cap_tokens`	عدد صحيح لا يقل عن 0	لا يوجد	القيمة 1 أو أكثر تفرض حدًا على المفتاح. وتعني `0` أو `null` عدم وجود حد.
`expires_at`	تاريخ ووقت في المستقبل	لا يوجد
`vendor_acknowledged`	قيمة منطقية	`false`	مطلوب لمفتاح قابل للنشر يحمل `vendor` (Enterprise).

يقبل PATCH الحقول name وallowed_origins وallowed_products وallowed_ips وmonthly_cap_tokens وexpires_at. أرسل الحقول التي تريد تغييرها فقط؛ وتمسح قيمة null الصريحة الحقل. ولا يقبل scopes.

يقبل rotate القيمة { "grace_hours": 0 } من 0 إلى 8760. ويرث المفتاح البديل نطاقات صلاحية المفتاح القديم، باستثناء أي نطاق لم تعد خطتك الحالية تسمح به. وفي Free، يحمل البديل دائمًا كل صلاحيات Free، ولا يمكن تدوير مفتاح خادم أو مفتاح قديم (403 free_plan_publishable_only). وعند اختيار 0، يتوقف المفتاح القديم وجلساته فورًا. أما مع فترة سماح، فيظل المفتاح القديم يعمل حتى نهايتها، ويظل محسوبًا ضمن حد المفاتيح النشطة لخطتك، ولا يمكن تدويره مرة ثانية. تستخدم صفحة مفاتيح API فترة سماح مدتها 24 ساعة.

أخطاء هذه المسارات مدرجة في الأخطاء: إدارة المفاتيح.

أخطاء المصادقة

تعني 401 أن واجهة البرمجة لا تقبل بيانات الاعتماد إطلاقًا. وتعني 403 أنها تعرف هويتك لكنها ترفض الطلب. وتأتي جميعها بالصيغة {"detail": "<code>"}.

في المتصفح، لا تحمل الاستجابة للطلب المرفوض بسبب بيانات الاعتماد أو المصدر ترويسة CORS، لذا ترى الصفحة خطأ CORS بدل متن الاستجابة. أما الرفض اللاحق بسبب النطاق أو الخطة، فيمكن قراءته، وتُبلغ حزمة التطوير عن kaleidr session exchange failed (403). في الحالتين، افتح الطلب في علامة التبويب Network بأدوات المتصفح لقراءة الرمز. راجع CORS والمصادر المسموح بها.

الحالة	الرمز	السبب	الحل
401	`Invalid or missing API key`	عدم إرسال بيانات اعتماد؛ أو مفتاح غير معروف أو ملغى أو منتهي الصلاحية؛ أو جلسة منتهية؛ أو جلسة أُلغي مفتاحها أو فقد مصدرها أو منتجها، أو صَدرت قبل خفض الخطة؛ أو مؤسسة معلّقة أو من دون خطة.	تحقّق من قيمة المفتاح وحالته في صفحة مفاتيح API. وبالنسبة إلى الجلسة، أجرِ الاستبدال مجددًا.
401	`publishable_requires_session`	أُرسل مفتاح قابل للنشر إلى نقطة نهاية لوقت التشغيل.	استبدله بجلسة، أو أرسل الاستدعاء من خادم خلفي باستخدام مفتاح خادم.
403	`publishable_key_required`	استُدعيت عملية استبدال الجلسة بمفتاح خادم أو مفتاح قديم.	استخدم مفتاحًا يبدأ بـ `kld_pk_…` عند الاستبدال.
403	`origin_required`	عملية استبدال جلسة بلا ترويسة `Origin`.	أرسل الاستدعاء من صفحة متصفح.
403	`origin_not_allowed`	مصدر الصفحة غير موجود في مصادر المفتاح المسموح بها، أو ليس ضمن النطاقات المسموح بها للخريطة المنشورة.	أضف المصدر المطابق تمامًا إلى المفتاح، أو النطاق إلى الخريطة.
403	`product_not_allowed`	المنتجات المسموح بها للمفتاح لا تتضمن هذا المنتج: قيمة `product` المطلوبة عند الاستبدال، أو المنتج الذي تنتمي إليه نقطة النهاية عند استخدام مفتاح خادم أو مفتاح قديم.	غيّر `allowed_products` أو استخدم مفتاحًا آخر.
403	`insufficient_scope`	أُنشئ المفتاح دون النطاق الذي تحتاج إليه نقطة النهاية أو المنتج.	استخدم مفتاحًا يحمل النطاق؛ فلا يمكن تعديل النطاقات.
403	`tier_capability_not_allowed`	يحمل المفتاح النطاق أو المنتج لكن خطتك الحالية لا تتضمنه.	غيّر الخطة في kaleidr.com/billing.
403	`server_key_in_browser`	أُرسل مفتاح خادم مع ترويسة `Origin`.	انقل الاستدعاء إلى خادمك الخلفي. وإذا كان المفتاح ظاهرًا في مصدر الصفحة، فدوّره.
403	`session_origin_mismatch`	استُخدم رمز جلسة من مصدر مختلف عن الذي أُنشئ له، أو استُخدمت جلسة خريطة منشورة دون `Origin`.	استبدل الجلسة من الصفحة التي ستستخدمها.
403	`ip_not_allowed`	استُخدم مفتاح خادم أو مفتاح قديم مع قائمة عناوين IP مسموح بها من عنوان خارجها.	أرسل الاستدعاء من عنوان مسموح، أو غيّر `allowed_ips`.
403	`chat_disabled`	استبدال خريطة منشورة: لا يفعّل Kaleidr AI الخاص بالخريطة الميزة المطلوبة.	فعّل Control Tower أو Popup Window في لوحة Kaleidr AI الخاصة بالخريطة في Studio.
403	`owner_has_no_organization`	استبدال خريطة منشورة: لا ينتمي مالك الخريطة إلى مؤسسة.	يجب على المالك إنشاء مؤسسة أو الانضمام إليها.
404	`not_found`	استبدال خريطة منشورة: لا توجد خريطة منشورة ولا رابط مشاركة بهذا المعرّف.	تحقّق من المعرّف ومن نشر الخريطة.

توجد القائمة الكاملة، بما في ذلك استجابات 429 و5xx، في الأخطاء.

موضوعات ذات صلة

نموذج الأمان: ما يمكن فعله بكل نوع من بيانات الاعتماد إذا تسرّب.
CORS والمصادر المسموح بها: كيفية تطبيق قائمة المصادر.
نقاط النهاية: ما الذي يسمح كل نطاق صلاحيّة باستدعائه.
الحصول على مفتاح API: إنشاء مفتاح من صفحة مفاتيح API.

أنواع بيانات الاعتماد​

إرسال بيانات الاعتماد​

تبادل الجلسة​

القيود المرتبطة بالجلسة​

التجديد​

ترتيب عمليات التحقق​

التجربة من الطرفية​

جلسات الخريطة المنشورة​

النطاقات​

تتحدد قدرات المفتاح بالحدود الأكثر تقييدًا بين المفتاح والخطة​

منتج مسموح به لكل مفتاح​

النطاق vendor​

عندما تغادر المؤسسة خطة Enterprise​

تقييد مفتاح​

ما يسري على جلسة صادرة بالفعل​

واجهة برمجة تطبيقات إدارة المفاتيح​

أخطاء المصادقة​

موضوعات ذات صلة​