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

# Spiris

Complete Spiris 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 selects the company in Spiris. Your backend sends the unused authorization code and callback URL, plus a PKCE verifier if used. **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 Spiris application and the scopes your integration needs. See the [Spiris setup guide](https://docs.zwapgrid.com/client-portal/systems/setup-guides/visma-eaccounting.md).
* A Published Spiris System Setting containing that application's ID and secret, belonging to your Zwapgrid client.
* Your exact backend callback registered for the application. Keep any guided callback you use; confirm the provider's registration limits or use a separate application.
* Confirmation of whether your registered application uses **PKCE**, an OAuth check that links the authorization request to the code exchange. If it does, follow the PKCE instructions below.

## OAuth scopes

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

```
offline_access ea:api ea:sales ea:accounting ea:purchase
```

## 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). Make sure `systemsSettings.vismaeaccounting` contains your published setting ID.
2. Start authorization at `https://identity.vismaonline.com/connect/authorize` with `response_type=code`, your `client_id`, exact `redirect_uri`, required `scope`, random expiring session/Consent-bound `state` and `prompt=select_account` for deliberate company selection. Include `acr_values=service:44643EB1-3F76-4C1C-A672-402AE8085934` to filter the selector to companies with access to the accounting product.
3. Send the [OAuth scopes above](#oauth-scopes) in the authorization request.
4. If your registered application uses PKCE, generate and retain a verifier on your backend, send its S256 challenge in the authorization request and include that original verifier when sending the code to Zwapgrid.
5. The customer signs in, deliberately selects the company and approves access. Validate callback state; retain the unused code without exchanging it.
6. Submit once within five minutes, with the exact redirect URI and matching verifier when PKCE was used. Zwapgrid exchanges the code and verifies company settings/product access before completing the connection.

See [Spiris authentication](https://developer.vismaonline.com/docs/authentication) for provider parameters and application requirements.

## 2. Send the request

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

The code and redirect URI are required, at most 2048 characters each. Use HTTPS (HTTP loopback is accepted locally), without fragments or user information. Do not send tokens or company/tenant/environment fields.

When authorization used PKCE, add `codeVerifier` inside `credentials` with the exact original verifier. It must contain 43–128 ASCII letters, digits or `-._~`. Omitted, null or empty means no PKCE verifier; whitespace-only values are invalid. Do not omit the verifier when authorization used PKCE. Other ERP sources do not accept this field.

For PKCE authorization, the complete body is:

```json
{
  "source": "vismaeaccounting",
  "credentials": {
    "authorizationCode": "<unused-authorization-code>",
    "redirectUri": "https://client.example/spiris/callback",
    "codeVerifier": "<matching-original-PKCE-verifier>"
  }
}
```

Choose the body that matches your authorization, replace the placeholders and save it 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: vismaeaccounting` and `state: completed`. [Optionally verify the connection](https://docs.zwapgrid.com/onboarding-flow/headless-onboarding/headless-onboarding.md#optional-verify-the-connection). Zwapgrid owns refresh using the selected application.

Codes are single-use. A GET 404 does not mean the code is safe to reuse. If the company check fails after code exchange, or you cannot confirm the result, authorize again with a fresh code and a new PKCE verifier if used. Do not automatically repeat the connection request.


---

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