Autentique seus serviços de back-end com a Zonos usando criptografia de chave assimétrica — sem segredos compartilhados.
A Zonos oferece suporte à autenticação máquina a máquina via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Seu serviço assina um JWT de curta duração com sua chave privada RSA; a Zonos o verifica usando sua chave pública registrada e retorna um token Bearer com escopo para sua organização.
Resumo do fluxo:
Gere um par de chaves RSA e registre sua chave pública com a Zonos.
Em tempo de execução, assine uma asserção JWT com sua chave privada e envie-a por POST ao endpoint do token.
A Zonos retorna um token de acesso de curta duração.
Inclua o token de acesso como Authorization: Bearer <token> em cada solicitação de API.
Passo 1 — Registre sua chave pública (configuração única)
Gere um par de chaves RSA de 4096 bits e compartilhe a chave pública com a Zonos. Isso é feito uma vez durante o onboarding.
Compartilhe public_key.pem com a Zonos. Armazene private_key.pem em um gerenciador de segredos dedicado (AWS Secrets Manager, HashiCorp Vault etc.) — nunca no controle de versão ou em variáveis de ambiente.
A Zonos registrará sua chave e retornará seu ID de organização, que se torna a declaração iss em todas as asserções JWT.
Passo 2 — Construa uma asserção JWT
Assine um JWT com RS256 usando sua chave privada. A asserção é válida para uma única troca de token — mantenha a janela de expiração curta (60–300 segundos).
Os tokens de acesso expiram em 5 minutos por padrão. Armazene o token em cache e renove-o proativamente — não solicite um novo token a cada chamada de API. Cada renovação exige uma nova asserção JWT assinada.
Autenticação OAuth 2.0
Autenticação OAuth 2.0
Autentique seus serviços de back-end com a Zonos usando criptografia de chave assimétrica — sem segredos compartilhados.
A Zonos oferece suporte à autenticação máquina a máquina via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Seu serviço assina um JWT de curta duração com sua chave privada RSA; a Zonos o verifica usando sua chave pública registrada e retorna um token Bearer com escopo para sua organização.
Resumo do fluxo:
Authorization: Bearer <token>em cada solicitação de API.Passo 1 — Registre sua chave pública (configuração única)
Gere um par de chaves RSA de 4096 bits e compartilhe a chave pública com a Zonos. Isso é feito uma vez durante o onboarding.
Gere 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.pemCompartilhe
public_key.pemcom a Zonos. Armazeneprivate_key.pemem um gerenciador de segredos dedicado (AWS Secrets Manager, HashiCorp Vault etc.) — nunca no controle de versão ou em variáveis de ambiente.A Zonos registrará sua chave e retornará seu ID de organização, que se torna a declaração
issem todas as asserções JWT.Passo 2 — Construa uma asserção JWT
Assine um JWT com
RS256usando 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 deve 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 — Troque 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 é aceito.Campos da solicitação
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionSolicitação e resposta
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeExemplos completos de código
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 — Chame as APIs da Zonos com o token de acesso
Inclua o token de acesso como um token
Bearerno cabeçalhoAuthorizationem cada solicitação à API da Zonos.Exemplo de solicitação
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
Os tokens de acesso expiram em 5 minutos por padrão. Armazene o token em cache e renove-o proativamente — não solicite um novo token a cada chamada de API. Cada renovação exige 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 esteja sincronizado via NTPaudnão é exatamente"zonos-auth"issnão corresponde ao seu ID de organização registradoBoas práticas de segurança
jti. Um valor exclusivo por asserção permite a detecção de repetição no lado do servidor.access_tokenouassertion. Trate ambos como credenciais.Esta página foi útil?