Xác thực
Một loại thông tin xác thực, và các cách một yêu cầu bị từ chối.
Header
URL gốc là localhost:2222. Mọi yêu cầu đều mang khóa trong header Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Không có cách xác thực nào khác ở đây. Cookie phiên và token phiên đều bị từ chối với invalid_credential_type, mã lỗi này nêu rõ thông tin xác thực cần gửi thay thế thay vì để bạn phải đoán từ một mã 401 trơn.
Kiểm tra khóa có hoạt động không
GET /ping là bài kiểm tra nhanh: nó không cần phạm vi nào và cho bạn biết khóa đó là gì.
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"}Nếu lệnh này chạy được mà lệnh khác trả về 401, vấn đề nằm ở phạm vi chứ không phải ở khóa.
scopes là danh sách CÓ HIỆU LỰC và là danh sách duy nhất cấp quyền cho bất kỳ thao tác nào. grantedScopes là những gì khóa được cấp khi phát hành, và hai danh sách chỉ khác nhau khi một vai trò đang giới hạn khóa. Trang Phạm vi giải thích phần giao đó. roleId bằng null nghĩa là không có giới hạn trên, đây là mức rộng nhất mà một khóa có thể có.
Xem khóa được phép gửi dưới danh nghĩa địa chỉ nào
GET /addresses là lời giải cho một mã 403 bạn không ngờ tới.
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 có ba nguyên nhân: địa chỉ đã bị tắt, phạm vi gửi của khóa không bao gồm nó (cả tên miền lẫn bản thân địa chỉ đều không có trên khóa), hoặc tên miền chưa thể ký thư. enabled trên địa chỉ và sendingVerified trên tên miền của nó giúp phân biệt các trường hợp này, và đó là phần lớn thời gian gỡ lỗi mà endpoint này tiết kiệm cho bạn. Một tên miền có thể đã được xác minh để nhận thư nhưng vẫn chưa gửi được.
unrestricted: true nghĩa là mọi local-part trên một tên miền đã xác minh đều được chấp nhận, kể cả những local-part chưa ai tạo.
Cách một khóa bị từ chối
| Mã | Ý nghĩa |
|---|---|
| missing_api_key | Hoàn toàn không có header Authorization. |
| invalid_credential_type | Là cookie hoặc token phiên. Hãy gửi khóa API. |
| invalid_api_key | Không phải khóa do chúng tôi cấp, hoặc chuỗi bí mật không khớp. |
| revoked_api_key | Được cấp tại đây, sau đó bị thu hồi. Được tách riêng có chủ đích. Đó là khác biệt giữa năm phút sửa lỗi và cả một buổi chiều. |
| expired_api_key | Được cấp tại đây, sau đó hết hạn. |
| insufficient_scope | Khóa hợp lệ, nhưng thiếu phạm vi mà endpoint này yêu cầu. |
Việc thu hồi có hiệu lực từ lệnh gọi tiếp theo. Hàng của khóa vẫn còn trên trang khóa sau đó, nên bạn vẫn biết được có thứ gì đang dùng khóa lúc bạn vô hiệu hóa nó hay không. Trạng thái hữu ích nhất trên màn hình đó là “chưa từng dùng”, vì đó là cách phân biệt một khóa bị lộ với một phụ thuộc đang hoạt động.
Xoay vòng là cách còn lại để loại bỏ một chuỗi bí mật. Thao tác này tạo chuỗi bí mật mới cho cùng một khóa, nên id, tên, các phạm vi, vai trò, phạm vi gửi cùng mọi hàng yêu cầu và hoạt động đều được giữ nguyên; chỉ chuỗi bí mật thay đổi. Chuỗi cũ ngừng hoạt động ngay khi xoay vòng hoàn tất, không có khoảng thời gian chồng lấn, và chuỗi thay thế chỉ hiển thị một lần. Trong bảng điều khiển, thao tác này nằm cùng menu với Thu hồi và yêu cầu bạn xác minh lại trước. Một khóa có keys:write cũng có thể tự xoay vòng bằng POST /keys/self/rotate, đó là cách một tích hợp xoay vòng theo lịch mà không cần ai mở bảng điều khiển.