ورود و حساب

این مسیرها اطلاعات پنل را می‌خوانند، وارد و خارج می‌شوند، حساب فعلی را توصیف می‌کنند و رمز، ورود دومرحله‌ای، مرورگرهای واردشده و توکن‌های API خودتان را عوض می‌کنند. بیشترشان برای نشست مرورگرند؛ توکن نشست و مقدار CSRF ندارد.

زمان با ثانیهٔ یونیکس است. درخواست توکن از Authorization: Bearer استفاده می‌کند، هدر CSRF نمی‌خواهد و مسیرهای مخصوص نشست را صدا نمی‌زند. مرورگر با کوکی وارد می‌شود و در هر نوشتن X-CSRF-Token می‌فرستد.

اطلاعات پنل

GET/api/metaدسترسیpublic

نام پنل، نسخه، زبان پیش‌فرض و گزینه‌های ورود را برای صفحهٔ ورود برمی‌گرداند.

curl -sS "$BASE/meta"

{
  "version": "0.9.9-beta.6",
  "updatePending": false,
  "locale": "en",
  "brand": "Ovira",
  "panelAccent": "lime"
}

سند OpenAPI

GET/api/openapi.jsonدسترسیpublic

همین سند OpenAPI 3.1 را با نسخهٔ در حال اجرا در info.version برمی‌گرداند.

curl -sS "$BASE/openapi.json"

ورود

POST/api/auth/loginدسترسیpublic

مرورگر را وارد می‌کند و کوکی نشست می‌گذارد. وقتی ورود دومرحله‌ای روشن است، پاسخ یک چالش است، نه نشست.

فیلد	نوع	لازم	معنی
username	string	بله	نام کاربری حساب.
password	string	بله	رمز حساب.
remember	boolean	خیر	مرورگر را ۳۰ روز وارد نگه دار، نه تا مهلت بی‌فعالیتی.

curl -sS -c cookies.txt -X POST "$BASE/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"owner","password":"your-password","remember":false}'

{
  "admin": { "id": 1, "username": "owner", "role": "owner" },
  "csrf": "csrf-value",
  "roleName": "Owner",
  "perms": { "clients.view": "all" }
}

بدون عامل دوم، پاسخ شیء Me و کوکی است. با عامل دوم، پاسخ این است:

{ "mfa": true, "ticket": "ticket-value", "remember": false }

401 یعنی نام کاربری یا رمز اشتباه. 403 یعنی حساب مسدود است یا لایسنس آن را رد می‌کند. 429 یعنی تلاش ناموفق زیاد.

تمام کردن ورود دومرحله‌ای

POST/api/auth/mfaدسترسیpublic

ورود را با کد TOTP یا کد بازیابی تمام می‌کند.

فیلد	نوع	لازم	معنی
ticket	string	بله	تیکت auth/login. پنج دقیقه اعتبار دارد.
code	string	بله	کد TOTP یا یکی از کدهای بازیابی.
remember	boolean	خیر	مرورگر را ۳۰ روز وارد نگه دار.

curl -sS -c cookies.txt -X POST "$BASE/auth/mfa" \
  -H "Content-Type: application/json" \
  -d '{"ticket":"ticket-value","code":"123456"}'

پاسخ شیء Me و کوکی نشست است. 401 یعنی کد کار نکرد یا تیکت منقضی شد.

خروج

POST/api/auth/logoutدسترسیanyفقط نشست

مرورگر را خارج و کوکی را پاک می‌کند. مخصوص نشست.

curl -sS -b cookies.txt -X POST "$BASE/auth/logout" \
  -H "X-CSRF-Token: $CSRF"

{ "ok": true }

من کی هستم

GET/api/auth/meدسترسیany

حساب پشت درخواست، نقش، دسترسی‌ها و محدودیت‌های مؤثر، طرح و، وقتی درخواست با توکن است، توکن را برمی‌گرداند. برای مرورگر csrf مقدار لازم برای نوشتن را دارد؛ برای درخواست توکن خالی است.

curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/auth/me"

401 یعنی نشست یا توکن معتبر نیست.

سهمیهٔ ترافیک من

GET/api/auth/usageدسترسیany

سهمیهٔ ترافیک فعلی حساب را برمی‌گرداند. مالک همیشه برای سقف و تاریخ پایان 0 می‌خواند.

curl -sS -H "Authorization: Bearer $OVIRA_TOKEN" "$BASE/auth/usage"

{
  "usedBytes": 82463372083,
  "trafficLimit": 1099511627776,
  "expireAt": 1796000000
}

تغییر رمز من

POST/api/account/passwordدسترسیanyفقط نشست

مخصوص نشست. رمز شما را عوض می‌کند و مرورگرهای دیگرتان را خارج می‌کند.

فیلد	نوع	لازم	معنی
current	string	بله	رمز فعلی.
new	string	بله	رمز تازه، بررسی‌شده از نظر قدرت.

