الحصول على مفتاح API

Kaleidr عبارة عن منصة واحدة وSDK واحد ونظام وصول واحد — للذكاء الاصطناعي والخرائط والتصميم، ويتم التحكم فيها بواسطة نطاقات الإمكانات. يأتي المفتاح في شكلين آمنين حسب المكان الذي يعمل فيه؛ وكلاهما ينتمي إلى المؤسسة نفسها ويتم احتساب الاستخدام على الحصة نفسها.

الشكل	البادئة	مكان التشغيل	ما الذي يفعله
Publishable (المتصفح)	kld_pk_live_…	داخل HTML وSDK و<kaleidr-map>	مقيد بالأصل وآمن للظهور في مصدر الصفحة. يستبدله SDK بجلسة قصيرة العمر أثناء التشغيل. لا يمكن استخدامه كمفتاح bearer للخادم أو لإدارة المفاتيح.
Server (الخلفية)	kld_sk_live_…	على خوادمك فقط	bearer كامل للاتصالات من خادم إلى خادم؛ مع قائمة IP اختيارية وحدود وانتهاء صلاحية. محظور في المتصفح (يُرفض بخطأ 403 server_key_in_browser).

تستمر مفاتيح kld_live_… القديمة الحالية في المصادقة دون أي تغيير.

ما الذي تسمح به كل خطة

هذه هي سياسة الخطة → النطاق × المنتج المرجعية. تتم مساواة هذا الجدول مع B2B_TIER_API_CAPABILITIES في @kaleidr/shared-types — وهو الثابت نفسه الذي يقرأه shared-api عند إنشاء المفتاح وinference-api عند تبادل الجلسة — عبر فحص CI لمنع الانحراف، بحيث لا يمكن لصف هنا أن يخالف بصمت ما تسمح به المنصة فعليًا.

الخطة	Publishable	Server	النطاقات المسموح بها	المنتجات المسموح بها
Free	نعم	— (403 free_plan_publishable_only)	maps	tile
Pro	نعم	نعم	ai, maps, design, vendor*	chat, editor, viewer, tile
Enterprise	نعم	نعم	ai, maps, design, vendor*	chat, editor, viewer, tile

* يتطلب vendor إقرارًا صريحًا لكل مفتاح (وإلا يظهر الخطأ 403 vendor_scope_requires_acknowledgement).

Viewer لا يحتاج إلى مفتاح أبدًا — معرّف المشاركة هو بيانات الاعتماد. يمكن لأي خطة (بما فيها Free) تضمين Viewer دون أي مفتاح. تمرير مفتاح إلى تضمين Viewer يُرفض باستخدام product_not_allowed.

السماح الفعلي = المفتاح المخزن × الخطة الحالية. إذا تم تخفيض مفتاح Pro إلى Free، يستبدله الخادم بجلسة بشكل Free — نطاق maps ومنتج tile فقط. توسيع مفتاح Free مجددًا يتطلب إنشاء مفتاح جديد في الخطة الأعلى، وليس تعديل المفتاح الحالي (راجع Errors — Key management).

مفاتيح الاختبار

يتوفر كلا الشكلين أيضًا بنسخة test (kld_pk_test_…, kld_sk_test_…).

مفتاح الاختبار ليس بيئة sandbox. فهو يصادق على API نفسه، ويستدعي النماذج نفسها، ويخصم من الحصة الشهرية نفسها مثل المفتاح الحي. هناك اختلافان فقط:

• يمكن إنشاء مفتاح publishable اختباري دون قائمة أصول مسموح بها، بينما لا يمكن ذلك للمفتاح الحي؛
• لا يمكن لمفتاح الاختبار تقديم بلاطات خريطة الأساس.

استخدم مفاتيح الاختبار لجعل حركة staging قابلة للتتبع وقابلة للإلغاء بشكل مستقل — وهذه هي قيمتها الحقيقية. لا تتعامل معها على أنها مجانية.

إنشاء مفتاح

