> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# المصادقة

> حماية API بالمصادقة الأساسية، ثم إقران كل حساب WhatsApp برمز QR أو رمز الاقتران أو مفتاح المرور.

ولدى GOWA نوعان منفصلان من التوثيق:

1. **الوصول إلى API**: من قد يتصل بـ GOWA. هذه هي مصادقة HTTP الأساسية.
2. **إقران WhatsApp**: ربط حساب WhatsApp بفتحة الجهاز، كما أنك ستربط Web.

## الوصول إلى API: المصادقة الأساسية

المصادقة الأساسية هي طريقة المصادقة API الوحيدة. لا توجد مفاتيح API أو JWT لمكالمات REST.

تعيين واحد أو أكثر من أزواج `user:password`، مفصولة بفواصل:

```bash theme={null}
# environment
APP_BASIC_AUTH=admin:changeme,ops:another-secret
# or flag
./whatsapp rest --basic-auth=admin:changeme,ops:another-secret
```

يجب أن يحتوي كل إدخال على اسم مستخدم وكلمة مرور غير فارغين. المستمع الافتراضي، `APP_HOST=0.0.0.0`، يرفض البدء بدون بيانات اعتماد كاملة. من أجل التنمية المحلية بدون مصادقة، يربط `APP_HOST=127.0.0.1`.

إذا قام الوكيل العكسي بالمصادقة على كل متصل، فإن `APP_ALLOW_UNAUTHENTICATED=true` أو `--allow-unauthenticated=true` يسمح صراحة للمستمع غير المصدق بدون مصادقة أساسية. تقييد الوصول المباشر إلى ذلك المستمع.

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

```bash theme={null}
curl -u admin:changeme http://localhost:3000/app/info
# same as
curl -H "Authorization: Basic YWRtaW46Y2hhbmdlbWU=" http://localhost:3000/app/info
```

يؤدي غياب بيانات الاعتماد أو عدم صحتها إلى إرجاع `401 Unauthorized`.

### ما ليس وراء المصادقة الأساسية

