احراز هویت و توکن

همه وب سرویس‌ها، CLI و Terraform با توکن شخصی API کار می‌کنند. یک توکن برای همه محصولات کافی است؛ با دسترسی‌ها (scope) مشخص می‌کنید هر توکن چه کاری مجاز است انجام دهد.

ساخت توکن

1. وارد پنل شوید و به صفحه توکن‌های API بروید (تنظیمات ← توکن‌های API).
2. نامی بگذارید که بگوید توکن مال کجاست (مثلاً ci-deploy یا laptop).
3. دسترسی‌های لازم را از جدول زیر انتخاب کنید و در صورت نیاز تاریخ انقضا و فهرست IP مجاز بگذارید.
4. توکن را کپی کنید. فقط یک بار نمایش داده می‌شود و آریانت هم نسخه خوانای آن را نگه نمی‌دارد.

ارسال توکن

توکن را در هدر Authorization هر درخواست بفرستید:

GET /cloud/v1/servers HTTP/1.1
Host: api.ariaservice.net
Authorization: Bearer <token>

curl -s https://api.ariaservice.net/cloud/v1/servers -H "Authorization: Bearer $ARIANET_TOKEN"

CLI توکن را از arianet configure، متغیر محیطی ARIANET_TOKEN یا فلگ --token می‌خواند و Terraform از آرگومان token پرووایدر یا همان متغیر محیطی.

دسترسی‌ها (scope)

توکنی که بدون هیچ scope ساخته شود همه دسترسی‌های صاحبش را دارد. برای هر کاربرد، توکن را فقط به scopeهای لازم محدود کنید. درخواست خارج از scope توکن پاسخ 403 می‌گیرد.

ابر آریانت (/cloud/v1)

Scope	اجازه
cloud:servers:read	همه GETها: سرورها، دیسک‌ها، شبکه‌ها، فایروال‌ها، IPها، لود بالانسرها، ایمیج‌ها، قیمت‌ها و actionها
cloud:servers:write	همه تغییرات (POST، PUT، PATCH، DELETE)

لیست قیمت عمومی (GET /cloud/v1/public/pricing) به توکن نیاز ندارد.

سرور مجازی (/api/v1)

Scope	اجازه
regions:read	GET /regions
os:read	GET /os/datacenter/{id}
plans:read	GET /plans/...
servers:read / servers:write	خواندن سرورها / ساخت، حذف، روشن و خاموش، نصب مجدد، تغییر نام و محافظت
ssh-keys:read / ssh-keys:write	کلیدهای SSH
firewalls:read / firewalls:write	فایروال‌ها، قوانین و اتصال‌ها
balance:read	موجودی و تراکنش‌ها
invoices:read	فاکتورها
tokens:read / tokens:write	فهرست و ابطال توکن‌ها

GET /auth/me و DELETE /auth/logout scope لازم ندارند.

VPS منطقه‌ای، هاستینگ و سرور اختصاصی

وب سرویس	خواندن	تغییر
VPS منطقه‌ای (/vps/v1)	vps:servers:read	vps:servers:write
هاستینگ (/hosting/v1)	hosting:accounts:read	hosting:accounts:write
سرور اختصاصی (/baremetal/v1)	baremetal:servers:read	baremetal:servers:write

پیامک (/sms/v1)

Scope	اجازه
sms:messages:read	پیام‌های ارسالی و دریافتی، batchها، ارسال‌های زمان‌بندی‌شده، قیمت‌ها و گزارش
sms:messages:write	ارسال، لغو ارسال زمان‌بندی‌شده، شماره‌های مسدود و وب‌هوک
sms:lines:read	خطوط ارسال
sms:templates:read / sms:templates:write	خواندن / مدیریت قالب‌ها

درخواست خط اختصاصی (POST /lines) توکن بدون scope می‌خواهد.

محدود کردن به IP

توکن را می‌توان به فهرستی از آدرس‌ها یا بازه‌های IP مبدأ محدود کرد. درخواست از هر آدرس دیگر، حتی با توکن معتبر، با 403 رد می‌شود (در /api/v1 با کد IP_NOT_ALLOWED). برای سرورها و runnerهای CI که IP ثابت دارند این کار را حتماً انجام دهید.

اعضای تیم

اگر توکن را عضو تیمِ یک حساب بسازد، دسترسی توکن هرگز از دسترسی خود آن عضو بیشتر نمی‌شود: سیاست‌های IAM حساب هم روی هر درخواست اعمال می‌شوند. مثلاً مدیریت نمایندگی هاست به hosting:reseller:manage و تغییر تنظیم ترافیک VPS منطقه‌ای به vps:manage در IAM نیاز دارد.

مدیریت و ابطال توکن

• در پنل، صفحه توکن‌های API توکن‌های شما را نشان می‌دهد و هر کدام را می‌توانید باطل کنید. GET /api/v1/auth/tokens آخرین زمان استفاده (last_used) و انقضای (expires) هر توکن را هم برمی‌گرداند.
• با وب سرویس VPS: GET /api/v1/auth/tokens (scope tokens:read) و DELETE /api/v1/auth/tokens/{id} (scope tokens:write). DELETE /api/v1/auth/logout توکنی را که با آن درخواست فرستاده‌اید باطل می‌کند.
• با CLI: arianet auth tokens list، arianet auth tokens revoke <id>، arianet auth whoami و arianet auth logout.

نگه‌داری امن توکن

• توکن را هرگز در کد سمت کاربر (مرورگر، اپلیکیشن موبایل) یا مخزن کد قرار ندهید؛ در متغیر محیطی یا ذخیره‌گاه اسرار نگه دارید.
• برای هر برنامه، سرور یا pipeline یک توکن جدا با کمترین scope لازم بسازید تا بتوانید یکی را بدون اختلال در بقیه باطل کنید.
• برای توکن‌های CI تاریخ انقضا و فهرست IP بگذارید و آن‌ها را مرتب عوض کنید.
• اگر توکنی لو رفت، همان لحظه آن را در پنل باطل کنید.

نمونه در CI (متغیر محرمانه ARIANET_TOKEN در تنظیمات پروژه تعریف شده است):

.gitlab-ci.yml

deploy:
  image: alpine:3.20
  script:
    - apk add --no-cache curl
    - curl -fsS https://api.ariaservice.net/cloud/v1/servers -H "Authorization: Bearer $ARIANET_TOKEN"

.github/workflows/deploy.yml

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ARIANET_TOKEN: ${{ secrets.ARIANET_TOKEN }}
    steps:
      - run: curl -fsS https://api.ariaservice.net/cloud/v1/servers -H "Authorization: Bearer $ARIANET_TOKEN"

خطاهای احراز هویت

HTTP	یعنی	چه کنید
401	توکن نیست، نامعتبر است، منقضی یا باطل شده	هدر Authorization: Bearer <token> را بررسی کنید یا توکن تازه بسازید
403	توکن معتبر است اما scope لازم را ندارد (insufficient_scope / INSUFFICIENT_SCOPE)، IP مجاز نیست (IP_NOT_ALLOWED)، یا حساب اجازه این کار را ندارد (forbidden، identity_needed)	scope یا فهرست IP توکن را اصلاح کنید؛ برای identity_needed احراز هویت حساب را در پنل کامل کنید