Authenticating with the Fortnox API

Overview: how authentication works

Fortnox supports two OAuth 2.0 grants. Human/user connections use the authorization-code grant and customer login described in this guide. Pre-authorized service accounts use the client-credentials grant with a tenant identifier and do not run an interactive login for each token.

Both flows start in the Fortnox Developer Portal, where you register the integration and receive a Client ID and a Client Secret. They authenticate requests to the token endpoint; the resulting access token is what authorizes API resource calls.

For the human authorization-code flow, the customer — Fortnox calls them the resource owner — signs into their Fortnox account and approves the requested scopes. A service account instead has to be created and pre-authorized for the integration and tenant before client credentials can mint an access token.

A successful human authorization-code flow returns an access token and a refresh token. The client-credentials flow returns a tenant-scoped service-account access token instead. In both cases, resource calls send the access token as a Bearer token.

Step by step: the OAuth flow

1. 1

   Send the customer to the authorization URL

   The link points at apps.fortnox.se/oauth-v1/auth and carries your Client ID, the scopes the integration is requesting, your redirect URI, and a random state string you verify when the customer comes back. In practice this link opens in the customer's browser, but written as curl -G the parameters are easy to read:

   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

   The customer signs in and approves the scopes

   Fortnox lists exactly which scopes the integration is requesting. The customer signs in with their own Fortnox account and approves only what's shown — no scope is added later without a fresh approval.

3. 3

   Fortnox sends an authorization code to your redirect URI

   The code is valid for ten minutes, so the exchange for a token pair has to happen in the same request cycle. Hold onto it for later and it expires before you get to use it.

4. 4

   Your backend exchanges the code for a token pair

   A POST request to the token endpoint, authenticated with your Client ID and Client Secret as Basic auth, returns an access token and a 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

   Use the access token as a Bearer token

   Every subsequent call to a resource, for example /3/invoices, sends the access token in the Authorization header. If that call succeeds, the integration is live.

6. 6

   Refresh before the access token expires

   Same token endpoint, but with grant_type set to refresh_token. A successful refresh can hand you a new refresh token too — always keep the latest one, never the original:

   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: what permissions actually exist?

Fortnox splits the API into 24 scopes, and an approved token only reaches the scopes that were listed in the authorization link and that the customer actually approved at activation — never the whole account. Need payroll data? Request salary. Only need customer invoices? invoice is enough. The list below is pulled straight from Nordsynk's own scope configuration, not from memory.

The rule is least privilege: request only the scopes the integration actually needs for the job at hand. A scope you never requested can't leak data, and an overly broad approval is harder for the customer to trust and harder for you to justify in a security review. If the integration needs more later, the customer has to approve the new scopes explicitly — it never happens quietly in the background.

Common authentication errors

Most Fortnox authentication problems fall into three categories — and only one of them is actually a bug in your code.

Token management in practice

Frequently asked questions about Fortnox authentication