احراز هویت
یک نوع اعتبارنامه، و راههایی که یک درخواست رد میشود.
هدر
نشانی پایه api.openemail.uk است. هر درخواست کلید را در یک هدر Authorization با خود میآورد.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…هیچ چیز دیگری اینجا احراز هویت نمیکند. کوکی نشست و توکن نشست هر دو با invalid_credential_type رد میشوند، که بهجای رها کردن شما با یک 401 لخت، نام اعتبارنامهای را که باید بفرستید میگوید.
بررسی اینکه کلید کار میکند
GET /ping آزمون سریع است: به هیچ دامنه دسترسیای نیاز ندارد و به شما میگوید کلید چیست.
curl "$OE/ping" -H "$AUTH"{ "ok": true, "keyId": "4c1b257a66287fd113bd89d0", "mode": "live", "scopes": ["emails:send", "emails:read"], "roleId": null, "grantedScopes": ["emails:send", "emails:read"], "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}اگر این کار کند و جای دیگری 401 بدهد، مشکل از دامنه دسترسی است، نه از کلید.
scopes فهرست مؤثر است و تنها فهرستی که چیزی را مجاز میکند. grantedScopes همان چیزی است که کلید با آن صادر شده، و این دو تنها زمانی فرق میکنند که یک نقش سقفی برای کلید گذاشته باشد. صفحهٔ دامنههای دسترسی آن اشتراک را توضیح میدهد. roleId برابر null یعنی هیچ سقفی نیست، که گشادهترین حالتی است که یک کلید میگیرد.
ببینید یک کلید با چه نشانیهایی میتواند بفرستد
GET /addresses پاسخِ آن 403ی است که انتظارش را نداشتید.
curl "$OE/addresses" -H "$AUTH"{ "object": "list", "unrestricted": false, "data": [ { "object": "address", "address": "[email protected]", "enabled": true, "canSend": true }, { "object": "address", "address": "[email protected]", "enabled": true, "canSend": false } ], "domains": [ { "domain": "acme.com", "receivingVerified": true, "sendingVerified": true, "catchAll": false } ]}canSend: false سه علت دارد: نشانی خاموش است، دامنه دسترسی ارسالِ کلید آن را در بر نمیگیرد (نه دامنهاش و نه خود نشانی روی کلید نیست)، یا دامنه هنوز نمیتواند امضا کند. enabled روی نشانی و sendingVerified روی دامنهاش اینها را از هم جدا میکنند، و بیشترِ وقتِ اشکالزدایی که این نقطه پایانی برایتان صرفهجویی میکند همین است. یک دامنه میتواند برای دریافت تأیید شده باشد و باز هم نتواند بفرستد.
unrestricted: true یعنی هر بخش محلی روی یک دامنهٔ تأییدشده پذیرفته میشود، حتی آنهایی که هنوز کسی نساخته است.
چگونه یک کلید رد میشود
| کد | معنا |
|---|---|
| missing_api_key | اصلاً هدر Authorization نیست. |
| invalid_credential_type | یک کوکی یا یک توکن نشست. یک کلید API بفرستید. |
| invalid_api_key | کلیدی نیست که ما صادر کرده باشیم، یا راز آن نمیخواند. |
| revoked_api_key | اینجا صادر شده و سپس باطل شده. عمداً جدا نگه داشته شده. فرق میان یک رفعاشکال پنجدقیقهای و یک بعدازظهر است. |
| expired_api_key | اینجا صادر شده و سپس منقضی شده. |
| insufficient_scope | کلیدی واقعی، بدون دامنه دسترسیای که این نقطه پایانی میخواهد. |
ابطال از فراخوانی بعدی اثر میکند. ردیف پس از آن روی صفحهٔ کلیدها میماند، تا باز هم بتوانید بگویید وقتی کلید را کشتید چیزی از آن استفاده میکرد یا نه. سودمندترین وضعیت در آن صفحه «هرگز استفاده نشده» است، چون همین است که کلید لو رفته را از یک وابستگی زنده جدا میکند.
چرخاندن راه دیگر بازنشستهکردن یک راز است. برای همان کلید راز تازهای ضرب میکند، پس شناسه، نام، دامنههای دسترسی، نقش، دامنه دسترسی ارسال و هر ردیف درخواست و فعالیت همه ادامه مییابند؛ تنها راز عوض میشود. راز قدیمی همان لحظه که چرخش کامل میشود از کار میافتد، بدون هیچ پنجرهٔ همپوشانی، و جایگزین یک بار نشان داده میشود. در کنسول در همان منویی است که Revoke هست و از شما میخواهد اول دوباره هویتتان را تأیید کنید. کلیدی که keys:write دارد میتواند خودش را هم با POST /keys/self/rotate بچرخاند، و یکپارچهسازیها اینگونه طبق زمانبندی میچرخند بیآنکه کسی کنسول را باز کند.