Autentisering mot Fortnox API

Översikt: hur autentisering fungerar

Fortnox stöder två OAuth 2.0-grants. Mänskliga användaranslutningar använder authorization code grant och kundinloggningen som beskrivs i guiden. Förhandsgodkända servicekonton använder client credentials grant med ett tenant-id och gör ingen interaktiv inloggning för varje token.

Båda flödena börjar i Fortnox Developer Portal, där du registrerar integrationen och får ett Client ID och en Client Secret. De autentiserar anrop mot token-endpointen; den resulterande access-token är vad som auktoriserar anrop mot API-resurser.

I det mänskliga authorization code-flödet loggar kunden — Fortnox kallar dem resource owner — in och godkänner begärda scopes. Ett servicekonto måste i stället skapas och förhandsgodkännas för integrationen och tenant-kontexten innan client credentials kan skapa en access-token.

Ett lyckat mänskligt authorization code-flöde ger en access-token och en refresh-token. Client credentials-flödet ger i stället en tenant-avgränsad access-token för servicekontot. I båda fallen skickas access-token som Bearer-token vid resursanrop.

Steg för steg: OAuth-flödet

1. 1

   Skicka kunden till auktoriseringsurlen

   Länken pekar mot apps.fortnox.se/oauth-v1/auth och bär med sig ditt Client ID, vilka scopes integrationen begär, din redirect-URI och en slumpad state-sträng du verifierar när kunden kommer tillbaka. I praktiken öppnas länken i kundens webbläsare, men skrivet som curl -G blir parametrarna tydliga:

   curl -G "https://apps.fortnox.se/oauth-v1/auth" \
     --data-urlencode "client_id=YOUR_CLIENT_ID" \
     --data-urlencode "redirect_uri=https://your-app.example.com/callback" \
     --data-urlencode "scope=invoice customer bookkeeping" \
     --data-urlencode "state=RANDOM_STATE_STRING" \
     --data-urlencode "response_type=code" \
     --data-urlencode "access_type=offline"

2. 2

   Kunden loggar in och godkänner scopes

   Fortnox listar exakt vilka scopes integrationen begär. Kunden loggar in med sitt eget Fortnox-konto och godkänner endast det som visas — inget scope läggs till i efterhand utan ett nytt godkännande.

3. 3

   Fortnox skickar en auktoriseringskod till din redirect-URI

   Koden är giltig i tio minuter, så växlingen mot ett tokenpar måste ske i samma begäran-cykel. Sparar du koden för senare bruk hinner den gå ut innan du använder den.

4. 4

   Din backend växlar koden mot ett tokenpar

   Ett POST-anrop mot token-endpointen, autentiserat med Client ID och Client Secret som Basic-auktorisering, ger tillbaka en access-token och en refresh-token:

   curl -X POST "https://apps.fortnox.se/oauth-v1/token" \
     -H "Authorization: Basic $(printf '%s' 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=authorization_code" \
     --data-urlencode "code=AUTHORIZATION_CODE_FROM_REDIRECT" \
     --data-urlencode "redirect_uri=https://your-app.example.com/callback"

5. 5

   Använd access-token som Bearer-token

   Varje efterföljande anrop mot en resurs, till exempel /3/invoices, skickar access-token i Authorization-headern. Fungerar anropet är integrationen igång.

6. 6

   Förnya med refresh-token innan access-token går ut

   Samma token-endpoint, men med grant_type satt till refresh_token. En lyckad förnyelse kan ge en ny refresh-token också — spara alltid den senaste, aldrig den ursprungliga:

   curl -X POST "https://apps.fortnox.se/oauth-v1/token" \
     -H "Authorization: Basic $(printf '%s' 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=refresh_token" \
     --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"

Scopes: vilka behörigheter finns?

Fortnox delar upp API:t i 24 scopes, och en godkänd token kommer bara åt de scopes som stod i auktoriseringslänken och som kunden faktiskt godkände vid aktivering — aldrig hela kontot. Vill du läsa löner begär du salary; nöjer du dig med kundfakturor räcker invoice. Listan nedan är hämtad direkt ur Nordsynks egen scope-konfiguration, inte ur minnet.

Principen är minsta möjliga privilegium: begär bara de scopes integrationen faktiskt behöver för uppgiften. Ett scope du aldrig begärde kan inte läcka data, och ett för brett godkännande är svårare för kunden att lita på och svårare för dig att motivera i en säkerhetsgranskning. Behöver integrationen mer längre fram måste kunden godkänna de nya scopes explicit — det sker aldrig tyst i bakgrunden.

Vanliga fel vid autentisering

De flesta autentiseringsproblem mot Fortnox API landar i tre kategorier — och bara en av dem är faktiskt ett fel i din kod.

Token-hantering i praktiken

Vanliga frågor om Fortnox-autentisering