Xác thực

Định dạng khóa#

esk_live_<prefix:10>_<secret:40>

Khóa là chuỗi chữ và số gồm tiền tố 10 ký tự (mã định danh công khai hiển thị trong cổng) và phần bí mật 40 ký tự. esimoa chỉ lưu mã băm SHA-256, nên khóa đầy đủ chỉ hiển thị một lần khi cấp và không thể khôi phục.

Sending the key#

Gửi khóa trong header X-API-Key ở mọi yêu cầu; Authorization: Bearer cũng được chấp nhận. Không có khóa sẽ trả về 401 API_KEY_REQUIRED, khóa sai định dạng hoặc không xác định sẽ trả về 401 INVALID_API_KEY.

# Preferred
X-API-Key: esk_live_AbCdE12345_<40-character secret>

# Also accepted
Authorization: Bearer esk_live_AbCdE12345_<40-character secret>

Issuing keys#

1. 1Cổng đối tác → Khóa API — tạo khóa mới.
2. 2Đặt tên và tùy chọn thời hạn (từ 1 phút đến 3 năm kể từ bây giờ) cùng danh sách IP cho phép.
3. 3Sao chép khóa ngay — khóa chỉ hiển thị một lần — và lưu vào trình quản lý bí mật hoặc biến môi trường của máy chủ.

Theo mặc định, mỗi tài khoản có thể có tối đa 5 khóa đang hoạt động (khóa chưa bị thu hồi và chưa hết hạn).

Rotating keys#

Xoay vòng sẽ tạo khóa mới có cùng tên, phạm vi, danh sách IP được phép và thời hạn. Khóa cũ vẫn hoạt động trong thời gian gia hạn bạn chọn (0–72 giờ) rồi hết hạn — hãy triển khai khóa mới trong khoảng thời gian đó. Thời gian gia hạn bằng 0 sẽ vô hiệu hóa khóa cũ ngay lập tức.

IP allowlist#

Mỗi khóa có thể giới hạn tối đa 20 địa chỉ IPv4/IPv6 hoặc dải CIDR (ví dụ: 203.0.113.10, 198.51.100.0/24). Danh sách trống nghĩa là không giới hạn; yêu cầu từ nơi khác sẽ nhận lỗi 403 IP_NOT_ALLOWED. Hãy dùng IP đầu ra (egress) của máy chủ.

Revoking keys#

Hãy thu hồi khóa trong cổng ngay khi bị lộ hoặc không còn cần dùng. Khóa không được lưu bộ nhớ đệm nên yêu cầu ngay sau đó sẽ bị từ chối với 401 KEY_REVOKED. Trong trường hợp khẩn cấp, esimoa có thể thu hồi khóa hoặc tạm ngưng tài khoản; mọi khóa của tài khoản bị tạm ngưng sẽ nhận 403 PARTNER_SUSPENDED.

Member roles#

Chỉ thành viên OWNER, ADMIN và DEVELOPER mới có thể cấp, xoay vòng hoặc thu hồi khóa; mọi thành viên đều xem được danh sách khóa.