# Twinfield — Accounting API: configuration

> Canonical URL: https://developers.apideck.com/apis/accounting/twinfield/configuration

# How to create OAuth credentials for Twinfield

This guide walks you through taking out your Twinfield API subscription, registering your own
Twinfield OAuth client, telling Wolters Kluwer that your integration runs through Apideck, and adding
the Client ID and Secret to the Apideck Dashboard so your integration can run in production.

Things to know before you start:

- **A free Wolters Kluwer Account is your login for everything on the Twinfield side.** Create it as
  a non-personal, shared account that represents your application, not an individual employee's
  account, and not one belonging to a customer whose administration you will connect to. One
  Wolters Kluwer Account and one Client ID cover both your test and production use.
- **Every Twinfield Client ID needs its own Twinfield API subscription.** You register your own
  Client ID and take out your own subscription, a monthly fee paid to Wolters Kluwer; the
  subscription holder is the Client ID owner. Developer Portal access and API support come with the
  subscription. Before that point you can read Twinfield's
  [public API documentation](https://developers.twinfield.com/documentation), plan your mappings and
  error handling, build your own UI, and register the Wolters Kluwer Account itself.
- **Because your integration runs through Apideck, you can skip Wolters Kluwer's full
  certification.** When Wolters Kluwer contacts you about certification after you create your Client
  ID, tell them the integration runs through Apideck and they proceed without the full
  certification. Section 5 covers this step.

## 1. Take out the Twinfield API subscription

1. **Get in touch.** Submit the contact form on Wolters Kluwer's
   [Partner worden van Twinfield Boekhouden?](https://www.wolterskluwer.com/nl-nl/solutions/twinfield-accounting/functies/koppelingen/partner-worden)
   page (Dutch-language, "Stap 1: Aanmelden"). Mention there that your integration runs through
   Apideck. A Partner Sales Manager follows up with you.
2. **Take out the subscription.** The subscription gives you access to the
   [Twinfield developer portal](https://developers.twinfield.com) and to API support. You can request
   a Twinfield test environment through the Developer Portal or the same contact form.

The subscription carries a monthly fee per Client ID and Wolters Kluwer does not publish a figure,
so confirm the price with the Partner Sales Manager, and ask them for an expected timeline so you
can plan the rest of the build around it. Keep the subscription running for as long as the
integration is live: Wolters Kluwer's API terms require a continuous subscription, and letting it
lapse can lead to suspension of API access.

## 2. Register your OAuth client

1. Go to the [Twinfield developer portal](https://developers.twinfield.com) and sign in with your
   Wolters Kluwer Account.
2. Open **Your connections** and click **New** to register an OpenID Connect / OAuth 2.0 client for
   your application. Fill the registration form
   in as follows:

   | Field | What to enter |
   |-------|---------------|
   | **Client ID** | The identifier for your client. This is the value you paste into the Apideck Dashboard in section 6. |
   | **Product name** | Your application's name: end users see it when they are asked to grant permission. |
   | **Authorization flow** | Select **authorization code**. This is the flow the connector uses. |
   | **Access token type** | Keep the default, **Reference**. |
   | **Ignore single sign on** | **Check this box.** Twinfield's registration documentation says to enable it so that creating an OAuth 2.0 connection does not fail with an error requiring the user to log in with Single Sign On (SSO). |
   | **Redirect url** | `https://unify.apideck.com/vault/callback`: see section 3. |

   Leave anything else at its default; Twinfield documents **Post logout redirect url** as
   unavailable.
3. Generate a **Client Secret** with the *Generate new* link and store it somewhere safe as soon as
   it is shown.

Twinfield's registration guidance lists `Reference` as the default access token type, with `Jwt` as
an alternative; keep `Reference`.

Twinfield's own references for this step are
[Setting up OAuth 2.0: Register a client ID](https://wktaaeu.my.site.com/nlcommunity/articles/en_US/Knowledge/Setting-up-OAuth-2-0-Register-a-client-ID)
and the
[OpenID Connect authentication documentation](https://developers.twinfield.com/documentation/api/authentication/openid-connect-auth).

## 3. Set the redirect URL

Enter this value in the **Redirect url** field on your Twinfield client:

```
https://unify.apideck.com/vault/callback
```

This is the only redirect URL Apideck uses. Do not register a localhost or vendor-specific URL: the
authorization will fail if the value Twinfield has on file does not match exactly, including the
presence or absence of a trailing slash.

## 4. Scopes: nothing to configure

**You do not need to enable scopes anywhere.** Twinfield's client registration form has no scope
selection; scopes are requested per authorization request, and the Apideck connector already
requests all five that a Twinfield integration needs:

| Scope | Why it is needed |
|-------|------------------|
| `openid` | Required alongside `twf.user` for OpenID Connect authentication |
| `twf.user` | User claims (id, organisation user code, organisation id) |
| `twf.organisation` | Organisation claims, which the connector needs to work with the customer's organisation |
| `twf.organisationUser` | Mandatory in order to log in |
| `offline_access` | Required to receive a refresh token: without it, connections stop working after the access token expires |

`twf.organisation` is not optional in practice: the connector relies on the organisation claims,
so keep all five scopes in place.

## 5. Tell Wolters Kluwer your integration runs through Apideck

Every Twinfield Client ID needs certification by default. For an integration that runs through
Apideck, Wolters Kluwer does not require the full certification from you:

1. **After you create your Client ID, Wolters Kluwer contacts you to start certification.**
2. **Reply that your integration runs through Apideck.** Wolters Kluwer then proceeds without the
   full certification.

**If you prefer to certify directly with Wolters Kluwer,** the full certification process applies:
onboarding (contracts and a personal test account), an intake by Wolters Kluwer's Professional
Services, an evaluation against mandatory requirements, go-live support, and re-certification every
two years. Twinfield's own write-up is the article
[What is covered during certification](https://wktaaeu.my.site.com/nlcommunity/articles/en_US/Knowledge/Wat-komt-er-aan-bod-tijdens-de-certificering).

Under Twinfield's
[fair use policy](https://developers.twinfield.com/documentation/getting-started/fair-use-policy),
new Client IDs that are not yet certified get 5% of the per-Client ID rate limits.

## 6. Add the credentials in Apideck

1. Open the [Twinfield connector configuration](https://platform.apideck.com/configuration/accounting/twinfield)
   in the **Apideck Dashboard**.
2. Select **Use your own client credentials**.
3. Enter:
   - **Client ID** → the Client ID from your Twinfield developer portal client
   - **Client Secret** → the matching secret
4. Save the settings.

Apideck also ships managed credentials for Twinfield. These are for development and testing only.
Use your own Client ID for production: your Twinfield API subscription and rate limits are tied to
the Client ID you registered.

## 7. Track the per-customer values your integration needs

Twinfield connections carry a few values that are specific to each customer's administration, not to
your OAuth app. The end customer sets them in the connection's **Settings** in Vault after
authorizing, picking the office code from the list of administrations their Twinfield user can
access. Collecting them as part of your customer onboarding means a connection can be completed
without a round-trip.

| Setting | What it is | Default |
|---------|-----------|---------|
| **Office code** | The Twinfield office (administration) code the connection operates against, e.g. `1000`. Twinfield references companies by code, not by numeric ID, and this code is sent on every authenticated request. Required. | none: ask the customer |
| **Accounts payable control account** | The ledger account code Twinfield uses for amounts owed to suppliers. Required by Twinfield on every bill. | `1600` |
| **Accounts receivable control account** | The ledger account code Twinfield uses for amounts owed by customers. Required by Twinfield when recording a customer payment. | `1300` |
| **Bank feed statement currency** | The ISO 4217 currency code Twinfield records bank feed statements in. Optional. | `EUR` |

The two control accounts only need to be set when a customer's chart of accounts differs from
Twinfield's standard one. Leave them blank and the defaults above are used. Twinfield exposes no API
to look these codes up, so if a customer is on a customized chart of accounts, the correct values
have to come from the customer or their accountant.

One connection targets one office code. A customer whose organisation spans several administrations
needs one connection per office. There is no server, region or environment to choose for a
Twinfield connection.

## FAQ and troubleshooting

**The authorization fails or returns a redirect mismatch.**
Check that `https://unify.apideck.com/vault/callback` is registered on the Twinfield client exactly,
with no trailing slash, and that you configured the same Client ID in the Apideck Dashboard that you
registered the redirect URL on.

**Authorization fails with an error saying the user must log in with Single Sign On.**
Check the **Ignore single sign on** box on your Twinfield client registration and have the customer
authorize again.

**Connections work at first, then stop refreshing.**
Twinfield invalidates a refresh token immediately, with no advance warning, when the underlying
Twinfield organisation user is deleted, disabled, or locked, when that user's password expires, or
when the organisation itself is deactivated. The first sign is an `invalid_request` or
`invalid_grant` error on the next refresh. The fix is on the customer's side: restore or replace the
Twinfield organisation user, then reconnect. To avoid this, ask customers to authorize with a
service account rather than an individual's login.

**We are hitting HTTP 429 responses.**
Check first whether your Client ID is still in Twinfield's "new, not yet certified" state: such
Client IDs get 5% of the normal per-Client ID budget. If you are unsure of your Client ID's status,
ask Wolters Kluwer in an API support case (see "Where do I get help?" below). Twinfield returns `X-RateLimit-*` headers on
every call and a `Retry-After` header on rate-limit rejections, so you can see the remaining budget
directly in the response. Twinfield states that it does not grant limits above the published values.

**Bills or payments post to the wrong ledger account.**
Check the accounts payable / accounts receivable control account settings on that connection against
the customer's chart of accounts. The defaults (`1600` and `1300`) are correct only for Twinfield's
standard chart of accounts.

**Where do I get help?**
For questions about your subscription, certification, or the API itself, open an API support case
with Wolters Kluwer: in the [Twinfield developer portal](https://developers.twinfield.com), go to
**Support & Community** to reach the support portal, sign in with your Wolters Kluwer Account, then
choose **Cases** > **Create case**, with Level 1 **Twinfield Accounting** and product **API Support
Twinfield Boekhouden**. Wolters Kluwer answers API questions only for parties with an API
subscription. Wolters Kluwer's article
[How do I create a case about API integrations](https://wktaaeu.my.site.com/nlcommunity/articles/nl_NL/Knowledge/Hoe-maak-ik-een-case-aan-inzake-API-koppelingen)
(Dutch) describes the same steps. For pricing, contact your Wolters Kluwer Partner Sales Manager.

To hear about Twinfield outages, subscribe to the
[Twinfield status page](https://status.twinfield.com/), as Wolters Kluwer recommends.

For questions about the connector or the Apideck Dashboard, contact
[Apideck Support](https://help.apideck.com/en/articles/7774658).


[API reference](https://developers.apideck.com/apis/accounting/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/accounting/coverage)