# POST /api/auth/access-token

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td><td>تگ Swagger</td></tr><tr><td style="direction: ltr; text-align: left;">POST</td><td style="direction: ltr; text-align: left;">/api/auth/access-token</td><td style="direction: ltr; text-align: left;">UserController@accessToken</td><td style="direction: ltr; text-align: left;">domainAccess, ipTrust</td><td style="direction: rtl; text-align: right;">تولید توکن دسترسی جدید پس از تطبیق مرورگر، IP، دامنه و شعبه.</td><td style="direction: ltr; text-align: left;">tags={"Auth"}</td></tr></tbody></table>

</div>### توضیح عملکرد (Function Logic)

<div id="bkmrk-%D8%A7%DB%8C%D9%86-endpoint%D8%8C-%D8%A7%D8%B9%D8%AA%D8%A8%D8%A7%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><div style="direction: rtl; text-align: justify;">این Endpoint، اعتبار و اصالت توکن فعلی کاربر را پس از Decode بررسی کرده و در صورت تطبیق پارامترهای امنیتی، توکن جدید ۷ روزه صادر می‌کند. اگر هر کدام از فاکتورهای مرورگر، IP، دامنه یا شعبه تغییر کند، درخواست با پیام خطای دقیق رد می‌شود.</div>1. دریافت `access_token` از `$request->data` و Decode با کلید `env('JWT_SECRET_KEY')`.
2. تحلیل User-Agent با `DeviceDetector` برای استخراج اطلاعات مرورگر فعلی (نام و نسخه).
3. تابع داخلی `checkBrowser()` مقایسه‌ای بین مرورگر ثبت‌شده در توکن و مرورگر فعلی انجام می‌دهد.
4. اگر مرورگر تطبیق داشت، سپس IP بررسی می‌شود: 
    - اگر IP فعلی با `uip` در توکن یا با یکی از IPهای خصوصی (10.\* / 192.168.\* / 172.16.\*) هم‌خوانی داشت، ادامه داده می‌شود.
5. تطبیق دامنه `iss` با هدر Domain درخواست.
6. تطبیق شناسه شعبه `brn` با ورودی `branch` درخواست.
7. در صورت قبولی همه مراحل: یافتن اپراتور فعال (status=1، بدون بلوک).
8. تولید توکن جدید با ساختار زیر:

</div>```
{
  "typ": "base",
  "iss": "domain.com",
  "aud": "domain.com",
  "iat": 1731964000,
  "nbf": 1731964000,
  "exp": 1732568800,       // 7 روز
  "uuid": 54,
  "brn": 2,
  "uip": "10.0.0.15",
  "brw": { "name": "Chrome", "version": "122.0", "type": "browser" }
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### بدنه درخواست (Request Body)

<div id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%A7%D9%84%D8%B2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>پارامتر</td><td>نوع داده</td><td>الزامی</td><td>توضیح</td></tr><tr><td>data.access\_token</td><td>string (JWT)</td><td>بله</td><td style="direction: rtl; text-align: right;">توکن فعلی کاربر که باید توسط سرور Decode و اعتبارسنجی شود.</td></tr><tr><td>branch</td><td>integer</td><td>بله</td><td style="direction: rtl; text-align: right;">شناسه شعبه فعلی جهت تطبیق با اطلاعات درون توکن.</td></tr></tbody></table>

</div>```
POST /api/auth/access-token
Content-Type: application/json
Domain: example.domain

{
  "branch": 2,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6..."
  }
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### پاسخ موفق (Response - Success)

```
{
  "user": {
    "uuid": 54,
    "from": "users",
    "role": "admin",
    "isAirPlusAdmin": true,
    "group": "core",
    "data": {
      "displayName": "Ali Pour",
      "email": "a.pour@example.ir",
      "photoURL": "https://storage.service01.ir/media/avatar/robot.png",
      "services": { "telegram": false },
      "personnelId": "P00999",
      "branch": [0,1],
      "access": [ ... ],
      "shortcuts": ["temporary-registration","online-ticket","trade-management","customers"]
    }
  },
  "access_token": "new.jwt.token.generated"
}
```

