> For the complete documentation index, see [llms.txt](https://docs.zwapgrid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/fortnox.md).

# Fortnox

Complete Fortnox onboarding from your client backend.

**Preview** · [What this means for your integration](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#preview)

Your backend sends an unused Fortnox authorization code and your registered callback URL. **Zwapgrid exchanges the code and manages token refresh.**

First, complete the [shared prerequisites and example setup](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#before-you-start).

## What you need

* Your own Fortnox application, with the permissions your integration needs. See the [Fortnox setup guide](https://docs.zwapgrid.com/client-portal/systems/setup-guides/fortnox.md).
* A Published Fortnox System Setting containing that application's client ID and secret, belonging to your Zwapgrid client.
* Your backend callback URL registered on the Fortnox application. Use this exact URL when starting authorization and submitting the code.

The Zwapgrid callback in the setup guide is for guided onboarding. Keep it if you also use that flow; confirm Fortnox's callback options or register a separate application for headless use. Headless onboarding requires your own application credentials.

## OAuth scopes

Zwapgrid needs these scopes to access your customer's accounting data:

```
archive article payment settings bookkeeping invoice inbox companyinformation connectfile costcenter customer supplier supplierinvoice profile project currency
```

## 1. Prepare the connection

{% hint style="info" %}
PKCE is not currently supported for Fortnox headless onboarding. Support is planned. For now, start authorization without a PKCE challenge and do not send `codeVerifier` in the connection request.
{% endhint %}

1. Use the [Consent created in the shared workflow](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#1-create-a-consent). Make sure `systemsSettings.fortnox` contains your published setting ID.
2. Start Fortnox authorization at `https://apps.fortnox.se/oauth-v1/auth` with `response_type=code`, `access_type=offline`, your application's `client_id`, registered `redirect_uri`, required `scope` and random, expiring `state` bound to the session and Consent. Offline access lets Zwapgrid refresh tokens when your customer is not signed in.
3. The customer signs in and authorizes the intended company. Validate `state` at your callback and retain the unused code briefly on your backend. Do not exchange it yourself.
4. Submit the code and exact redirect URI once. Zwapgrid exchanges the code using the selected application and completes the connection; no additional Zwapgrid company-selection call is needed.

## 2. Send the request

```json
{
  "source": "fortnox",
  "credentials": {
    "authorizationCode": "<unused-authorization-code>",
    "redirectUri": "https://client.example/fortnox/callback"
  }
}
```

Both fields are required and limited to 2048 characters each. Use an absolute HTTPS redirect URI without a fragment or user information; HTTP loopback is accepted for local development. Do not include token, tenant, company or PKCE fields.

Replace the placeholders and save this body as a protected `connection.json` on your backend. Set the [example variables](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#set-up-the-examples), including a new UUID in `CORRELATION_ID`, then send the request once:

```sh
curl --request POST \
  "$CONSENTS_API_BASE_URL/api/v1/consents/$CONSENT_ID/connection" \
  --header "x-api-key: $ZWAPGRID_API_KEY" \
  --header "x-correlation-id: $CORRELATION_ID" \
  --header 'Content-Type: application/json' \
  --data-binary @connection.json
```

## 3. Check the result

Expect HTTP 201 with `source: fortnox` and `state: completed`. [Optionally verify the connection](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#optional-verify-the-connection). Zwapgrid owns token refresh after completion.

Codes are single-use: submit promptly and never automatically retry. After an uncertain outcome, use GET. A GET 404 does not mean the code is safe to reuse; if you cannot confirm the result, authorize again to get a fresh code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/fortnox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
