Godkend dine backend-tjenester hos Zonos med asymmetrisk nøglekryptografi — uden delte hemmeligheder.
Zonos understøtter maskine-til-maskine-godkendelse via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Din tjeneste signerer en kortvarig JWT med din RSA-private nøgle; Zonos verificerer den ved hjælp af din registrerede offentlige nøgle og returnerer et Bearer-token med scope til din organisation.
Flow-oversigt:
Generer et RSA-nøglepar, og registrer din offentlige nøgle hos Zonos.
Ved kørsel signerer du en JWT-assertion med din private nøgle og sender den med POST til token-endpointet.
Zonos returnerer et kortvarigt adgangstoken.
Inkluder adgangstokenet som Authorization: Bearer <token> i hver API-anmodning.
Trin 1 — Registrer din offentlige nøgle (engangsopsætning)
Generer et 4096-bit RSA-nøglepar, og del den offentlige nøgle med Zonos. Dette gøres én gang under onboarding.
Del public_key.pem med Zonos. Opbevar private_key.pem i en dedikeret secrets manager (AWS Secrets Manager, HashiCorp Vault osv.) — aldrig i source control eller miljøvariabler.
Zonos registrerer din nøgle og returnerer dit Organization ID, som bliver iss-claim i alle JWT-assertions.
Trin 2 — Opbyg en JWT-assertion
Signer en JWT med RS256 ved hjælp af din private nøgle. Assertionen er gyldig til et enkelt token-udveksling — hold udløbsvinduet kort (60–300 sekunder).
Adgangstokens udløber som standard efter 5 minutter. Cache tokenet, og forny proaktivt — anmod ikke om et nyt token ved hvert API-kald. Hver fornyelse kræver en ny signeret JWT-assertion.
OAuth 2.0-godkendelse
OAuth 2.0-godkendelse
Godkend dine backend-tjenester hos Zonos med asymmetrisk nøglekryptografi — uden delte hemmeligheder.
Zonos understøtter maskine-til-maskine-godkendelse via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Din tjeneste signerer en kortvarig JWT med din RSA-private nøgle; Zonos verificerer den ved hjælp af din registrerede offentlige nøgle og returnerer et Bearer-token med scope til din organisation.
Flow-oversigt:
Authorization: Bearer <token>i hver API-anmodning.Trin 1 — Registrer din offentlige nøgle (engangsopsætning)
Generer et 4096-bit RSA-nøglepar, og del den offentlige nøgle med Zonos. Dette gøres én gang under onboarding.
Generer nøgleparret
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemDel
public_key.pemmed Zonos. Opbevarprivate_key.pemi en dedikeret secrets manager (AWS Secrets Manager, HashiCorp Vault osv.) — aldrig i source control eller miljøvariabler.Zonos registrerer din nøgle og returnerer dit Organization ID, som bliver
iss-claim i alle JWT-assertions.Trin 2 — Opbyg en JWT-assertion
Signer en JWT med
RS256ved hjælp af din private nøgle. Assertionen er gyldig til et enkelt token-udveksling — hold udløbsvinduet kort (60–300 sekunder).Påkrævede claims
iss"org_abc123")sub"checkout-service")aud"zonos-auth"expiatiatjtiJWT-headeren skal angive
"alg": "RS256"og"typ": "JWT".Kodeeksempler
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",)Trin 3 — Udveksl assertionen for et access token
Send den signerede JWT til Zonos' token-endpoint for at modtage et kortvarigt Bearer-token.
Endpoint
application/x-www-form-urlencodedaccepteres også.Anmodningsfelter
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionAnmodning og svar
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeFulde kodeeksempler
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"]Trin 4 — Kald Zonos API'er med adgangstoken
Inkluder adgangstokenet som et
Bearer-token iAuthorization-headeren i hver Zonos API-anmodning.Eksempelanmodning
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Tokenlivscyklus og caching
Adgangstokens udløber som standard efter 5 minutter. Cache tokenet, og forny proaktivt — anmod ikke om et nyt token ved hvert API-kald. Hver fornyelse kræver en ny signeret JWT-assertion.
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"]Fejlreference
Alle fejl følger OAuth 2.0 fejlresponsformatet (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typevar ikkeurn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorAlmindelige årsager til
invalid_grant:expligger i fortiden — sørg for, at dit systemur er NTP-synkroniseretauder ikke præcis"zonos-auth"issmatcher ikke dit registrerede Organization IDSikkerhedsbedste praksis
jti. En unik værdi pr. assertion muliggør replay-detektion på serversiden.access_token- ellerassertion-værdier. Behandl begge som legitimationsoplysninger.Var denne side nyttig?