1. سجّل الدخول وافتح API Keys ضمن حسابك (kaleidr.com/api-keys) — لمسؤولي المؤسسة فقط.
2. أنشئ مفتاحًا — سمّه واختر Browser (publishable) أو Server. في خطتي Pro وEnterprise يتم إنشاؤه مع كامل صلاحيات الخطة (ai, maps, design scopes؛ ومنتجات chat, editor, viewer, tile)؛ أما في Free فيكون مفتاح Browser مقيدًا بـ maps / tile ولا يتوفر خيار Server.
3. يجب تقييد مفتاح Browser الحي بواحد على الأقل من الأصول المسموح بها — يُرفض مفتاح publishable حي بدون أصول لأنه سيصبح سرًا دائمًا ظاهرًا في مصدر الصفحة.
4. انسخ قيمة kld_pk_live_… / kld_sk_live_… مرة واحدة — فهي تظهر مرة واحدة فقط ولا يتم عرضها مجددًا.

المتطلبان الأساسيان لكل تضمين

كلاهما غير موثق حاليًا في أي صفحة منتج، وكل واحد منهما يمكنه منفردًا إيقاف أول عملية تكامل.

1. قائمة الأصول المسموح بها

يتحقق تبادل الجلسة من ترويسة Origin للمتصفح مقابل قائمة الأصول المسموح بها للمفتاح. عدم التطابق يُرفض بخطأ 403 session_origin_mismatch. لا يرسل file:// أي Origin على الإطلاق — وهي الطريقة التي غالبًا ما يتم بها تجربة المقتطف المنسوخ لأول مرة — لذا قدّم كل تضمين يستخدم مفتاحًا عبر HTTP(S).

حدّث قائمة الأصول المسموح بها لمفتاح موجود باستخدام JWT من Cognito بصلاحية org-admin، وليس مفتاح المنصة نفسه:

PATCH /shared-api/api-keys/{key_id}
Authorization: Bearer {cognito_org_admin_jwt}
Content-Type: application/json

{ "allowed_origins": ["https://your.site", "https://staging.your.site"] }

يقوم PATCH بإبطال ذاكرة التخزين المؤقت للقطة المفتاح فورًا، كما أن إزالة أصل تنهي أيضًا الجلسات المرتبطة به بالفعل — فكل طلب جلسة يعيد التحقق من أصله مقابل allowed_origins الحالية للمفتاح، ولذلك يُرفض الطلب التالي من الأصل الذي تمت إزالته بدلًا من الانتظار حتى انتهاء TTL. أما إضافة أصل فتعمل بالعكس: تسمح بجلسات جديدة، ولا تربط الجلسات الحالية بأثر رجعي.

2. CSP الخاص بالعميل

يجب أن تسمح Content Security Policy الخاصة بصفحتك بالموارد التي يقوم كل منتج بتحميلها. راجع Content Security Policy لإعداد خاص بكل منتج — يضيف Tile وViewer فقط محمّل SDK ومضيف iframe واحد؛ بينما يحتاج Chat وEditor أيضًا إلى 'wasm-unsafe-eval' ومضيفي مزود الخريطة لأن MapLibre يعمل في المستند الأصل.

الاستخدام

في المتصفح، مرر مفتاح publishable وسيقوم SDK باستبداله بجلسة قصيرة العمر:

<kaleidr-map product="tile"
             publishable-key="kld_pk_live_…"
             style-id="kaleidr-morning"
             style="height:480px"></kaleidr-map>

من الخادم، أرسل مفتاح server كـ bearer:

Authorization: Bearer kld_sk_live_…

يقوم المفتاح بالمصادقة باعتباره مؤسستك. يتم احتساب الاستخدام مقابل الحصة الشهرية للمؤسسة. راجع Auth & scopes لمعرفة ما يفتحه كل نطاق، و CORS & allowed origins لمعرفة قائمة أصول المتصفح التي تتحكم في كل تبادل جلسة.