کلیدهای API

GET /keys هر کلیدی را که فراخوان می‌تواند ببیند فهرست می‌کند، تازه‌ترین اول و صفحه‌به‌صفحه، با وضعیت، اسکوپ‌ها، نقش، دامنهٔ ارسال، آخرین استفاده و اینکه چه کسی آن را ساخت و آخرین بار تغییر داد. GET /keys/{id} یکی را می‌خواند. هیچ خواندنی هرگز رمز را برنمی‌گرداند: maskedKey برای تشخیص دو کلید کافی است. هر دو به keys:read نیاز دارند.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys کلیدی می‌سازد و رمزش را در token یک بار برمی‌گرداند. اگر داده نشوند، اسکوپ emails:send است و نقش، دامنهٔ ارسال و انقضا همان‌هایی‌اند که فراخوان دارد.
• —PATCH /keys/{id} نام کلید را عوض می‌کند، اسکوپ‌ها یا دامنهٔ ارسالش را جایگزین می‌کند و با enabled آن را خاموش و روشن می‌کند. خاموش کردن گزینهٔ برگشت‌پذیر است: کلید همه‌چیز را نگه می‌دارد و تا دوباره روشن نشود با inactive_api_key رد می‌شود.
• —POST /keys/{id}/rotate به کلید رمز تازه‌ای می‌دهد و آن را یک بار برمی‌گرداند. رمز قبلی همان لحظه‌ای که فراخوانی برمی‌گردد از کار می‌افتد.
• —POST /keys/{id}/revoke کلید را برای همیشه کنار می‌گذارد، با reason اختیاری. سپس DELETE /keys/{id} آن را از فهرست برمی‌دارد و تاریخچه‌اش را نگه می‌دارد.
• —همهٔ آن‌ها به keys:manage نیاز دارند. چرخاندن خود کلید فراخوان با keys:write هم کار می‌کند، درست مانند POST /keys/self/rotate.

هر تغییر در برابر کلیدی که آن را انجام می‌دهد سنجیده می‌شود. کلیدی که در هر محوری بیرون از فراخوان قرار بگیرد با 403 beyond_caller_authority رد می‌شود و param آن محور را نام می‌برد:

• —اسکوپ‌ها: فقط اسکوپ‌هایی که فراخوان پس از محدود شدن با نقش خودش دارد.
• —نقش: فراخوانی که نقشی سقفش را تعیین کرده فقط می‌تواند کلیدهایی با همان نقش بسازد و مدیریت کند.
• —انقضا: فراخوانی که منقضی می‌شود فقط می‌تواند کلیدهایی بسازد و مدیریت کند که دیرتر از آن منقضی نشوند.
• —حالت: کلید آزمایشی فقط به کلیدهای آزمایشی می‌رسد.
• —دامنهٔ ارسال: فقط دامنه‌ها و نشانی‌های درون دامنهٔ فراخوان، و داشتن یک نشانی هرگز کل دامنه‌اش را پوشش نمی‌دهد.

کنسول پیش از ساختن یا چرخاندن کلید از شما می‌خواهد دوباره هویتتان را تأیید کنید. این را نمی‌توان از فراخوانی‌ای که با کلید انجام می‌شود خواست، پس keys:manage اعتباری است که اعتبار می‌سازد: کلید لورفته‌ای که آن را دارد می‌تواند کلیدهای خودش را بسازد، تا حد دسترسی خودش، که پس از باطل شدنش هم کار می‌کنند.

• —keys:manage را فقط به خودکارسازی‌ای بدهید که کارش صدور کلید است، هرگز به کلیدی که ایمیل می‌فرستد.
• —آن کلید را محدود کنید: یک نقش، یک دامنهٔ ارسال و یک انقضا. هر چه می‌سازد هر سه را به ارث می‌برد و هرگز نمی‌تواند از آن‌ها فراتر برود.
• —GET /keys/activity را زیر نظر بگیرید. هر کلیدی که می‌سازد، تغییر می‌دهد یا باطل می‌کند به نام او ثبت می‌شود، پس نشت به شکل کلیدهایی که انتظارشان را نداشتید دیده می‌شود.
• —keys:read گزارش درخواست‌ها را، با نشانی‌های IP و عامل‌های کاربر، آشکار می‌کند. با آن مانند دسترسی حسابرسی رفتار کنید.

GET /keys/requests و GET /keys/{id}/requests هر فراخوانی احرازشده‌ای را که یک کلید انجام داده می‌خوانند، تازه‌ترین اول: متد، مسیر، وضعیت، کد خطا، مدت، IP و عامل کاربر، هرگز بدنه یا رشتهٔ پرس‌وجو. keyIds، failedOnly، since و until فیلترهایی‌اند که کنسول ارائه می‌کند. GET /keys/activity و GET /keys/{id}/activity می‌خوانند چه بر سر کلیدها آمد، و actor نام می‌برد چه کسی آن را انجام داد، به‌صورت @username یا API key <name>. هیچ چیز پاک نمی‌شود و کلید حذف‌شده تاریخچه‌اش را نگه می‌دارد.