پرش به مطلب اصلی

توکن‌های Bearer (JWT)

توکن‌های Bearer (JWT) برای احراز هویت درخواست‌های کاربر به API اورکاریل استفاده می‌شوند.

ورود از طریق داشبورد​

ساده‌ترین راه گرفتن توکن Bearer ورود به داشبورد است. داشبورد از همان اندپوینت ورود استفاده می‌کند و توکن را برای شما (در کوکی‌ها) ذخیره می‌کند؛ هنگام استفاده از داشبورد لازم نیست توکن‌ها را دستی مدیریت کنید.

نمای کلی​

توکن‌های Bearer همان JSON Web Token (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"
}

بهترین روش‌های امنیتی​

۱. توکن‌ها را امن ذخیره کنید​

  • اپلیکیشن‌های وب: در کوکی‌های HTTP-only یا حافظه امن ذخیره کنید
  • اپ‌های موبایل: از ذخیره‌سازی امن استفاده کنید (Keychain در iOS، Keystore در اندروید)
  • اپلیکیشن‌های سمت سرور: در متغیرهای محیطی یا سیستم‌های مدیریت راز ذخیره کنید

۲. هرگز توکن‌ها را افشا نکنید​

  • توکن‌ها را در لاگ ثبت نکنید
  • توکن‌ها را در URL قرار ندهید
  • توکن‌ها را در کنترل نسخه commit نکنید

۳. انقضای توکن را مدیریت کنید​

همیشه منطق تازه‌سازی توکن را پیاده کنید تا توکن‌های منقضی‌شده بدون مشکل مدیریت شوند.

۴. از HTTPS استفاده کنید​

در محیط عملیاتی همیشه از HTTPS استفاده کنید تا توکن‌ها در حین انتقال محافظت شوند.

قدم‌های بعدی​