Bước 1 — Đăng ký khóa công khai của bạn (thiết lập một lần)
Tạo cặp khóa RSA 4096-bit và chia sẻ khóa công khai với Zonos. Điều này được thực hiện một lần trong quá trình onboarding.
Tạo cặp khóa
# Generate private keyopenssl genrsa -out private_key.pem 4096 # Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemChia sẻ public_key.pem với Zonos. Lưu trữ private_key.pem trong trình quản lý bí mật chuyên dụng (AWS Secrets Manager, HashiCorp Vault, v.v.) — không bao giờ trong kiểm soát nguồn hoặc biến môi trường.
Zonos sẽ đăng ký khóa của bạn và trả về ID Tổ chức của bạn, trở thành yêu cầu iss trong tất cả các xác nhận JWT.
Bước 2 — Xây dựng một xác nhận JWT
Ký một JWT bằng RS256 bằng cách sử dụng khóa riêng của bạn. Xác nhận có hiệu lực cho một lần trao đổi token duy nhất — giữ cửa sổ hết hạn ngắn (60–300 giây).
Yêu cầu các đòi hỏi
| Yêu cầu↕ | Giá trị↕ |
|---|---|
iss | ID Tổ chức Zonos của bạn (ví dụ: "org_abc123") |
sub | Xác định dịch vụ gọi (ví dụ: "checkout-service") |
aud | Phải chính xác "zonos-auth" |
exp | Dấu thời gian Unix; 60–300 giây từ iat |
iat | Dấu thời gian Unix của cấp phát |
jti | UUID duy nhất cho mỗi xác nhận (bật phát hiện phát lại) |
Tiêu đề JWT phải chỉ định "alg": "RS256" và "typ": "JWT".
Ví dụ về mã
import jwt, uuid, time with open("private_key.pem") as f: private_key = f.read() now = int(time.time())assertion = jwt.encode( { "iss": "org_abc123", "sub": "checkout-service", "aud": "zonos-auth", "iat": now, "exp": now + 300, "jti": str(uuid.uuid4()), }, private_key, algorithm="RS256",)Bước 3 — Trao đổi xác nhận cho token truy cập
Gửi JWT đã ký đến điểm cuối token Zonos để nhận token Bearer có thời gian sống ngắn.
Điểm cuối
POST https://auth.zonos.com/oauth/token
Content-Type: application/json
application/x-www-form-urlencoded cũng được chấp nhận.
Trường yêu cầu
| Trường↕ | Bắt buộc↕ | Giá trị↕ |
|---|---|---|
grant_type | Có | "urn:ietf:params:oauth:grant-type:jwt-bearer" |
assertion | Có | JWT đã ký của bạn (nén dạng tuần tự) |
Yêu cầu và phản hồi
{ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}| Trường phản hồi↕ | Mô tả↕ |
|---|---|
access_token | Token Bearer cho tất cả các yêu cầu API tiếp theo |
token_type | Luôn "Bearer" |
expires_in | Giây cho đến khi hết hạn (mặc định: 300) |
scope | Các quyền được cấp cho token này, được phân tách bằng dấu cách |
Ví dụ mã đầy đủ
import requests response = requests.post( "https://auth.zonos.com/oauth/token", json={ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion, },)data = response.json()access_token = data["access_token"]expires_in = data["expires_in"]Bước 4 — Gọi API Zonos bằng token truy cập
Bao gồm token truy cập dưới dạng token Bearer trong tiêu đề Authorization trên mỗi yêu cầu API Zonos.
Yêu cầu ví dụ
curl -X POST https://api.zonos.com/graphql \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "query": "{ ... }" }'Vòng đời token và bộ nhớ cache
Token truy cập hết hạn trong 5 phút theo mặc định. Lưu trữ token trong bộ nhớ cache và làm mới một cách chủ động — không yêu cầu token mới trên mỗi lệnh gọi API. Mỗi lần làm mới yêu cầu một xác nhận JWT được ký lại.
import time, requests _cache = {"access_token": None, "expires_at": 0} def get_access_token(): if time.time() < _cache["expires_at"] - 30: return _cache["access_token"] assertion = build_jwt_assertion() data = requests.post( "https://auth.zonos.com/oauth/token", json={ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion, }, ).json() _cache["access_token"] = data["access_token"] _cache["expires_at"] = time.time() + data["expires_in"] return _cache["access_token"]Tham khảo lỗi
Tất cả các lỗi tuân theo định dạng phản hồi lỗi OAuth 2.0 (RFC 6749 §5.2):
{ "error": "invalid_grant", "error_description": "JWT assertion has expired"}| Trạng thái HTTP↕ | error↕ | Nguyên nhân↕ |
|---|---|---|
400 | unsupported_grant_type | grant_type không phải urn:ietf:params:oauth:grant-type:jwt-bearer |
400 | invalid_request | Trường bị thiếu hoặc sai định dạng |
401 | invalid_grant | Chữ ký không hợp lệ, xác nhận hết hạn, tổ chức không xác định hoặc khóa chưa đăng ký |
500 | server_error | Lỗi nội bộ — liên hệ hỗ trợ Zonos nếu kiên trì |
Nguyên nhân phổ biến của invalid_grant:
expnằm trong quá khứ — đảm bảo đồng hồ hệ thống của bạn được đồng bộ NTPaudkhông chính xác"zonos-auth"isskhông khớp với ID Tổ chức đã đăng ký của bạn- Khóa công khai đã được xoay nhưng chưa được cập nhật với Zonos
Các thực hành bảo mật tốt nhất
- Bảo vệ khóa riêng của bạn. Lưu trữ nó trong trình quản lý bí mật chuyên dụng — không bao giờ trong kiểm soát nguồn, biến môi trường hoặc nhật ký.
- Giữ xác nhận ngắn. 60–300 giây là tiêu chuẩn; không có lý do để phát hành những cái dài hơn.
- Bao gồm
jti. Một giá trị duy nhất cho mỗi xác nhận cho phép phát hiện phát lại phía máy chủ. - Xoay cặp khóa định kỳ. Đăng ký khóa công khai mới với Zonos trước khi thu hồi khóa cũ để tránh ngừng hoạt động.
- Không bao giờ ghi nhật ký
access_tokenhoặcassertiongiá trị. Coi cả hai là thông tin xác thực.
Xác thực OAuth 2.0
Xác thực các dịch vụ phía sau của bạn với Zonos bằng cách sử dụng mã hóa khóa bất đối xứng — không cần bí mật chia sẻ.
Zonos hỗ trợ xác thực máy chủ sang máy chủ thông qua OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Dịch vụ của bạn ký một JWT có thời gian sống ngắn bằng khóa riêng RSA của bạn; Zonos xác minh nó bằng cách sử dụng khóa công khai đã đăng ký của bạn và trả về một token Bearer được phân vùng theo tổ chức của bạn.
Tóm tắt luồng:
Authorization: Bearer <token>trên mỗi yêu cầu API.