## 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](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/administrasjon-av-api/) `(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](#slik-legger-du-til-et-nytt-token) 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.

> [!CAUTION]
> Del aldri tokenet, og legg det aldri inn i et offentlig repository. Alle som har
> tokenet og Application ID, kan sende meldinger fra kontoen din. Hvis du mistenker
> at det har lekket ut, må du [regenerere](#slik-regenererer-du-et-token) eller
> [slette](#slik-sletter-du-et-token) tokenet.

## 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`.

![Delen Logg inn legitimasjon med listen over tokener](docs:api-tokens/token-list_en)

## 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

![Dialogboksen Vis token som ber om passordet](docs:api-tokens/token-show_en)

> [!NOTE]
> Et token som er vist, forblir synlig bare til siden lastes inn på nytt. Etter
> en ny innlasting er det maskert igjen, og du må skrive inn passordet for å se det på nytt.

## 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`

![Menyen Flere handlinger med Generer en ny, Deaktiver og Slett](docs:api-tokens/token-menu_en)

Portalen bekrefter med `Token har blitt regenerert`.

> [!WARNING]
> Det gamle tokenet slutter å virke umiddelbart. Alle integrasjoner som brukte det,
> begynner å få feil — sett inn det nye tokenet med en gang.

## 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.

> [!CAUTION]
> Slettingen er permanent — tokenet kan ikke gjenopprettes eller vises igjen. Hvis du
> bare vil blokkere tilgangen midlertidig, bruker du heller
> [deaktivering av tokenet](#slik-deaktiverer-og-aktiverer-du-et-token-igjen).

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](#slik-bruker-du-tokenet-i-en-signert-jwt)
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](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/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`:

```http
POST /api/1.0/simple/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
Authorization: Bearer <JWT>
```

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

| Del | Innhold |
|:--|:--|
| Header | `{"alg":"HS256","typ":"JWT"}` — API-et godtar ingen annen algoritme eller type |
| Payload | `application_id` med din [Application ID](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/administrasjon-av-api/) |
| Signatur | HMAC-SHA256 av header og payload, med API-tokenet som nøkkel |

Payloaden for applikasjon nummer 39238 ser altså slik ut:

```json
{
    "application_id": 39238
}
```

> [!NOTE]
> Når du sender en JWT, trenger du ikke lenger `application_id` eller `application_token`
> blant parameterne i forespørselen — API-et henter identiteten fra payloaden.

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:

```json
{
    "application_id": 39238,
    "application_parameters": {
        "expire": 1800000000
    }
}
```

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`.