- Dokumentasjon
- Grunnlag
Autentisering
API-nøkler, rettigheter per produkt, miljøer, rotasjon uten nedetid og hva du aldri bør gjøre med en nøkkel.
Spire bruker API-nøkler som Bearer-tokens. Det er enkelt med vilje: nøkler er lette å håndtere i alle språk og miljøer, og rettigheter styres per nøkkel.
Nøkkeltyper
| Prefiks | Miljø | Brukes til |
|---|---|---|
sk_test_ | Sandkasse | Utvikling og test. Gratis. |
sk_live_ | Produksjon | Ekte data og ekte sendinger. |
pk_live_ | Produksjon, offentlig | Bare adresse-autofullfør fra nettleser, låst til dine domener. |
whsec_ | Begge | Signeringshemmelighet for webhooks. Ikke en API-nøkkel. |
Send nøkkelen i Authorization-hodet:
Authorization: Bearer sk_live_din_nokkelNøkler i spørrestrengen avvises. Nøkler i kroppen ignoreres.
Rettigheter
Hver nøkkel har rettigheter per produkt og operasjon. Lag nøkler med minst mulig tilgang:
| Rettighet | Gir |
|---|---|
oppslag:les | Alle GET under /v1/virksomheter |
faktura:les, faktura:skriv | Lese fakturaer, opprette og sende |
signering:les, signering:skriv | |
varsling:skriv | Sende meldinger (lese status inngår) |
adresse:les | |
webhooks:admin | Opprette og endre webhooks |
konto:les | Forbruk og faktura fra Spire |
En nøkkel for en nattjobb som vasker kunderegisteret trenger bare oppslag:les. En nøkkel for fakturaservicen trenger faktura:skriv og kanskje varsling:skriv. Kall utenfor rettighetene gir 403 ingen_tilgang.
Miljøer
På Vekst og oppover kan du ha flere miljøer i produksjon (for eksempel «staging» og «prod»), hvert med egne nøkler, egne webhooks og egne data. Miljøer deler ikke objekter: en faktura i staging finnes ikke i prod. Sandkassen er alltid et eget miljø.
Rotasjon uten nedetid
Nøkler kan roteres når som helst:
- Opprett en ny nøkkel med samme rettigheter i dashbordet eller via
POST /v1/nokler. - Rull ut den nye nøkkelen til tjenestene dine.
- Sett utløp på den gamle (
PATCH /v1/nokler/{id}medutloper: "2026-12-01T00:00:00Z"), eller slett den med en gang.
Begge nøklene virker i mellomtiden. Dashbordet viser når hver nøkkel sist ble brukt, så du kan se når den gamle er trygg å slette.
Begrensning til IP-adresser
Nøkler kan låses til CIDR-blokker. Kall fra andre adresser avvises med 401 uautorisert. Anbefales for produksjonsnøkler der infrastrukturen har faste utgående adresser.
Hva du aldri bør gjøre
- Ikke legg nøkler i kildekoden. Bruk miljøvariabler eller en hemmelighetstjeneste. Vi skanner offentlige repoer og deaktiverer lekkede nøkler automatisk, og du får e-post.
- Ikke bruk
sk_live_fra nettleser eller mobilapp. Brukpk_live_for autofullfør, og la backend gjøre resten. - Ikke del én nøkkel mellom tjenester. Én nøkkel per tjeneste gjør rotasjon og feilsøking mulig.
- Ikke logg
Authorization-hodet. SDK-ene stripper det fra sine egne logger; sørg for at din proxy gjør det samme.
Hvis en nøkkel lekker
Slett den i dashbordet. Alle kall med nøkkelen avvises innen 5 sekunder. Se deretter gjennom leveringsloggen og forbruket for perioden, og kontakt oss hvis du ser kall du ikke kjenner igjen. Vi kan gi deg en liste over Spire-Request-Id per nøkkel for de siste 13 månedene.
OAuth for partnere
Byråer og plattformer som handler på vegne av mange Spire-kunder bruker OAuth 2.0 med autorisasjonskode i stedet for nøkler. Hver sluttkunde godkjenner tilgangen i Spires dashbord, og dere får et token per kunde med begrensede rettigheter. Les mer på partnersiden.