Autentisering

Nøkkelen

Nøkkelen sendes som bearer-token på hver forespørsel. Den ser slik ut: skribb_sk_ etterfulgt av 43 tegn. Prefikset foran er der så en nøkkel på avveie kjennes igjen av både et menneske og en hemmelighetsskanner.

Nøkkelen bestemmer selv hvilken publikasjon den gjelder. Du oppgir aldri en publikasjon i forespørselen, og en nøkkel kan ikke nå en annen publikasjon enn sin egen. Har du flere publikasjoner, lager du en nøkkel per publikasjon.

Mister du en nøkkel, trekker du den tilbake under Innstillinger. Den slutter å virke med det samme, og du lager en ny. Vi viser når hver nøkkel sist ble brukt, så du ser om noe fortsatt kaller med den.

Se nøklene dine →

Tilganger

Hver rute krever én bestemt tilgang. Mangler nøkkelen den, får du 403, også når nøkkelen ellers er gyldig. Koden sier hvilken tilgang som manglet. Skrivetilgang gir ikke lesetilgang: en nøkkel som justerer lager, får ikke se bestillinger med mindre du huker av for det.

Tilgang på vegne av en skaper

Bygger du noe andre skal bruke, skal du ikke be dem lime inn en nøkkel hos deg. Da vet ingen av dere hvem som holder den, den utløper aldri, og skaperen må hake av tilganger i et skjema som hører hjemme i produktet ditt.

I stedet registrerer programmet ditt seg én gang og sender skaperen hit for å godkjenne. Tokenet kommer rett til deg, og det varer én time.

De to stegene ligger på hver sin vert. Godkjenningen skjer på skribb.no, fordi det er det ene steget som leser innloggingen til skaperen. Alt annet skjer på api.skribb.no, som den innloggingen aldri når.

1. Registrer klienten. Du får en client_id tilbake. Det følger ingen client_secret med: et program du deler ut, klarer ikke å holde på en hemmelighet, så det er PKCE som knytter innbyttet til programmet som startet det.

curl -X POST https://api.skribb.no/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Lagerstyring AS",
    "redirect_uris": ["https://lagerstyring.example/skribb/callback"],
    "client_uri": "https://lagerstyring.example"
  }'

Adressene i redirect_uris må stemme på tegnet når koden skal leveres. De kan være https, http mot 127.0.0.1 eller [::1] for et program som kjører på maskinen til brukeren, eller et eget URI-skjema på formen no.eksempel.app:/callback.

2. Send skaperen til godkjenningen på https://skribb.no/gi-tilgang, med response_type=code, client_id, redirect_uri, scope som en mellomromsdelt liste, en state du kjenner igjen, og en code_challenge med code_challenge_method=S256. Skaperen ser navnet du registrerte, hvilken publikasjon tilgangen gjelder og hva hver enkelt tilgang betyr. Sier de nei, får du det tilbake som ?error=access_denied.

3. Bytt koden i et token. Koden lander på redirect_uri, varer ti minutter og kan brukes én gang. Bruker noen den om igjen, trekker vi tilbake tokenet den alt hadde laget.

curl -X POST https://api.skribb.no/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d client_id="$CLIENT_ID" \
  -d redirect_uri=https://lagerstyring.example/skribb/callback \
  -d code_verifier="$VERIFIER"

Tokenet sendes som bearer på hver forespørsel, akkurat som en nøkkel skaperen har laget selv, og det når bare den ene publikasjonen de godkjente. Sammen med det får du et refresh_token, som er det du fornyer med.

4. Forny før tokenet går ut. Skaperen skal ikke måtte godkjenne på nytt når det har gått én time. Det ordner programmet ditt selv.

curl -X POST https://api.skribb.no/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN" \
  -d client_id="$CLIENT_ID"

Du får et nytt token og et nytt refresh_token. Det gamle slutter å virke med én gang, så lagre det nye. Brukes det samme refresh_token to ganger, trekker vi tilbake hele tilgangen, og skaperen må godkjenne på nytt. Det er strengt med vilje. Programmet ditt holder ingen hemmelighet, så det eneste vi kan gå etter, er at ingen andre har tokenet. Kommer det inn to ganger, stemmer ikke det lenger.

Fornyelsen varer i 30 dager fra sist du brukte den, og fristen settes på nytt hver gang. Et program som kaller jevnlig, trenger aldri å spørre skaperen igjen. Vil du ha et token med færre tilganger enn de godkjente, sender du scope med. Du kan be om mindre, aldri mer, og selve godkjenningen ligger like fullstendig etterpå.

5. Lever tilgangen tilbake når brukeren kobler fra hos deg. Ellers står den igjen i listen til skaperen som om noe fortsatt bruker den.

curl -X POST https://api.skribb.no/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token="$REFRESH_TOKEN" \
  -d client_id="$CLIENT_ID"

Sender du et refresh_token, ryker hele tilgangen. Sender du et access-token, ryker bare det ene. Du får 200 uansett, også for et token vi ikke kjenner igjen. Skaperen finner tilgangen igjen under Innstillinger og kan trekke den tilbake når som helst.

Alt dette står også maskinlesbart, så en klient som bare har adressen vår, finner fram selv. https://api.skribb.no/.well-known/oauth-authorization-server beskriver flyten steg for steg. Den andre, https://api.skribb.no/.well-known/oauth-protected-resource, sier hva som er beskyttet og hvem som gir tilgang til det. Et 401 herfra peker på den siste i WWW-Authenticate.

En liten klient

Kodeeksemplene i referansen bruker denne, én gang per språk, i stedet for å gjenta oppsettet på hver eneste rute. Sett nøkkelen i miljøvariabelen SKRIBB_API_KEY, lim inn klienten under, og hvert eksempel lenger inne i referansen kan limes rett etter.

Legg merke til at den leser error ut av svaret i stedet for å kaste på statuskoden alene. Det er den koden du bør bygge logikk på, og en klient som kastet den, ville gjort feilhåndteringen din vanskeligere enn nødvendig.

export SKRIBB_API_KEY="skribb_sk_…"

# Så nøkkelen og adressen ikke gjentas på hver eneste linje.
skribb() {
  local path="$1"; shift
  curl -sS -H "Authorization: Bearer $SKRIBB_API_KEY" "https://api.skribb.no/v1$path" "$@"
}

• Python: krever requests.
• C#: krever .NET 8.