Autentique os seus serviços de back-end na Zonos com criptografia de chave assimétrica — sem segredos partilhados.
A Zonos suporta autenticação entre máquinas através de OAuth 2.0 JWT Bearer Token Grant (RFC 7523). O seu serviço assina um JWT de curta duração com a sua chave privada RSA; a Zonos verifica-o com a sua chave pública registada e devolve um token Bearer com âmbito limitado à sua organização.
Resumo do fluxo:
Gere um par de chaves RSA e registe a sua chave pública na Zonos.
Em tempo de execução, assine uma asserção JWT com a sua chave privada e envie-a por POST para o endpoint de token.
A Zonos devolve um token de acesso de curta duração.
Inclua o token de acesso como Authorization: Bearer <token> em todos os pedidos à API.
Passo 1 — Registe a sua chave pública (configuração única)
Gere um par de chaves RSA de 4096 bits e partilhe a chave pública com a Zonos. Isto é feito uma única vez, durante a integração inicial.
Partilhe public_key.pem com a Zonos. Guarde private_key.pem num gestor de segredos dedicado (AWS Secrets Manager, HashiCorp Vault, etc.) — nunca no controlo de versões nem em variáveis de ambiente.
A Zonos registará a sua chave e devolverá o seu ID de organização, que passa a ser a declaração iss em todas as asserções JWT.
Passo 2 — Criar uma asserção JWT
Assine um JWT com RS256 utilizando a sua chave privada. A asserção é válida para uma única troca de token — mantenha a janela de expiração curta (60–300 segundos).
Por predefinição, os tokens de acesso expiram ao fim de 5 minutos. Guarde o token em cache e renove-o de forma proativa — não peça um novo token em cada chamada à API. Cada renovação requer uma nova asserção JWT assinada.
Autenticação OAuth 2.0
Autenticação OAuth 2.0
Autentique os seus serviços de back-end na Zonos com criptografia de chave assimétrica — sem segredos partilhados.
A Zonos suporta autenticação entre máquinas através de OAuth 2.0 JWT Bearer Token Grant (RFC 7523). O seu serviço assina um JWT de curta duração com a sua chave privada RSA; a Zonos verifica-o com a sua chave pública registada e devolve um token Bearer com âmbito limitado à sua organização.
Resumo do fluxo:
Authorization: Bearer <token>em todos os pedidos à API.Passo 1 — Registe a sua chave pública (configuração única)
Gere um par de chaves RSA de 4096 bits e partilhe a chave pública com a Zonos. Isto é feito uma única vez, durante a integração inicial.
Gerar o par de chaves
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemPartilhe
public_key.pemcom a Zonos. Guardeprivate_key.pemnum gestor de segredos dedicado (AWS Secrets Manager, HashiCorp Vault, etc.) — nunca no controlo de versões nem em variáveis de ambiente.A Zonos registará a sua chave e devolverá o seu ID de organização, que passa a ser a declaração
issem todas as asserções JWT.Passo 2 — Criar uma asserção JWT
Assine um JWT com
RS256utilizando a sua chave privada. A asserção é válida para uma única troca de token — mantenha a janela de expiração curta (60–300 segundos).Declarações obrigatórias
iss"org_abc123")sub"checkout-service")aud"zonos-auth"expiatiatjtiO cabeçalho do JWT tem de especificar
"alg": "RS256"e"typ": "JWT".Exemplos de código
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",)Passo 3 — Trocar a asserção por um token de acesso
Envie o JWT assinado para o endpoint de token da Zonos para receber um token Bearer de curta duração.
Endpoint
application/x-www-form-urlencodedtambém é aceite.Campos do pedido
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionPedido e resposta
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeExemplos de código completos
import requestsresponse = 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"]Passo 4 — Chamar as APIs da Zonos com o token de acesso
Inclua o token de acesso como token
Bearerno cabeçalhoAuthorizationem todos os pedidos à API da Zonos.Exemplo de pedido
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Ciclo de vida e cache do token
Por predefinição, os tokens de acesso expiram ao fim de 5 minutos. Guarde o token em cache e renove-o de forma proativa — não peça um novo token em cada chamada à API. Cada renovação requer uma nova asserção JWT assinada.
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"]Referência de erros
Todos os erros seguem o formato de resposta de erro do OAuth 2.0 (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typenão eraurn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorCausas comuns de
invalid_grant:expestá no passado — certifique-se de que o relógio do seu sistema está sincronizado por NTPaudnão é exatamente"zonos-auth"issnão corresponde ao seu ID de organização registadoBoas práticas de segurança
jti. Um valor único por asserção permite a deteção de repetições do lado do servidor.access_tokenouassertionem logs. Trate ambos como credenciais.Esta página foi útil?