# مفتاح API في مُجيب، إنشاؤه وإرساله وإلغاؤه

> مفتاح API هو ما يفتح واجهة مُجيب البرمجية لنظامك. أنشئه من صفحة التكاملات، واختر صلاحياته ومدته، وأرسله في ترويسة Authorization مع كل طلب.

مفتاح API هو كلمة سرّ طويلة يرسلها برنامجك مع كل طلب إلى واجهة مُجيب البرمجية، فيعرف مُجيب أي نشاط يطلب وما الذي يحق له أن يقرأه. تنشئه من صفحة «التكاملات»، ويبدأ دائمًا بـ `mjb_live_`، ويُرسَل في الترويسة `Authorization`.

يتكوّن المفتاح من `mjb_live_` يليها 32 حرفًا عشوائيًا. كل مفتاح للقراءة فقط، وله صلاحيات تختارها، ويمكنك إلغاؤه في أي وقت.

## كيف أنشئ مفتاح API؟

تنشئ المفتاح من قسم «للمطوّرين» في صفحة «التكاملات»، ولا يراه إلا «المالك» و«مدير».

1. افتح «التكاملات» من القائمة الجانبية.
2. اضغط بطاقة «مفاتيح API»، فيفتح قسم «للمطوّرين» أسفل الصفحة.
3. اضغط «مفتاح جديد».
4. في خانة «اسم المفتاح» اكتب اسمًا يدل على النظام الذي سيستخدم المفتاح، مثل «تقارير المبيعات».
5. تحت «شو بيقدر يقرأ» اختر «قراءة العملاء» أو «قراءة الحجوزات» أو كليهما.
6. في «بينتهي» اختر «بعد 90 يوم» أو «بعد سنة» أو «ما بينتهي».
7. اضغط «اعمل المفتاح». يظهر المفتاح تحت عنوان «هذا مفتاحك — بيبين هالمرة بس»، فاضغط «انسخ المفتاح» واحفظه في مكان آمن، ثم اضغط «خلصت، نسخته».

![نافذة مفتاح API جديد فيها اسم المفتاح وصلاحيتا القراءة ومدة الانتهاء](https://docs.mujib.ai/shots/ar/api-key-new.webp "كُتب اسم للمفتاح وعُلِّمت «قراءة العملاء» و«قراءة الحجوزات» معًا، وتحت «بينتهي» قائمة مدة الانتهاء، أما زر «اعمل المفتاح» فلم يُضغط.")

> **يظهر المفتاح مرة واحدة**
>
> لا يحتفظ مُجيب بالمفتاح نفسه، بل ببصمته فقط، فلا يستطيع أحد أن يعرضه بعد إغلاق النافذة، ولا فريق مُجيب. انسخه قبل أن تغلق، وإذا ضاع فألغِه وأنشئ غيره.
بعد الإنشاء يظهر المفتاح في القائمة باسمه، وبتلميح فيه `mjb_live_…` وآخر أربعة أحرف منه، وبصلاحياته، وبوقت آخر استعمال أو «ما انستعمل لهلّق»، وبتاريخ انتهائه.

## ما الصلاحيات التي يمكن أن يحملها المفتاح؟

للمفتاح صلاحيتان فقط، وكلتاهما للقراءة: `contacts.read` لقراءة العملاء، و`bookings.read` لقراءة الحجوزات. لا توجد صلاحية تغيّر أو تحذف شيئًا.

| الصلاحية | اسمها في لوحة التحكم | الطلبات التي تفتحها |
| --- | --- | --- |
| `contacts.read` | «قراءة العملاء» | `GET /api/v1/contacts` و`GET /api/v1/contacts/{id}` |
| `bookings.read` | «قراءة الحجوزات» | `GET /api/v1/bookings` و`GET /api/v1/bookings/{id}` |

- الطلب `GET /api/v1/me` لا يحتاج إلى صلاحية، فيعمل بأي مفتاح صالح.
- المفتاح الذي ينقصه ما يحتاجه الطلب يتلقى الخطأ 403 ورمز `FORBIDDEN`.
- يظهر خيار «قراءة الحجوزات» فقط إذا كان نشاطك يستخدم المواعيد.
- اختر أقل ما يحتاجه نظامك: نظام التقارير الذي يعدّ الحجوزات لا يحتاج إلى أرقام العملاء.

## كيف أرسل المفتاح مع الطلب؟

أرسل المفتاح في الترويسة `Authorization` بصيغة `Bearer`، مع كل طلب. احفظه في متغير بيئة ولا تكتبه في الكود.

```bash
export MUJIB_API_KEY="mjb_live_xxxxxxxx…"
curl https://api.mujib.ai/api/v1/me \
  -H "Authorization: Bearer $MUJIB_API_KEY"
```

```js
const res = await fetch('https://api.mujib.ai/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.MUJIB_API_KEY}` },
});
console.log(res.status, await res.json());
```

```python
import os
import requests

