Me API

يخبر GET /me المستدعي بهويته: في أي مؤسسة ومساحة عمل تعمل بيانات الاعتماد، وأي منطقة تخدمها، وما عنوان API الأساسي الذي يجب استدعاؤه، ونوع بيانات الاعتماد، والصلاحيات التي تحملها الآن. يعمل مع كل أنواع بيانات الاعتماد - مفتاح API أو جلسة لوحة التحكم أو رمز وصول OAuth - ولا يحتاج إلى صلاحية معيّنة، لذا فهو الاستدعاء الطبيعي "لاختبار الاتصال".

جميع نقاط النهاية في هذه الصفحة نسبية إلى العنوان الأساسي: https://api-eu1.joryio.com/api - راجع نظرة عامة على API.

الحصول على المستدعي

GET /me

curl https://api-eu1.joryio.com/api/me \
  -H "Authorization: Bearer jry_live_your_api_key"

الاستجابة 200:

{
  "organization": { "id": "8f0c2c1e-3b0a-4d2e-9a51-0f6f4d1c2b11", "name": "Acme" },
  "workspace": { "id": "1d2e3f40-5a6b-4c7d-8e9f-a0b1c2d3e4f5", "name": "Production" },
  "region": "eu1",
  "api_base_url": "https://api-eu1.joryio.com/api",
  "principal": {
    "type": "oauth",
    "client_kind": "integration",
    "client": "zapier",
    "email": "[email protected]",
    "name": "Dana Levi"
  },
  "scopes": ["events:track", "users:read", "users:write"]
}

الحقل	النوع	ملاحظات
organization	object	id وname للمؤسسة.
workspace	object أو null	مساحة العمل التي تعمل فيها بيانات الاعتماد. مفتاح API ورمز OAuth مرتبطان بمساحة عمل واحدة؛ أما جلسة لوحة التحكم فتستخدم الترويسة X-Workspace-Id وتحصل على null بدونها.
region	string	المنطقة التي تحتفظ بالبيانات، مثل eu1.
api_base_url	string	العنوان الأساسي لـ REST API في تلك المنطقة. استدعِه بدلًا من مضيف ثابت في الشيفرة.
principal	object	ماهية بيانات الاعتماد - انظر أدناه.
scopes	string[]	الصلاحيات التي يمكن لبيانات الاعتماد استخدامها الآن، مرتّبة.

أنواع Principal

principal.type	بيانات الاعتماد	حقول أخرى
api_key	مفتاح API	api_key_id، name (اسم المفتاح). scopes هي نطاقات المفتاح، بما فيها ما تشمله (مثلًا canvas:activate تشمل canvas:enter).
oauth	رمز وصول OAuth	client_kind (integration - مثل Zapier - أو mcp، وكيل ذكاء اصطناعي)، client (zapier لـ Zapier، وإلا اسم العميل)، وemail وname للشخص الذي ربطه. scopes هي ما تمت الموافقة عليه وما زال الشخص يملكه معًا.
user	جلسة لوحة التحكم	email، name؛ scopes هي صلاحيات الشخص في مساحة العمل.

OAuth للتكاملات

تتصل التكاملات مثل Zapier عبر "Sign in with Joryio" (OAuth 2.0 authorization code) بدلًا من لصق مفتاح API. يختار الشخص مساحة العمل والصلاحيات في صفحة موافقة من Joryio؛ ثم يعمل التكامل باسمه، في مساحة العمل تلك، في حدود ما سمح به وما زال يملكه. تسجّل Joryio عملاء التكامل - لا يوجد تسجيل ذاتي للعملاء.

نقاط نهاية OAuth موجودة على المضيف المحايد للمنطقة connect.joryio.com، الذي يمرّر كل طلب إلى المنطقة التي أصدرت الرمز أو الشيفرة:

الخطوة	نقطة النهاية
التفويض (المتصفح)	GET https://connect.joryio.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=...&scope=...&state=...
الرمز	POST https://connect.joryio.com/oauth/token
الإلغاء	POST https://connect.joryio.com/oauth/revoke

• مصادقة العميل: client_secret_basic (HTTP Basic) أو client_secret_post (client_id وclient_secret في نص النموذج). PKCE (S256) اختياري ويُفرض عند إرساله.
• Redirect URI: يجب أن يطابق تمامًا أحد العناوين المسجّلة للعميل.
• استجابة الرمز: access_token، refresh_token، token_type، expires_in، scope، إضافة إلى api_base_url (استدعِ API هناك) وregion.
• رموز الوصول صالحة لمدة ساعة. يحصل الرمز المنتهي على 401؛ جدّد الرمز وأعد المحاولة.
• رموز التحديث تتبدّل مع كل استخدام وتبقى صالحة ما دام الاتصال مستخدمًا - وتنتهي بعد 180 يومًا دون أي استخدام. عمليتا تحديث بالرمز نفسه خلال 60 ثانية (خطوات متوازية) تحصلان كلتاهما على الزوج الجديد نفسه؛ أما رمز تم تبديله ويُقدَّم لاحقًا فينهي الاتصال.
• النطاقات التي يمكن للتكامل طلبها: users:read، pii:view (اختياري، انظر أدناه)، users:write، events:read، events:track، lists:read، subscriptions:read، segments:read، subscriptions:write، canvas:enter، hooks:manage.
• الصلاحيات الضمنية: لا يحصل رمز OAuth أبدًا على users:export أو users:merge أو users:alias عبر نطاق آخر (يتضمنها segments:read وusers:write للأدوار ومفاتيح API، لا لـ OAuth). يبقى تصدير جهات الاتصال بالجملة والدمج وتغيير الأسماء البديلة للأدوار ومفاتيح API.
• البيانات الشخصية (pii:view، اختياري): بدونه يحصل التكامل على معرّفات جهات الاتصال فقط - يعيد GET /users وبقية قراءات جهات الاتصال الحقول email وphone وexternalId بقيمة null ويخفي السمات المعلَّمة كبيانات شخصية (والأسماء)، ولا تحمل تسليمات webhook إلا contact.id. ومعه تحمل البريد الإلكتروني والهاتف والمعرّف الخارجي لجهة الاتصال. لا يسري إلا ما دام الشخص الذي أنشأ الاتصال يملك أيضًا pii:view في مساحة العمل، ويُتحقق منه عند كل طلب وكل تسليم: فقدانه يخفي البيانات في التالي. تعرضه صفحة الموافقة بعنوان "عرض عنوان البريد الإلكتروني ورقم الهاتف لجهات الاتصال"، غير محدد افتراضيًا، ولمن يملك pii:view فقط؛ ومن لا يملكه يُبلَّغ بأن التطبيق سيحصل على معرّفات جهات الاتصال فقط، ويظل بإمكانه الاتصال. لا يمنحه أي نطاق آخر، بما في ذلك users:read. ولا يمكن لوكلاء الذكاء الاصطناعي (MCP) طلبه.
• قطع الاتصال: يزيل الشخص الاتصال من الإعدادات > عام > التطبيقات المتصلة؛ وتتوقف كل رموز الاتصال عن العمل فورًا.