使用非對稱金鑰密碼術向 Zonos 驗證您的後端服務 — 無需共享祕密。
Zonos 支援透過 OAuth 2.0 JWT Bearer Token Grant (RFC 7523) 的機器對機器驗證。您的服務使用您的 RSA 私鑰簽署短期 JWT；Zonos 使用您註冊的公鑰驗證它，並返回範圍限於您組織的 Bearer 令牌。
流程摘要：
Authorization: Bearer <token>
生成 4096 位元 RSA 金鑰對，並與 Zonos 分享公鑰。這在上線期間執行一次。
# 生成私鑰
openssl genrsa -out private_key.pem 4096
# 提取公鑰
openssl rsa -in private_key.pem -pubout -out public_key.pem
與 Zonos 分享 public_key.pem。將 private_key.pem 儲存在專用祕密管理器中（AWS Secrets Manager、HashiCorp Vault 等）— 不要在原始碼管理或環境變數中。
public_key.pem
private_key.pem
Zonos 將註冊您的金鑰，並返回您的組織 ID，這將成為所有 JWT 宣告中的 iss 聲明。
iss
使用您的私鑰以 RS256 簽署 JWT。宣告對單次令牌交換有效 — 保持有效期窗口較短（60–300 秒）。
RS256
"org_abc123"
sub
"checkout-service"
aud
"zonos-auth"
exp
iat
jti
JWT 標頭必須指定 "alg": "RS256" 和 "typ": "JWT"。
"alg": "RS256"
"typ": "JWT"
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",
)
將簽署的 JWT 發送至 Zonos 令牌端點以接收短期 Bearer 令牌。
POST https://auth.zonos.com/oauth/token Content-Type: application/json
也接受 application/x-www-form-urlencoded。
application/x-www-form-urlencoded
grant_type
"urn:ietf:params:oauth:grant-type:jwt-bearer"
assertion
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
access_token
token_type
"Bearer"
expires_in
scope
import requests
response = requests.post(
"https://auth.zonos.com/oauth/token",
json={
"grant_type": ,
: assertion,
data = response.json()
access_token = data[]
expires_in = data[]
在 Authorization 標頭中將存取令牌作為 Bearer 令牌包含在每個 Zonos API 請求上。
Authorization
Bearer
curl -X POST https://api.zonos.com/graphql \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{ "query": "{ ... }" }'
存取令牌預設在 5 分鐘後到期。快取令牌並主動刷新 — 不要在每個 API 呼叫上要求新令牌。每次刷新都需要新簽署的 JWT 宣告。
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(
"assertion": assertion,
).json()
_cache["access_token"] = data["access_token"]
_cache["expires_at"] = time.time() + data["expires_in"]
所有錯誤都遵循 OAuth 2.0 錯誤回應格式 (RFC 6749 §5.2)：
"error": "invalid_grant",
"error_description": "JWT assertion has expired"
error
400
unsupported_grant_type
urn:ietf:params:oauth:grant-type:jwt-bearer
invalid_request
401
invalid_grant
500
server_error
常見 invalid_grant 原因：
OAuth 2.0 驗證
OAuth 2.0 驗證
使用非對稱金鑰密碼術向 Zonos 驗證您的後端服務 — 無需共享祕密。
Zonos 支援透過 OAuth 2.0 JWT Bearer Token Grant (RFC 7523) 的機器對機器驗證。您的服務使用您的 RSA 私鑰簽署短期 JWT；Zonos 使用您註冊的公鑰驗證它，並返回範圍限於您組織的 Bearer 令牌。
流程摘要：
Authorization: Bearer <token>。第 1 步 — 註冊您的公鑰（一次性設定）
生成 4096 位元 RSA 金鑰對，並與 Zonos 分享公鑰。這在上線期間執行一次。
生成金鑰對
# 生成私鑰openssl genrsa -out private_key.pem 4096# 提取公鑰openssl rsa -in private_key.pem -pubout -out public_key.pem與 Zonos 分享
public_key.pem。將private_key.pem儲存在專用祕密管理器中（AWS Secrets Manager、HashiCorp Vault 等）— 不要在原始碼管理或環境變數中。Zonos 將註冊您的金鑰，並返回您的組織 ID，這將成為所有 JWT 宣告中的
iss聲明。第 2 步 — 建構 JWT 宣告
使用您的私鑰以
RS256簽署 JWT。宣告對單次令牌交換有效 — 保持有效期窗口較短（60–300 秒）。必需的聲明
iss"org_abc123"）sub"checkout-service"）aud"zonos-auth"expiat後的 60–300 秒iatjtiJWT 標頭必須指定
"alg": "RS256"和"typ": "JWT"。程式碼範例
import jwt, uuid, timewith 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",)第 3 步 — 將宣告交換為存取令牌
將簽署的 JWT 發送至 Zonos 令牌端點以接收短期 Bearer 令牌。
端點
也接受
application/x-www-form-urlencoded。請求欄位
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertion請求和回應
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscope完整程式碼範例
import requestsresponse = requests.post("https://auth.zonos.com/oauth/token",json={"grant_type": ,: assertion,},)data = response.json()access_token = data[]expires_in = data[]第 4 步 — 使用存取令牌呼叫 Zonos API
在
Authorization標頭中將存取令牌作為Bearer令牌包含在每個 Zonos API 請求上。範例請求
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'令牌生命週期和快取
存取令牌預設在 5 分鐘後到期。快取令牌並主動刷新 — 不要在每個 API 呼叫上要求新令牌。每次刷新都需要新簽署的 JWT 宣告。
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"]錯誤參考
所有錯誤都遵循 OAuth 2.0 錯誤回應格式 (RFC 6749 §5.2)：
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_type不是urn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_error常見
invalid_grant原因：exp在過去 — 確保您的系統時鐘是 NTP 同步的aud不是"zonos-auth"iss與您註冊的組織 ID 不相符安全最佳實踐
jti。 每個宣告的唯一值可啟用伺服器端重播偵測。access_token或assertion值。 將兩者視為認證。這個頁面有幫助嗎？