res = requests.get(
    "https://api.mujib.ai/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MUJIB_API_KEY']}"},
    timeout=30,
)
print(res.status_code, res.json())
```

وعلى Windows في PowerShell:

```powershell
$env:MUJIB_API_KEY = "mjb_live_xxxxxxxx…"
Invoke-RestMethod -Uri "https://api.mujib.ai/api/v1/me" -Headers @{ Authorization = "Bearer $env:MUJIB_API_KEY" }
```

- إذا كانت أداتك لا تستطيع ضبط `Authorization`، فأرسل المفتاح في الترويسة `X-Api-Key` بدلًا منها. وإذا أرسلت الترويستين معًا فالمعتمد هو `Authorization: Bearer`.
- لا تضع المفتاح في الرابط (مثل `?api_key=`): الواجهة لا تقرؤه من هناك وتردّ بالخطأ 401.
- جلسة الدخول إلى لوحة التحكم لا تفتح الواجهة، والمفتاح لا يفتح لوحة التحكم.

## متى يُرفض المفتاح؟

يُرفض المفتاح بالخطأ 401 ورمز `UNAUTHORIZED` في كل حالة لا يكون فيها صالحًا، ويحمل الرد الترويسة `WWW-Authenticate: Bearer realm="mujib"`.

| الحالة | ما تفعله |
| --- | --- |
| لا توجد ترويسة، أو ليست بصيغة `Bearer mjb_live_…` | تحقق من اسم الترويسة والمسافة بعد `Bearer` |
| المفتاح ناقص أو فيه حرف زائد بعد النسخ | انسخه كاملًا من مكان حفظه، أو أنشئ مفتاحًا جديدًا |
| المفتاح أُلغي | أنشئ مفتاحًا جديدًا وضعه في نظامك |
| انتهت مدة المفتاح، ويظهر في القائمة «انتهى» | أنشئ مفتاحًا جديدًا، ثم ألغِ القديم |
| حساب النشاط غير فعّال، كأن يكون موقوفًا | تواصل مع فريق مُجيب |

```json
{ "error": { "code": "UNAUTHORIZED", "message": "A valid API key is required (Authorization: Bearer mjb_live_…)." } }
```

## كيف ألغي مفتاحًا أو أستبدله؟

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

لتستبدل مفتاحًا دون أن يتوقف نظامك:

1. أنشئ مفتاحًا جديدًا بالصلاحيات نفسها.
2. ضعه في إعدادات نظامك مكان القديم.
3. تأكد أنه يعمل بطلب `GET /api/v1/me`.
4. انتظر حتى يتوقف تحديث وقت آخر استعمال للمفتاح القديم في القائمة، ثم ألغِه.

لكل نشاط حتى 10 مفاتيح فعّالة. المفتاح المنتهي لا يُحسب ضمنها، لكنه يبقى في القائمة حتى تلغيه.

## كيف أحمي المفتاح؟

عامل المفتاح ككلمة سرّ، لأنه يقرأ أسماء عملائك وأرقامهم.

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

لمعرفة من في فريقك يستطيع فتح صفحة «التكاملات»، راجع [صلاحيات الفريق](https://docs.mujib.ai/account/team-permissions/).

## الأسئلة الشائعة

### هل أستطيع رؤية المفتاح مرة أخرى بعد إغلاق النافذة؟

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

### كم مفتاحًا أستطيع أن أنشئ؟

حتى 10 مفاتيح فعّالة لكل نشاط. المفتاح الملغى أو المنتهي لا يُحسب ضمنها.

### هل يعمل المفتاح إذا وضعته في الرابط؟

لا. الواجهة تقرأ المفتاح من الترويسة فقط، وترفض أي طلب يحمله في الرابط بالخطأ 401.

### ماذا يحدث لنظامي إذا ألغيت المفتاح؟

يتوقف النظام الذي يستخدمه من أول طلب بعد الإلغاء، ويتلقى الخطأ 401. لا يُحذف شيء من بيانات مُجيب.

### لماذا لا أرى خيار قراءة الحجوزات؟

يظهر خيار «قراءة الحجوزات» فقط إذا كان نشاطك يستخدم المواعيد في مُجيب.

---

المصدر: https://docs.mujib.ai/developers/authentication/ · آخر تحديث: 2026-11-04