إنشاء دور
اسم وقائمة أذونات. وما يعود أطول مما أرسلت.
ينفّذ الاستدعاء الحقيقي على مساحة عملك، بمفتاحك أنت.
POST /roles
اسم وقائمة أذونات. وما يعود أطول مما أرسلت.
مثال
يتطلب roles:write. يُعيد 201. والدور المخصص هو builtin: null وeditable: true وdeletable: true، ولا يحمله أحد حتى يُنقَل إليه شخص ما.
curl -X POST "$OE/roles" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": ["emails:send", "threads:write", "labels:write", "contacts:read"] }'{ "object": "role", "id": "role_2b81de079c1f0a4b7e05d386", "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": [ "emails:send", "emails:read", "threads:read", "threads:write", "labels:read", "labels:write", "contacts:read" ], "builtin": null, "editable": true, "deletable": true, "members": 0, "apiKeys": 0, "createdAt": "2026-08-30T10:41:02.000Z", "updatedAt": "2026-08-30T10:41:02.000Z"}أربعة أذونات دخلت وسبعة عادت. emails:send يستلزم emails:read، وthreads:write يستلزم threads:read، وlabels:write يستلزم labels:read. والدور الذي يُسمح له بأرشفة سلسلة لا يستطيع فتحها هو مربع اختيار نسيه أحدهم لا سياسة يقصدها أحد، ولذلك يُخزَّن الاستلزام بدل أن يُرفَض. كما تعود القائمة بالترتيب المعياري، وهو ما يتيح للعميل أن يقارن دورين كـ JSON ويقرر هل يُفعَّل زر الحفظ.
الإذن المجهول يُرفَض هنا بدل أن يُسقَط: فـ templates:writ هو invalid_parameter، وهو 422، يسمّي السلسلة. الخدمة تُطبِّع بصمت لأنها أيضًا مسار الزرع ومسار MCP، حيث إفشال دور كامل بسبب كلمة واحدة غير معروفة سيكون أسوأ. لكنه خطأ في نداء صنعه شخص عن قصد. فالرمز 200 الذي يحمل دورًا لا يستطيع تحرير القوالب لم يقل لهم شيئًا، وسيقضون الظهيرة عليه.
الاسم المكرر على مساحة العمل نفسها هو role_name_taken، وهو 409. والدور المخصص الخامس والعشرون هو role_limit_reached، وهو 422. وهو يحرس حجم المصفوفة قبل أن يعجز الجميع عن تدقيقها، وليس حدًّا من حدود الخطة.
إنشاء دور لا يعطيه لأحد. نقل الناس إليه يتم بـ PATCH /members/{userId}، وتوجيه مفتاح إليه يتم حيث يُصدَر المفتاح.