<div id="bkmrk--3" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### پاسخ‌های خطا (Error Types)

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D8%AE%D8%B7%D8%A7-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-chan" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 97%; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold; text-align: center;"><td>نوع خطا</td><td>شرح خطا</td></tr><tr><td>changeBrowser</td><td style="direction: rtl; text-align: right;">مرورگر فعلی با مرورگر آخرین ورود مطابقت ندارد.</td></tr><tr><td>changeIp</td><td style="direction: rtl; text-align: right;">IP متغیر یا استفاده از VPN.   
**جزئیات:** شامل IP فعلی و IP درج‌شده در توکن.</td></tr><tr><td>changeDomain</td><td style="direction: rtl; text-align: right;">دامنه درخواست با دامنه صادرکننده توکن هم‌خوانی ندارد.</td></tr><tr><td>changeBranch</td><td style="direction: rtl; text-align: right;">شناسه شعبه تغییر کرده (مثلاً انتقال کاربر بین شعبات).</td></tr><tr><td>personnelId</td><td style="direction: rtl; text-align: right;">نامعتبر بودن توکن یا خطای رمزگشایی JWT.</td></tr></tbody></table>

نمونه خطای تغییر IP:</div>```
{
  "error": {
    "type": "changeIp",
    "message": "وضعیت اینترنت شما تغییر پیدا کرده",
    "details": {
      "token_ip": "10.1.1.2",
      "current_ip": "45.66.88.100"
    }
  }
}
```

<div id="bkmrk--4" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### تولید JWT جدید

<div id="bkmrk-%D8%AA%D9%88%DA%A9%D9%86-%D8%AC%D8%AF%DB%8C%D8%AF-%D8%A8%D8%A7-%DA%A9%D8%AA%D8%A7%D8%A8%D8%AE%D8%A7%D9%86" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><div style="direction: rtl; text-align: justify;">توکن جدید با کتابخانه **firebase/php-jwt** و الگوریتم `HS256` تولید می‌شود؛ مدت اعتبار آن ۷ روز (۶۰۴٬۸۰۰ ثانیه) است. اطلاعات کلیدی آن شامل شناسه کاربر، شناسه شعبه، مرورگر و IP فعلی است.</div></div>### تحلیل امنیتی

<div id="bkmrk-%E2%9C%85-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%DA%86%D9%86%D8%AF%D9%85%D8%B1%D8%AD%D9%84%D9%87%E2%80%8C%D8%A7%DB%8C-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ✅ **احراز چندمرحله‌ای محیطی:** کنترل همزمان ۴ عامل (Browser + IP + Domain + Branch) قبل از احیای توکن.
- ✅ **محافظت از سوریه توکن:** جلوگیری از استفاده از JWT در مرورگر یا شبکه دیگر.
- ✅ **تأیید دامنه صدور:** مقایسه مقدار `iss` در هدر JWT با مقدار هدر درخواست (Domain).
- ✅ **دسترسی کنترل‌شده Redis:** بارگذاری میانبرهای رابط سیستم از مسیر cache محدود.
- ⚠️ توصیه: اعمال نرخ محدودسازی (Rate Limiting) برای جلوگیری از حمله بروت‌فورس JWT.

</div>### وابستگی‌ها (Dependencies)

<div id="bkmrk-use-firebase%5Cjwt%5Cjwt" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Firebase\\JWT\\JWT;
- use Firebase\\JWT\\Key;
- use DeviceDetector\\DeviceDetector;
- use DeviceDetector\\ClientHints;
- use DeviceDetector\\Parser\\AbstractDeviceParser;
- use Carbon\\Carbon;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Models\\User;

</div>### پیوست نگهداری و توسعه بعدی

<div id="bkmrk-%D8%A7%D8%B6%D8%A7%D9%81%D9%87%E2%80%8C%DA%A9%D8%B1%D8%AF%D9%86-%D8%A8%D8%B1%D8%B1%D8%B3%DB%8C-dev" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- اضافه‌کردن بررسی Device ID یکتا برای جلوگیری از جعل User-Agent.
- افزودن refresh-token مجزا برای دسترسی موقت با سطح محدود (scoped access).
- ذخیره لاگ تغییر IPها در SystemLog جهت تحلیل تهدیدات.
- اعمال Expiration Dynamics (IP-based TTL) بر اساس منطقه جغرافیایی کاربر.

</div>