使用非對稱金鑰密碼學對您的後端服務進行 Zonos 驗證——無需共享密鑰。
Zonos 支持通過 OAuth 2.0 JWT Bearer 令牌授予 (RFC 7523) 進行機器到機器驗證。您的服務使用您的 RSA 私鑰簽署短期有效的 JWT；Zonos 使用您註冊的公鑰驗證該 JWT 並返回一個以您的組織為範圍的 Bearer 令牌。
流程摘要：
Authorization: Bearer <token>
生成 4096 位 RSA 金鑰對，並與 Zonos 共享公鑰。這在上線期間進行一次。
# Generate private key
openssl genrsa -out private_key.pem 4096
# Extract public key
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，該 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[]
在每個 Zonos API 請求的 Authorization 標頭中包含訪問令牌作為 Bearer 令牌。
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 令牌授予 (RFC 7523) 進行機器到機器驗證。您的服務使用您的 RSA 私鑰簽署短期有效的 JWT；Zonos 使用您註冊的公鑰驗證該 JWT 並返回一個以您的組織為範圍的 Bearer 令牌。
流程摘要：
Authorization: Bearer <token>。步驟 1——註冊您的公鑰（一次性設定）
生成 4096 位 RSA 金鑰對，並與 Zonos 共享公鑰。這在上線期間進行一次。
生成金鑰對
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pem與 Zonos 共享
public_key.pem。將private_key.pem儲存在專用密鑰管理器中（AWS Secrets Manager、HashiCorp Vault 等）——絕不要放在原始碼管理或環境變數中。Zonos 將註冊您的金鑰並返回您的組織 ID，該 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
在每個 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("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值。 將兩者都視為憑證。這個頁面有幫助嗎？