curl -sS -b cookies.txt -X POST "$BASE/account/password" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"current":"old-password","new":"a-new-long-password"}'

{ "ok": true }

400 یعنی رمز فعلی اشتباه است یا رمز تازه پذیرفته نمی‌شود.

ورود دومرحله‌ای

همهٔ این مسیرها مخصوص نشست‌اند.

POST/api/account/2fa/setupدسترسیanyفقط نشست

راه‌اندازی را شروع و کلید راه‌اندازی، URI با otpauth:// و یک data URL از تصویر QR را برمی‌گرداند.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/setup" \
  -H "X-CSRF-Token: $CSRF"

{
  "secret": "JBSWY3DPEHPK3PXP",
  "uri": "otpauth://totp/Ovira:owner?secret=...",
  "qr": "data:image/png;base64,..."
}

400 یعنی ورود دومرحله‌ای از قبل روشن است.

POST/api/account/2fa/enableدسترسیanyفقط نشست

عامل دوم را روشن می‌کند. بدنه یک فیلد لازم code از برنامهٔ احراز هویت دارد. پاسخ ده کد بازیابی دارد که یک‌بار نشان داده می‌شود.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/enable" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"code":"123456"}'

{ "recoveryCodes": ["abcd-efgh", "ijkl-mnop"] }

400 یعنی راه‌اندازی شروع نشده یا کد مطابقت ندارد.

POST/api/account/2fa/disableدسترسیanyفقط نشست

عامل دوم را خاموش می‌کند. بدنه یک فیلد لازم password دارد.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/disable" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"password":"your-password"}'

{ "ok": true }

400 یعنی رمز اشتباه است.

POST/api/account/2fa/recoveryدسترسیanyفقط نشست

کدهای بازیابی را عوض می‌کند. بدنه یک فیلد لازم password دارد. پاسخ کدهای تازه است که یک‌بار نشان داده می‌شوند.

curl -sS -b cookies.txt -X POST "$BASE/account/2fa/recovery" \
  -H "Content-Type: application/json" -H "X-CSRF-Token: $CSRF" \
  -d '{"password":"your-password"}'

400 یعنی ورود دومرحله‌ای خاموش است یا رمز اشتباه است.

مرورگرهای واردشده

GET/api/account/sessionsدسترسیanyفقط نشست

نشست‌های شما را از جدیدترین فعالیت به قدیم‌ترین، با نشانهٔ نشست فعلی، فهرست می‌کند. مخصوص نشست.

curl -sS -b cookies.txt "$BASE/account/sessions"

[
  {
    "id": "9f3a...",
    "createdAt": 1795800000,
    "expiresAt": 1796000000,
    "lastSeenAt": 1795919000,
    "ip": "203.0.113.9",
    "userAgent": "Mozilla/5.0 ...",
    "current": true,
    "ref": "9f3a2b7c8d1e4f60"
  }
]

DELETE/api/account/sessions/{id}دسترسیanyفقط نشست

یک مرورگر را خارج می‌کند. پارامتر مسیر id مقدار ref نشست، یا شناسهٔ آن با حداقل ۱۶ نویسه است. مخصوص نشست.

curl -sS -b cookies.txt -X DELETE "$BASE/account/sessions/9f3a2b7c8d1e4f60" \
  -H "X-CSRF-Token: $CSRF"

{ "ok": true }

404 یعنی چنین نشستی نیست.

POST/api/account/sessions/revoke-othersدسترسیanyفقط نشست

همهٔ مرورگرها جز این یکی را خارج می‌کند. مخصوص نشست.

curl -sS -b cookies.txt -X POST "$BASE/account/sessions/revoke-others" \
  -H "X-CSRF-Token: $CSRF"

{ "ok": true }

توکن‌های API

این مسیرها مخصوص نشست‌اند و در توکن‌های API کامل توضیح داده شده‌اند.

GET/api/account/tokensدسترسیanyفقط نشست

توکن‌های شما را فهرست می‌کند.

POST/api/account/tokensدسترسیanyفقط نشست

توکن می‌سازد.

DELETE/api/account/tokens/{id}دسترسیanyفقط نشست

یکی از توکن‌های شما را لغو می‌کند.

GET/api/admins/{id}/tokensدسترسیownerفقط نشست

فقط مالک. توکن‌های یک حساب را فهرست می‌کند.

DELETE/api/admins/{id}/tokens/{tid}دسترسیownerفقط نشست

فقط مالک. یک توکن از یک حساب را لغو می‌کند.

صفحه‌های مرتبط

• توکن‌های API: ساخت، محدود کردن و لغو توکن.
• حساب‌های پنل: صفحهٔ حساب، رمز و عامل دوم.
• نمای کلی API: خطاهای توکن و فهرست مخصوص نشست.
• تنظیمات: جای حساب من.