| الطريق | لماذا |
| - | - |
| `GET /health` | مسبار الحياة. دائماً في الجذر، تجاهل `APP_BASE_PATH`. |
| `POST /chatwoot/webhook`, `POST /chatwoot/webhook/{device_id}` | مسجلة فقط من قبل Chatwot. عندما `CHATWOOT_ENABLED=true` وتحميها `CHATWOOT_WEBHOOK_SECRET`. انظر [Chatwoot](https://gowa-docs.mintlify.site/ar/integrations/chatwoot.md). |
| اكتشاف MCP OAuth والنقاط النهائية `/oauth/*` | فقط عندما `MCP_OAUTH_ENABLED=true`. انظر [MCP server](https://gowa-docs.mintlify.site/ar/integrations/mcp.md). |
| `GET /statics/*` | صور QR والملفات المرفوعة والوسائط المنزّلة. تُقدَّم قبل التحقق من المصادقة الأساسية. يستطيع أي شخص يعرف عنوان URL لملف استرداده. لا تُعرض مباشرةً في المتصفح إلا ملفات JPEG وPNG وGIF وWebP التي اجتازت التحقق والموجودة في مسارات الصور. وتُنزَّل الملفات الأخرى كمرفقات بنوع محتوى غير نشط والترويسة `X-Content-Type-Options: nosniff`. قيّد الوصول إلى الملفات على مستوى الوكيل عند الحاجة. |

كل شيء آخر، بما في ذلك لوحة التحكم في `/`، `/mcp` و `/ws`، يتطلب المصادقة الأساسية عند تكوينها.

### WebSocket

لا يمكن للمتصفحات تعيين رؤوس على اتصالات WebSocket، لذا فإن `/ws` يأخذ بيانات الاعتماد في سلسلة الاستعلام:

```text theme={null}
ws://localhost:3000/ws?device_id=my-device&authorization=YWRtaW46Y2hhbmdlbWU=
```

`authorization` هو `base64(user:password)`. استخدم TLS (`wss://`) و احرر سلسلة الاستعلام في سجلات البروكسي. يقوم WebSocket بالتحقق من مصدر المتصفح مقابل نفس الأصول الموثوقة المستخدمة لطلبات HTTP المتغيرة للدولة. يقوم مركز WebSocket الحالي ببث الأحداث على جميع المقابس المتصلة. الاستعلام `device_id` يحدد سياق الجهاز للاتصال ولكنه لا يعزل تسليم الحدث. استخدم معرفات الجهاز للحدث لتصفية عرض لوحة التحكم، ومنح API الوصول فقط إلى المتصلين الموثوق بهم مع جميع الأجهزة.

راجع [مرجع WebSocket المرجع](https://gowa-docs.mintlify.site/ar/api-reference/websocket.md) لرموز الأحداث ، الحمولات ، و مثال العميل.

### CORS

يسمح CORS بأي أصل افتراضيًا. قيّده باستخدام `APP_CORS_ALLOWED_ORIGINS=https://ui.example.com` (مع الفصل بفواصل). ترويسات الطلبات المسموح بها هي `Origin` و`Content-Type` و`Accept` و`Authorization` و`X-Device-Id`.

تُجرى فحوص CORS وفحوص مصدر المتصفح بشكل منفصل. لا يسمح استخدام حرف بدل لمصدر CORS بطلبات تغيّر الحالة أو باتصالات WebSocket. يثق GOWA بمضيف الطلب نفسه، ومصادر CORS المحددة، و`APP_TRUSTED_ORIGINS`، والمصادر المضبوطة لجهة إصدار OAuth وعنوان URL لاستدعاء Chatwoot الراجع. إذا كانت لوحة التحكم مستضافة بشكل منفصل، فاضبط مصدرها بدقة:

```env theme={null}
APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
APP_TRUSTED_ORIGINS=https://ui.example.com
```

طفرة متصفح غير موثوق بها ترجع `403 CROSS_SITE_REQUEST_BLOCKED`. وهذا أيضا يشمل مسارات GET التي تقوم بتسجيل الدخول أو تسجيل الخروج أو إعادة الاتصال أو إعادة تعيين رابط الدعوة. العملاء مثل الكول الذين لا يرسلون ترويسات منشأ المتصفح لا يزالون يعملون.

لا يُوثَق أبدًا بالأصل `null`. قدّم `gowa-ui.html` عبر HTTP أو HTTPS بدلًا من فتحه بعنوان URL من نوع `file://`. عند العمل خلف وكيل عكسي، حافظ على `Host`، أو اضبط الوكلاء الموثوقين مع `X-Forwarded-Host`، أو أدرج الأصل العام في `APP_TRUSTED_ORIGINS`.

## إقران واتساب

كل حساب في WhatsApp يعيش في **فتحة الجهاز**. قم بإنشاء الفتحة أولاً، ثم إقرانها. المسارات تحت `/devices/{device_id}` تأخذ الجهاز من المسار. المسارات المعادلة `/app/*` تستخدم رأس `X-Device-Id`.

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" -d '{"device_id": "sales"}'
```

### QR code

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/login
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Login success",
  "results": {
    "device_id": "sales",
    "qr_link": "http://localhost:3000/statics/qrcode/scan-qr-b0b7bb43-....png",
    "qr_duration": 30
  }
}
```

افتح `qr_link` و قم بفحصه من الهاتف: **إعدادات → الأجهزة المرتبطة → رابط الجهاز**. طلب رمز جديد بعد `qr_duration` ثواني. لوحة التحكم في `/` تظهر QR مباشرة وتحدث مباشرة عبر WebSocket.

### Pairing code

```bash theme={null}
curl -u admin:changeme -X POST \
  "http://localhost:3000/devices/sales/login/code?phone=628123456789"
```

تحتوي الاستجابة على `results.pair_code`، وهو رمز من 8 محارف. على الهاتف، اختر **الربط برقم الهاتف بدلًا من ذلك** وأدخله. يجب أن يكون `phone` رقم الحساب المراد ربطه، مع رمز البلد.

### كلمة المرور

إذا طلب الهاتف التحقق من مفتاح المرور أثناء تسجيل الدخول QR ، تقوم GOWA بتخزين تحدي WebAuthn وبث `PASSKEY_REQUEST` على WebSocket. لوحة التحكم تتعامل مع هذا التدفق. لقيادته بنفسك:

1. `GET /app/passkey` يرجع التحدي المعلق.
2. يقدم `POST /app/passkey/response` تأكيد WebAuthn (تنسيق `PublicKeyCredential.toJSON()`.
3. انتظر `PASSKEY_CONFIRMATION`. عندما يكون `result.skip_handoff_ux` صحيحاً، فإن تدفق QR النشط يرسل التأكيد تلقائياً. وإلا قارن `result.code` مع التعليمات البرمجية على الهاتف، ثم اتصل بـ `POST /app/passkey/confirm`.

إرسال `X-Device-Id` على المكالمات الثلاث.

### تحقق من النتيجة

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/status
```

`results.is_connected` و `results.is_logged_in` كلاهما `true` بمجرد ربط الحساب. تستمر الجلسات في `storages/`، لذلك لا تتطلب إعادة التشغيل الاقتران مرة أخرى.

## تسجيل الخروج والإزالة

| اجراء | Endpoint | التأثيرات |
| - | - | - |
| تسجيل الخروج | `POST /devices/{device_id}/logout` أو `GET /app/logout` | إلغاء ربط الحساب من WhatsApp ومسح جلسته. تبقى الخانة ، حتى يمكنك إقرانها مرة أخرى تحت نفس المعرف. |
| إعادة الاتصال | `POST /devices/{device_id}/reconnect` أو `GET /app/reconnect` | إعادة فتح اتصال WhatsApp دون الإقران مرة أخرى. |
| إزالة | `DELETE /devices/{device_id}` | تسجيل الخروج، ثم حذف الخانة مع بيانات الجلسة والدردشة. |

يتم تسجيل خروج حساب غير مرتبط من الهاتف (الأجهزة المرتبطة > تسجيل الخروج) بنفس الطريقة: تبقى الخانة وتحتاج إلى الاقتران مرة أخرى.

## قائمة التحقق من الأمان

* تعيين `APP_BASIC_AUTH` دائماً مع كلمات مرور قوية على أي شيء يمكن الوصول إليه من شبكة.
* إنهاء TLS في وكيل عكسي؛ أوراق اعتماد Auth الأساسية هي فقط أساس 64-مرمز.
* تقييد `APP_CORS_ALLOWED_ORIGINS` عند اتصال واجهة المستخدم في المتصفح بـ API.
* أنشئ قيمة ثابتة لـ `WHATSAPP_WEBHOOK_SECRET` باستخدام `openssl rand -hex 32`. تُستبدل القيم الفارغة أو القيم السرية المنشورة ضمن الأمثلة بمفتاح عشوائي خاص بكل عملية يتغير عند إعادة التشغيل.
* تعامل مع `storages/` باعتباره مجلدًا حساسًا. فهو يحتوي على مفاتيح جلسات جميع الحسابات المرتبطة. تستخدم ملفات SQLite الجديدة أذونات تقتصر على المالك، وتستخدم المجلدات المُنشأة لها الأذونات `0700`. احمِ النسخ الاحتياطية بالعناية نفسها.


## Related topics

- [مرجع API](https://gowa-docs.mintlify.site/ar/api-reference/introduction.md)
- [مصادقة API](https://gowa-docs.mintlify.site/ar/api-reference/authentication.md)
- [إرسال الرسائل](https://gowa-docs.mintlify.site/ar/examples/sending-messages.md)
- [البداية السريعة](https://gowa-docs.mintlify.site/ar/quickstart.md)
- [بوستمان](https://gowa-docs.mintlify.site/ar/api-reference/sdks/postman.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.