使用非对称密钥加密对您的后端服务进行身份验证 — 无需共享密钥。
Zonos 支持通过 OAuth 2.0 JWT Bearer Token Grant (RFC 7523) 进行机器到机器的身份验证。您的服务使用 RSA 私钥对短期 JWT 进行签名；Zonos 使用您注册的公钥验证它，并返回作用于您的组织的 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
将 public_key.pem 分享给 Zonos。将 private_key.pem 存储在专用的密钥管理器中（如 AWS Secrets Manager、HashiCorp Vault 等）— 切勿存储在源代码控制或环境变量中。
public_key.pem
private_key.pem
Zonos 将注册您的密钥并返回您的 Organization 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 支持通过 OAuth 2.0 JWT Bearer Token Grant (RFC 7523) 进行机器到机器的身份验证。您的服务使用 RSA 私钥对短期 JWT 进行签名；Zonos 使用您注册的公钥验证它，并返回作用于您的组织的 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将
public_key.pem分享给 Zonos。将private_key.pem存储在专用的密钥管理器中（如 AWS Secrets Manager、HashiCorp Vault 等）— 切勿存储在源代码控制或环境变量中。Zonos 将注册您的密钥并返回您的 Organization 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与您的注册 Organization ID 不匹配安全最佳实践
jti。 每个断言的唯一值支持服务器端重放检测。access_token或assertion值。 将两者都视为凭证。这个页面有帮助吗？