API-token

Hva er et API-token

Et API-token (APPLICATION_TOKEN) er den hemmelige nøkkelen applikasjonen din bruker for å autentisere seg mot BulkGate API. Sammen med Application ID (APPLICATION_ID) utgjør det det komplette settet med tilgangsopplysninger — uten begge avviser API-et forespørselen.

Tokenet er en tilfeldig streng på 50 tegn som består av sifre og små og store bokstaver. Det lagres kryptert og utløper ikke — det er gyldig helt til du selv regenererer, deaktiverer eller sletter det.

Ett token opprettes automatisk i det øyeblikket du oppretter API-et. Du kan legge til flere når som helst — for eksempel ett per server eller per miljø, slik at du kan trekke tilbake ett av dem uten å påvirke de andre.

Hvor finner du tokenet

1. Klikk på Moduler og APIer i menyen i portalen
2. Klikk på kortet for applikasjonen din under Mine APIer og moduler
3. Bli stående på fanen Innstillinger og finn delen Logg inn legitimasjon

Der finner du Application ID og under den, under underoverskriften Application Token, listen over tokenene til applikasjonen. Et token vises aldri med en gang — du ser bare de fire første og de fire siste tegnene, resten er erstattet med stjerner.

Ikonet til venstre viser tilstanden til tokenet: grønt betyr aktivert, rødt betyr deaktivert. Et deaktivert token er i tillegg gjennomstreket.

Knappen med det overstrekede øyet til høyre for hvert token viser det; de øvrige handlingene er skjult bak ikonet med tre prikker, Flere handlinger.

Slik viser og kopierer du et token

1. Klikk på ikonet med det overstrekede øyet ved siden av tokenet du vil se
2. Dialogboksen Vis token åpnes og ber deg sjekke omgivelsene dine
3. Skriv inn passordet til kontoen din og klikk på Fortsette
4. Tokenet vises i sin helhet, og ikonet endres til Kopiere, som legger det på utklippstavlen

Slik legger du til et nytt token

1. Klikk på Legg til token nederst i delen Logg inn legitimasjon
2. Skriv inn passordet til kontoen din
3. Klikk på Legg til

Portalen bekrefter med Token er opprettet og viser det nye tokenet i sin helhet — kopier det med en gang, for etter en ny innlasting er det maskert som de andre. Det er ingen grense for hvor mange tokener én applikasjon kan ha.

Slik regenererer du et token

Regenerering overskriver det eksisterende tokenet med et nytt. Det beholder plassen sin i listen, bare verdien endres.

1. Klikk på Flere handlinger ved siden av tokenet og velg Generer en ny
2. Skriv inn passordet til kontoen din
3. Klikk på Generer en ny

Portalen bekrefter med Token har blitt regenerert.

Slik deaktiverer og aktiverer du et token igjen

Å deaktivere et token er det reversible alternativet til å slette det: tokenet blir værende i listen, men kan ikke lenger brukes til autentisering.

1. Klikk på Flere handlinger ved siden av tokenet
2. Velg Deaktiver, eller Aktiver for et token som allerede er deaktivert
3. Bekreft i dialogboksen som åpnes

Portalen bekrefter med Token har blitt deaktivert eller Token ble aktivert. Denne handlingen krever ikke passord.

Slik sletter du et token

1. Klikk på Flere handlinger ved siden av tokenet og velg Slett
2. Bekreft med Slett i dialogboksen Slett token

Portalen bekrefter med Token er fjernet. Heller ikke denne handlingen krever passord.

Alle tokenene til en applikasjon forsvinner også i det øyeblikket du sletter selve applikasjonen.

Slik sendes tokenet til API-et

Du sender Application ID og tokenet som parameterne application_id og application_token — enten i forespørselens body eller i query-strengen. Det andre alternativet er å signere en JWT med tokenet og sende den i en header.

Et ugyldig, deaktivert eller slettet token gir et svar med HTTP-kode 401 og feiltypen unknown_identity. Du får det samme svaret når selve applikasjonen er deaktivert, eller når den har konfigurert tillatte IP-adresser og forespørselen kommer fra et annet sted. De øvrige feilene er oppført på siden API-feiltyper.

Slik bruker du tokenet i en signert JWT

I stedet for å sende tokenet med hver forespørsel kan du signere en JWT med det og sende den i stedet. Tokenet blir da værende hos deg — bare signaturen som er avledet av det, sendes over nettverket.

Legg den ferdige JWT-en i headeren Authorization:

For at API-et skal godta den, må JWT-en se slik ut:

Payloaden for applikasjon nummer 39238 ser altså slik ut:

Du kan begrense levetiden til en enkelt JWT med feltet expire i application_parameters. Verdien er et Unix-tidsstempel i sekunder; når det er nådd, slutter JWT-en å virke:

Uten dette feltet er JWT-en gyldig like lenge som tokenet som signerte den. Feltet er derfor nyttig overalt der du gir JWT-en videre — du signerer den med kort levetid, og selve tokenet blir hos deg.

Signaturen kontrolleres mot alle aktiverte tokener til applikasjonen, så du kan signere JWT-en med hvilket som helst av dem. Et deaktivert eller slettet token slipper ikke gjennom — det samme som beskrevet ovenfor gjelder: et svar med HTTP-kode 401 og feiltypen unknown_identity.