إنتقل إلى المحتوى الرئيسي

رموز Bearer (JWT)

تُستخدم رموز Bearer (JWT) لمصادقة الطلبات التي يجريها المستخدم إلى API الخاصة بـ OrcaRail.

تسجيل الدخول عبر لوحة التحكم​

أبسط طريقة للحصول على رمز Bearer هي تسجيل الدخول إلى لوحة التحكم. تستخدم لوحة التحكم نقطة نهاية تسجيل الدخول نفسها وتخزّن الرمز نيابةً عنك (في ملفات تعريف الارتباط)؛ لا تحتاج إلى التعامل مع الرموز يدويًا عند استخدام لوحة التحكم.

نظرة عامة​

رموز Bearer هي JSON Web Tokens (JWT) يحصل عليها المستخدم بعد تسجيل الدخول. وتُستخدم في العمليات الموجهة للمستخدم التي تحتاج فيها إلى معرفة المستخدم الذي أرسل الطلب.

الحصول على رمز Bearer​

تسجيل الدخول​

صادِق المستخدم للحصول على رمز JWT:

POST /api/v1/auth/email/login

جسم الطلب:

{
  "email": "[email protected]",
  "password": "secure-password"
}

الاستجابة:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenExpires": 3600,
  "user": {
    "id": 1,
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  }
}

استخدام الرمز​

ضمّن الرمز في ترويسة Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

مثال: تسجيل الدخول واستخدام الرمز​

JavaScript​

// Login
const loginResponse = await fetch(
  'https://api.orcarail.com/api/v1/auth/email/login',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: '[email protected]',
      password: 'secure-password',
    }),
  }
)

const { token, refreshToken, user } = await loginResponse.json()

// Store token securely (e.g., in memory, secure cookie, etc.)
localStorage.setItem('authToken', token)

// Use token for subsequent requests
const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
    }),
  }
)

cURL​

# Login
TOKEN=$(curl -X POST https://api.orcarail.com/api/v1/auth/email/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure-password"
  }' | jq -r '.token')

# Use token
curl https://api.orcarail.com/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

انتهاء صلاحية الرمز​

تنتهي صلاحية رموز JWT بعد مدة محددة (عادةً ساعة واحدة). عند انتهاء صلاحية الرمز، ستتلقى استجابة 401 Unauthorized.

رمز التحديث​

استخدم رمز التحديث للحصول على رمز وصول جديد:

POST /api/v1/auth/refresh
Authorization: Bearer YOUR_REFRESH_TOKEN

الاستجابة:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "new_refresh_token_here",
  "tokenExpires": 3600
}

مثال: تحديث الرمز​

async function refreshToken(refreshToken) {
  const response = await fetch('https://api.orcarail.com/api/v1/auth/refresh', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${refreshToken}`,
    },
  })

  if (!response.ok) {
    // Refresh token expired, need to login again
    throw new Error('Refresh token expired')
  }

  const { token, refreshToken: newRefreshToken } = await response.json()
  return { token, refreshToken: newRefreshToken }
}

// Use in your API client
async function apiRequest(url, options = {}) {
  let token = localStorage.getItem('authToken')

  let response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`,
    },
  })

  // If token expired, try to refresh
  if (response.status === 401) {
    const refreshToken = localStorage.getItem('refreshToken')
    const { token: newToken, refreshToken: newRefreshToken } =
      await refreshToken(refreshToken)

    localStorage.setItem('authToken', newToken)
    localStorage.setItem('refreshToken', newRefreshToken)

    // Retry request with new token
    response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${newToken}`,
      },
    })
  }

  return response
}

تسجيل الخروج​

سجّل الخروج وأبطل الجلسة الحالية:

POST /api/v1/auth/logout
Authorization: Bearer YOUR_JWT_TOKEN

الاستجابة: 204 No Content

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

احصل على معلومات المستخدم المصادَق عليه:

GET /api/v1/auth/me
Authorization: Bearer YOUR_JWT_TOKEN

الاستجابة:

{
  "id": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "role": "user",
  "status": "active"
}

استجابات الأخطاء​

رمز غير صالح​

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

رمز منتهي الصلاحية​

{
  "statusCode": 401,
  "message": "Token expired",
  "error": "Unauthorized"
}

غياب ترويسة Authorization​

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

أفضل ممارسات الأمان​

1. خزّن الرموز بأمان​

  • تطبيقات الويب: خزّنها في ملفات تعريف ارتباط HTTP-only أو في ذاكرة آمنة
  • تطبيقات الجوال: استخدم التخزين الآمن (Keychain على iOS وKeystore على Android)
  • تطبيقات الخادم: خزّنها في متغيرات البيئة أو أنظمة إدارة الأسرار

2. لا تكشف الرموز أبدًا​

  • لا تسجّل الرموز في السجلات
  • لا تضمّن الرموز في عناوين URL
  • لا تضف الرموز إلى نظام التحكم في الإصدارات

3. تعامل مع انتهاء صلاحية الرموز​

نفّذ دائمًا منطق تحديث الرمز للتعامل مع الرموز المنتهية بسلاسة.

4. استخدم HTTPS​

استخدم HTTPS دائمًا في بيئة الإنتاج لحماية الرموز أثناء النقل.

الخطوات التالية​