Trinn 1 — Registrer den offentlige nøkkelen din (engangsoppsett)
Generer et 4096-bits RSA-nøkkelpar og del den offentlige nøkkelen med Zonos. Dette gjøres en gang under onboarding.
Generer nøkkelparet
# 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. Lagre private_key.pem i en dedikert hemmelighetsbehandler (AWS Secrets Manager, HashiCorp Vault, osv.) — aldri i versjonskontroll eller miljøvariabler.
Zonos vil registrere nøkkelen din og returnere organisasjons-ID-en din, som blir iss-kravet i alle JWT-påstander.
Trinn 2 — Bygg en JWT-påstand
Signer en JWT med RS256 ved hjelp av den private nøkkelen din. Påstanden er gyldig for en enkelt tokenbytte — hold utløpsvinduet kort (60–300 sekunder).
Påkrevde krav
| Krav↕ | Verdi↕ |
|---|---|
iss | Din Zonos-organisasjons-ID (f.eks. "org_abc123") |
sub | Identifiserer den kallende tjenesten (f.eks. "checkout-service") |
aud | Må være nøyaktig "zonos-auth" |
exp | Unix-tidsstempel; 60–300 sekunder fra iat |
iat | Unix-tidsstempel for utgivelse |
jti | Unik UUID per påstand (gjør det mulig å oppdage gjentaking) |
JWT-hodet må spesifisere "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",)Trinn 3 — Bytt påstanden mot et tilgangstoken
Send den signerte JWT-en til Zonos-tokenendepunktet for å motta en kortvarig Bearer-token.
Endepunkt
POST https://auth.zonos.com/oauth/token
Content-Type: application/json
application/x-www-form-urlencoded er også godtatt.
Forespørselsfelt
| Felt↕ | Påkrevd↕ | Verdi↕ |
|---|---|---|
grant_type | Ja | "urn:ietf:params:oauth:grant-type:jwt-bearer" |
assertion | Ja | Din signerte JWT (kompakt serialisering) |
Forespørsel og respons
{ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}| Responsefelt↕ | Beskrivelse↕ |
|---|---|
access_token | Bearer-token for alle påfølgende API-forespørsler |
token_type | Alltid "Bearer" |
expires_in | Sekunder til utløp (standard: 300) |
scope | Mellomromsseparerte tillatelser gitt til dette tokenet |
Fullstendige 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"]Trinn 4 — Ring Zonos API-er med tilgangstokenen
Inkluder tilgangstokenen som en Bearer-token i Authorization-hodet på hver Zonos API-forespørsel.
Eksempelforespørsel
curl -X POST https://api.zonos.com/graphql \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "query": "{ ... }" }'Tokenlevetid og caching
Tilgangstokener utløper etter 5 minutter som standard. Cache tokenen og oppfrisk proaktivt — ikke be om et nytt token på hver API-anrop. Hver oppfrisking krever en nysignert JWT-påstand.
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"]Feilreferanse
Alle feil følger OAuth 2.0-feilresponsformatet (RFC 6749 §5.2):
{ "error": "invalid_grant", "error_description": "JWT assertion has expired"}| HTTP-status↕ | error↕ | Årsak↕ |
|---|---|---|
400 | unsupported_grant_type | grant_type var ikke urn:ietf:params:oauth:grant-type:jwt-bearer |
400 | invalid_request | Manglende eller dårlig utformet felt |
401 | invalid_grant | Ugyldig signatur, utløpt påstand, ukjent org, eller uregistrert nøkkel |
500 | server_error | Intern feil — kontakt Zonos-støtte hvis vedvarende |
Vanlige årsaker til invalid_grant:
exper i fortiden — sørg for at systemklokken din er NTP-synkronisertauder ikke nøyaktig"zonos-auth"isssamsvarer ikke med din registrerte organisasjons-ID- Offentlig nøkkel ble rotert men ikke oppdatert med Zonos ennå
Beste praksis for sikkerhet
- Beskytt den private nøkkelen din. Lagre den i en dedikert hemmelighetsbehandler — aldri i versjonskontroll, miljøvariabler eller logger.
- Hold påstander kortvarige. 60–300 sekunder er standard; det er ingen grunn til å utstede lengre.
- Inkluder
jti. En unik verdi per påstand gjør det mulig å oppdage gjentaking på serversiden. - Roter nøkkelpar med jevne mellomrom. Registrer en ny offentlig nøkkel med Zonos før du tilbakekaller den gamle for å unngå nedetid.
- Logg aldri
access_tokenellerassertion-verdier. Behandle begge som legitimasjon.
OAuth 2.0-godkjenning
Autentiser dine bakendtjenester med Zonos ved hjelp av asymmetrisk nøkkelkryptografi — ingen delte hemmeligheter.
Zonos støtter maskin-til-maskin-autentisering via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Tjenesten din signerer en kortvarig JWT med din private RSA-nøkkel; Zonos bekrefter den ved hjelp av din registrerte offentlige nøkkel og returnerer en Bearer-token som er begrenset til organisasjonen din.
Flytsammendrag:
Authorization: Bearer <token>på hver API-forespørsel.