انتقل إلى المحتوى
Sursa Developers

POST/oauth/token

إصدار رمز OAuth 2.0

oauth_token

نقطة نهاية إصدار الرموز في OAuth 2.0 (RFC 6749، القسم 3.2). الحقل grant_type: القيمة authorization_code تستبدل رمزًا لمرة واحدة بزوج من الرموز وتتطلب code_verifier (PKCE S256)؛ والقيمة refresh_token تصدر زوجًا جديدًا مقابل رمز التحديث وتُبطل رمز التحديث السابق (التدوير)، وإعادة استخدام رمز مُبطَل تُبطل السلسلة كلها؛ والقيمة client_credentials تصدر رمزًا نيابة عن المؤسسة، لتطبيق confidential فقط، دون رمز تحديث. العميل confidential يُصادَق بالترويسة Authorization: Basic أو بالحقلين client_id وclient_secret؛ والعميل العام يرسل client_id فقط. رمز الوصول صالح لمدة ساعة واحدة، ورمز التحديث لمدة 90 يومًا. تتبع الاستجابات والأخطاء RFC 6749، القسم 5، مع Cache-Control: no-store. أُضيف في الإصدار 1.62.0.

المصادقة

لا تلزم بيانات اعتماد.

نص الطلب

application/x-www-form-urlencoded

الكائن: OAuthTokenRequest

  • grant_typestringمطلوب

    القيم المسموح بها: authorization_coderefresh_tokenclient_credentials

  • codestring

    رمز التخويل (authorization_code).

  • redirect_uristring

    عنوان URI لإعادة التوجيه نفسه الذي في طلب التخويل (authorization_code).

  • code_verifierstring

    قيمة PKCE الأصلية، من 43 إلى 128 حرفًا (authorization_code).

  • refresh_tokenstring

    رمز التحديث (refresh_token).

  • scopestring

    نطاقات صلاحيات مفصولة بمسافات، للتضييق فقط (refresh_token، client_credentials).

  • client_idstring

    معرّف التطبيق، حين لا يُمرَّر السر في الترويسة Authorization: Basic.

  • client_secretstring

    سر العميل لتطبيق confidential، حين لا يُمرَّر في الترويسة Authorization: Basic.

الاستجابات

200صدرت الرموز.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: OAuthTokenResponse

  • access_tokenstringمطلوب

    رمز الوصول (kbat_…) للترويسة Authorization: Bearer.

  • token_typestringمطلوب

    القيم المسموح بها: Bearer

  • expires_inintegerمطلوب

    مدة صلاحية رمز الوصول بالثواني.

  • refresh_tokenstring

    رمز التحديث (kbrt_…)؛ يغيب مع client credentials.

  • scopestringمطلوب

    نطاقات صلاحيات الرمز، مفصولة بمسافات.

400خطأ وفق تعريف RFC 6749، القسم 5.2.

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: OAuthErrorResponse

401بيانات اعتماد العميل غير صالحة (`invalid_client`).

ترويسات الاستجابة

  • RateLimit-Policy

    الحدود السارية، بصيغة مسودة IETF draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل "<name>";q=<quota>;w=<window in seconds>. العنصر key هو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكون user، ودون بيانات اعتماد ip)؛ وminute وday وmonth هي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.

  • RateLimit

    المتبقي من كل حد في الترويسة RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    حد العنصر الأشد صرامة في الترويسة RateLimit-Policy (العنصر الذي بقي فيه أقل عدد من الطلبات).

  • X-RateLimit-Remaining

    عدد الطلبات المتبقية ضمن الحد الأشد صرامة.

  • X-RateLimit-Reset

    عدد الثواني حتى إعادة ضبط الحد الأشد صرامة.

application/json

الكائن: OAuthErrorResponse

إعادة المحاولة بأمان

أرسل الترويسة Idempotency-Key (قيمة UUID مثلًا) مع كل طلب POST وPATCH. إعادة المحاولة بالمفتاح نفسه خلال 24 ساعة تعيد الاستجابة المحفوظة بدل تنفيذ الطلب مرة أخرى.

حدود المعدل

تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.

← oauth · مرجع API