> 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/bokio.md).

# Bokio

Complete Bokio 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 customer authorizes a company in Bokio. Your backend sends the unused authorization code and exact callback URL to Zwapgrid. **Zwapgrid exchanges the code, checks company access 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 Bokio public integration, with your backend callback registered and the resource scopes your integration needs approved. See the [Bokio setup guide](https://docs.zwapgrid.com/client-portal/systems/setup-guides/bokio.md).
* A Published Bokio System Setting belonging to your Zwapgrid client and containing that application's ID and secret.
* A company subscription that includes Company API access for public integrations: Plus or Business, or Premium with the Integrations (API) add-on. Basic does not include it. All API features are available during the 14-day Bokio trial, regardless of plan. See [Bokio price plan requirements](https://docs.bokio.se/docs/price-plan-requirements).
* The [OAuth scopes below](#oauth-scopes), approved for your application and selected in its Published System Setting.

This flow connects one company per Consent through the Company API. Agency API access, General API tokens and Bokio marketplace entry are outside this flow. Your customer chooses the company during Bokio authorization; there is no further company-selection request in Zwapgrid.

## OAuth scopes

Use the scopes selected in your Published Bokio System Setting so Zwapgrid can access your customer's accounting data. Include `invoices:read`.

## 1. Prepare the connection

1. Use the [Consent created in the shared workflow](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#1-create-a-consent). Set `systemsSettings.bokio` to your Published System Setting ID before starting authorization.
2. Start authorization at `https://api.bokio.se/v1/authorize` with `response_type=code`, your `client_id`, the exact registered `redirect_uri`, approved resource `scope` values including `invoices:read`, and a random, expiring `state` bound to the customer's session and Consent. Separate scope values with spaces.
3. Your customer signs in, selects the intended company and approves access.
4. At your backend callback, validate `state` against the stored value and consume it once. Retain the unused code securely without exchanging it.
5. Send the connection request once within five minutes. Zwapgrid exchanges the code using the selected application and exact redirect URI, then verifies access to the company returned by Bokio before completing the connection.

Keep any callback used by guided onboarding registered. Confirm Bokio's callback registration limits or use a separate application for headless onboarding. This connection request does not accept a PKCE verifier. Confirm your application's requirements with Bokio before using this flow if its registration requires PKCE.

Use the scopes from your Published System Setting in the authorization parameters:

```
response_type=code
client_id=<your-Bokio-application-ID>
redirect_uri=https://client.example/bokio/callback
scope=<space-separated-scopes-from-your-Published-System-Setting>
state=<random-session-and-Consent-bound-value>
```

URL-encode these parameters when building the authorization URL. See [Bokio OAuth](https://docs.bokio.se/reference/authentication-for-public-integrations-oauth) and [resource scopes](https://docs.bokio.se/reference/scopes) for provider requirements. Your Zwapgrid API-key environment does not select a Bokio test company or application; choose those in Bokio.

## 2. Send the request

Save this body as a protected `connection.json` on your backend:

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

Both fields are required, nonblank and limited to 2048 characters each. Use the exact redirect URI from authorization: HTTPS, without fragments or user information. For local development, register an HTTPS callback; see [Bokio callback requirements](https://docs.bokio.se/docs/developer-portal). Send only these fields; do not supply tokens, a company or tenant ID, an application secret or `codeVerifier`.

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
```

Your application secret stays in System Settings. The selected setting must match the Bokio application used for authorization.

## 3. Check the result

Expect HTTP **201** with:

```json
{
  "id": "<connection-UUID>",
  "source": "bokio",
  "state": "completed"
}
```

The connection is complete and the Consent is accepted. Zwapgrid uses the company identity returned by Bokio and the selected application for subsequent refresh. You can optionally [verify the connection and read accounting data](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#optional-verify-the-connection).

OAuth authorization and code exchange can succeed even when the company subscription lacks API access. If company verification fails, check `invoices:read`, the authorized company and its subscription before starting fresh authorization. The connection is completed only after company access is verified.

Codes are single-use. If the POST response is lost or uncertain, [read the authoritative connection with GET](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#if-the-result-is-uncertain). A GET 404 does not prove the code is unused. Do not automatically repeat POST; authorize again with a fresh code if you cannot confirm the result or if company validation failed after exchange.

Bokio rotates refresh tokens when used and expires unused refresh tokens after 30 days. Let Zwapgrid manage refresh after connection creation. If refresh can no longer succeed, your customer must authorize again through a new onboarding attempt; a connection request cannot replace an existing connection.


---

# 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/bokio.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.
