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 - private_key.pem -pubout -out public_key.pemDel 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).
Påkrævede claims
| Claim↕ | Værdi↕ |
|---|---|
iss | Dit Zonos Organization ID (f.eks. "org_abc123") |
sub | Identificerer den kaldende tjeneste (f.eks. "checkout-service") |
aud | Skal være præcis "zonos-auth" |
exp | Unix-tidsstempel; 60–300 sekunder fra iat |
iat | Unix-tidsstempel for udstedelse |
jti | Unikt UUID pr. assertion (muliggør replay-detektion) |
JWT-headeren skal angive "alg": "RS256" og "typ": "JWT".
Kodeeksempler
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",)Trin 3 — Udveksl assertionen for et access token
Send den signerede JWT til Zonos' token-endpoint for at modtage et kortvarigt Bearer-token.
Endpoint
POST https://auth.zonos.com/oauth/token
Content-Type: application/json
application/x-www-form-urlencoded accepteres også.
Anmodningsfelter
| Felt↕ | Påkrævet↕ | Værdi↕ |
|---|---|---|
grant_type | Ja | "urn:ietf:params:oauth:grant-type:jwt-bearer" |
assertion | Ja | Din signerede JWT (kompakt serialisering) |
Anmodning og svar
{ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}| Svarfelt↕ | Beskrivelse↕ |
|---|---|
access_token | Bearer-token til alle efterfølgende API-anmodninger |
token_type | Altid "Bearer" |
expires_in | Sekunder indtil udløb (standard: 300) |
scope | Mellemrumseparerede tilladelser tildelt dette token |
Fulde kodeeksempler
import requests response = 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 i Authorization-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 signerede 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"}| HTTP-status↕ | error↕ | Årsag↕ |
|---|---|---|
400 | unsupported_grant_type | grant_type var ikke urn:ietf:params:oauth:grant-type:jwt-bearer |
400 | invalid_request | Manglende eller fejlformateret felt |
401 | invalid_grant | Ugyldig signatur, udløbet assertion, ukendt org eller uregistreret nøgle |
500 | server_error | Intern fejl — kontakt Zonos support, hvis den vedvarer |
Almindelige å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 ID- Offentlig nøgle blev roteret, men er endnu ikke opdateret hos Zonos
Sikkerhedsbedste praksis
- Beskyt din private nøgle. Opbevar den i en dedikeret secrets manager — aldrig i source control, miljøvariabler eller logs.
- Hold assertions kortvarige. 60–300 sekunder er standard; der er ingen grund til at udstede længere.
- Inkluder
jti. En unik værdi pr. assertion muliggør replay-detektion på serversiden. - Roter nøglepar periodisk. Registrer en ny offentlig nøgle hos Zonos, før du tilbagekalder den gamle, for at undgå nedetid.
- Log aldrig
access_token- ellerassertion-værdier. Behandl begge som legitimationsoplysninger.
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.