کلیدهای API

🖼

تصویر: مدیریت API Key در داشبوردplaceholder — تصویر را اینجا جایگزین کنید

کلیدهای API توکن‌های طولانی‌مدتی هستند که برای دسترسی برنامه‌نویسی به ابرکلیک طراحی شده‌اند. از کلیدهای API در CI/CD، اسکریپت‌های اتوماسیون، SDK و ابزارهای خارجی استفاده می‌کنید.

اطلاع

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

سطوح دسترسی (Scopes)

هنگام ساخت کلید API، می‌توانید محدوده دسترسی آن را تعیین کنید:

Scope	شرح
deploy	دسترسی به دیپلوی و مدیریت اپلیکیشن‌ها
db	دسترسی به ایجاد و مدیریت دیتابیس‌ها
registry	دسترسی به Harbor و مدیریت ایمیج‌ها
admin	مدیریت کلیدهای API (ساخت/حذف کلید)

هشدار

کلیدی که scope admin ندارد، نمی‌تواند کلیدهای دیگر بسازد یا حذف کند (حفاظت در برابر افزایش دسترسی).

ساخت کلید API

۱. وارد داشبورد ابرکلیک شوید. ۲. از منوی بالا سمت راست، روی نام کاربری خود کلیک کنید و پروفایل را انتخاب کنید. ۳. به بخش کلیدهای API بروید. ۴. روی دکمه کلید جدید کلیک کنید. ۵. یک نام توصیفی برای کلید وارد کنید (مثلاً: github-actions یا deploy-script). ۶. سطوح دسترسی (scopes) مورد نیاز را انتخاب کنید. ۷. (اختیاری) برای تعیین تاریخ انقضا، فیلد Expires At را پر کنید. ۸. روی ایجاد کلیک کنید.

هشدار

کلید API تنها یک بار در لحظه ساخت نمایش داده می‌شود. آن را در جای امنی ذخیره کنید — پس از بستن این پنجره دیگر قابل مشاهده نخواهد بود.

استفاده در درخواست‌های HTTP

کلید API را در هدر Authorization درخواست‌های خود قرار دهید:

curl -H "Authorization: Bearer <api_key>" \
  https://api.abrclick.ir/v1/projects

استفاده در SDK

import { AbrclickClient } from '@abrclick/sdk';

const client = new AbrclickClient({ apiKey: process.env.ABRCLICK_API_KEY });

استفاده در CI/CD

GitHub Actions

کلید API را به عنوان secret در تنظیمات مخزن خود اضافه کنید:

Settings → Secrets and variables → Actions → New repository secret

• نام: ABRCLICK_API_KEY
• مقدار: کلید API خود را وارد کنید

سپس در workflow خود استفاده کنید:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install CLI
        run: npm install -g @abrclick/cli

      - name: Deploy
        run: abrclick deploy --no-follow
        env:
          ABRCLICK_API_KEY: ${{ secrets.ABRCLICK_API_KEY }}

GitLab CI

کلید API را در Settings → CI/CD → Variables اضافه کنید و نوع آن را Masked انتخاب کنید:

deploy:
  stage: deploy
  script:
    - npm install -g @abrclick/cli
    - abrclick deploy --no-follow
  variables:
    ABRCLICK_API_KEY: $ABRCLICK_API_KEY

هشدار

کلید API را مستقیماً در کد یا repository ذخیره نکنید. همیشه از environment variables یا secret managers استفاده کنید.

مدیریت کلیدها از طریق API

ساخت کلید جدید

POST /v1/api-keys

نمونه با scope و انقضا:

curl -X POST https://api.abrclick.ir/v1/api-keys \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-ci-key",
    "scopes": ["deploy"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

پاسخ:

{
  "id": "key_01j2abc...",
  "name": "my-ci-key",
  "key": "abr_live_xxxxxxxxxxxxxxxxxxxx",
  "scopes": ["deploy"],
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-06-29T10:00:00Z"
}

اطلاع

فیلد key در پاسخ این endpoint نیز تنها یک بار برگردانده می‌شود.

لیست کلیدها

GET /v1/api-keys

curl https://api.abrclick.ir/v1/api-keys \
  -H "Authorization: Bearer <api_key>"

پاسخ:

[
  {
    "id": "key_01j2abc...",
    "name": "my-ci-key",
    "scopes": ["deploy"],
    "createdAt": "2026-06-29T10:00:00Z",
    "lastUsedAt": "2026-06-29T12:30:00Z",
    "expiresAt": null
  }
]

حذف کلید

DELETE /v1/api-keys/:id

curl -X DELETE https://api.abrclick.ir/v1/api-keys/key_01j2abc... \
  -H "Authorization: Bearer <api_key>"

هشدار

حذف کلید فوری است. تمام درخواست‌هایی که از آن کلید استفاده می‌کنند بلافاصله با خطای 401 Unauthorized مواجه خواهند شد.

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

• یک کلید به ازای هر محیط: برای production، staging و توسعه محلی کلیدهای جداگانه بسازید.
• نام‌گذاری توصیفی: از نام‌هایی مثل github-actions-prod یا gitlab-staging استفاده کنید تا منشأ هر کلید مشخص باشد.
• چرخش منظم: کلیدهای قدیمی را حذف و جایگزین کنید، به خصوص پس از تغییر اعضای تیم.
• حداقل دسترسی: فقط scopeهای ضروری را اختصاص دهید. از admin scope فقط برای مدیریت کلیدها استفاده کنید.
• تاریخ انقضا: برای کلیدهای موقت (CI پروژه کوتاه‌مدت)، تاریخ انقضا تعیین کنید.