مرجع API

API keyهای پروژه

با JWT کاربر یک API key مخصوص پروژه بسازید. secret را همان لحظهٔ صدور ذخیره کنید؛ بعداً می‌توانید کلید را در فهرست ببینید، تعویض یا باطل کنید.

روند کار

01صدور API key برای پروژه
02فهرست API keyهای پروژه
03تعویض API key با بازهٔ همپوشانی

روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.

صدور API key برای پروژه

POST/api/v1/tenancy/projects/{project_id}/credentials

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

نوع محتواapplication/json

پارامترها

این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`project_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ پروژه.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`attributed_team`	Body	string	اختیاری	مخصوص مهوش	تیمی که مصرف همهٔ requestهای این کلید به حسابش نوشته می‌شود. فقط برای گزارش مصرف است و دسترسی نمی‌دهد.
`expires_at`	Body	string	اختیاری	مخصوص مهوش	زمانی با قالب ISO 8601 که پس از آن کلید از کار می‌افتد.
`name`	Body	string	الزامی	مخصوص مهوش	نامی برای شناسایی کلید.
`scopes`	Body	array<value>	اختیاری	مخصوص مهوش	فهرست scopeهای مجاز. اگر نفرستید یا خالی بفرستید، کلید همهٔ کارهای مجاز در پروژه را می‌تواند انجام دهد.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>/credentials' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "production-backend"
}'

Response

{
  "status": 201,
  "data": {
    "credential": {
      "id": "<credential-uuid>",
      "project": "<project-uuid>",
      "name": "Server integration",
      "prefix": "<key-prefix>",
      "status": "ACTIVE"
    },
    "token": "<shown-once-project-api-key>"
  }
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
201	منبع ساخته شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

فهرست API keyهای پروژه

GET/api/v1/tenancy/projects/{project_id}/credentials

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`project_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ پروژه.
`search`	Query	string	اختیاری	مخصوص مهوش	جست‌وجو در نام کلید و پیشوند عمومی آن، بدون حساسیت به حروف بزرگ و کوچک.
`status`	Query	string	اختیاری	مخصوص مهوش	فیلتر بر اساس `ACTIVE`، `ROTATING` یا `REVOKED`.
`page`	Query	integer	اختیاری	مخصوص مهوش	شمارهٔ صفحه (از ۱)، وقتی صفحه‌بندی می‌خواهید.
`page_size`	Query	integer	اختیاری	مخصوص مهوش	اندازهٔ صفحه از ۱ تا ۱۰۰، وقتی صفحه‌بندی می‌خواهید.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>/credentials' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

تعویض API key با بازهٔ همپوشانی

POST/api/v1/tenancy/credentials/{credential_id}/rotate

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`credential_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ API key.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/credentials/<credential_id>/rotate' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
201	منبع ساخته شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

باطل کردن فوری API key

DELETE/api/v1/tenancy/credentials/{credential_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`credential_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ API key.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X DELETE 'https://api.mahvashai.ir/api/v1/tenancy/credentials/<credential_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.