Autentisering

Nøkkelen

Nøkkelen sendes som bearer-token på hver forespørsel. Den ser slik ut: skribb_sk_ etterfulgt av 43 tegn.

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. Innstillinger viser når hver nøkkel sist ble brukt.

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.

Tilgang på vegne av en skaper

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

1. Registrer klienten. Du får en client_id tilbake. Det følger ingen client_secret med. PKCE er påkrevd.

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. Adresser på skribb.no og skjemaer som begynner med no.skribb, er forbeholdt skribbs egne apper.

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.

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.

Fornyelsen varer i 30 dager fra sist du brukte den, og fristen settes på nytt hver gang. 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.

Maskinlesbart: https://api.skribb.no/.well-known/oauth-authorization-server beskriver flyten steg for steg, og 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. Sett nøkkelen i miljøvariabelen SKRIBB_API_KEY og lim inn klienten under.

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.