> 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/client-portal/systems/system-settings.md).

# System Settings

Configure credentials and provider options for Accounting System connections.

A System Setting tells Zwapgrid which vendor application credentials and options to use when Your Customer connects an Accounting System. Settings are created in the [Client Portal](https://clients.zwapgrid.com/) and belong to one Accounting System.

Treat System Settings as a standard part of setting up a new integration whenever they are supported. For a **client-managed connection**, your organisation owns the vendor application registration and Zwapgrid uses its credentials to complete authorisation and make API requests. Some settings instead configure options for a **Zwapgrid-managed integration**, whose application credentials are managed by Zwapgrid.

Zwapgrid is moving toward System Settings as the default connection model across all Accounting Systems. Where System Settings are not yet available, the system-specific guide explains the current Zwapgrid-managed process. Existing integrations may also remain Zwapgrid-managed until a migration is agreed.

## Enablement and configuration are different

Enabling a system makes it available in the Onboarding Flow. Configuring a system selects the credentials and options used by its connections.

For systems where System Settings are available, complete all three actions before inviting Your Customer:

1. Enable the Accounting System.
2. Create and publish a System Setting.
3. Make the setting the default where supported, or provide it explicitly when creating the Consent.

## What a System Setting contains

The available fields depend on the Accounting System and can include:

* A name that helps your team identify the configuration.
* A vendor application client ID and client secret.
* OAuth scopes or feature permissions.
* A redirect URI to register with the vendor.
* Environment-specific or connection-specific options.

Some vendors control permissions in their own developer portal instead of the Zwapgrid Client Portal. Always follow the relevant [System Setup Guide](/client-portal/systems/setup-guides.md).

{% hint style="warning" %}
Never place real client secrets, API keys, access tokens, or customer data in documentation, screenshots, support tickets, or chat messages.
{% endhint %}

## Create and publish a setting

1. Sign in to the [Client Portal](https://clients.zwapgrid.com/).
2. Open **Systems** and locate the Accounting System.
3. Select **Configure**, then create a setting with a descriptive name.
4. Copy any redirect URI shown by Zwapgrid to the corresponding field in the vendor application.
5. Enter the required credentials and permissions, or select the connection options available for that system.
6. Save the setting and review the configuration while it is in Draft.
7. Publish the setting when it is ready for Consent creation and onboarding.

Use names that identify the application and purpose without including secrets, for example `Production - reporting` or `Development - invoice sync`.

## Lifecycle

| State         | Behaviour                                                                     |
| ------------- | ----------------------------------------------------------------------------- |
| **Draft**     | Editable preparation state. Publish it before selecting it for a new Consent. |
| **Published** | Available for Consent creation and customer onboarding.                       |
| **Archived**  | Retained for lifecycle management but unavailable for new connections.        |

An archived setting must remain archived for 30 days before permanent deletion. Deletion is blocked if an accepted Consent becomes linked to the setting during that period.

## Select a setting for a Consent

You can use either of these approaches:

* **Default setting:** Use the published default whenever Your Customer selects that Accounting System.
* **Consent-specific setting:** Provide a published setting ID in the `systemsSettings` object when you [create the Consent](/client-portal/consents/create-consent.md#providing-system-settings-during-consent-creation).

You can maintain multiple named settings for the same Accounting System. This is useful when separate products, environments, or permission profiles require different configurations. Each connection still uses one setting for one Accounting System.

## Select a provider environment

Where supported, a System Setting lets you select the vendor's production or test environment. Available options, default behaviour, and rules for changing environments depend on the Accounting System. Follow its [System Setup Guide](/client-portal/systems/setup-guides.md); a Development Consent alone does not guarantee a connection to a vendor's test environment.

## Rotate a client secret

When you rotate the client secret for the same vendor application, you can update the existing Published System Setting. The client ID and scopes must remain unchanged.

1. Generate a new client secret in the vendor's developer portal.
2. In the Client Portal, open the existing Published System Setting.
3. Replace the client secret without changing the client ID or scopes.
4. Save the setting and validate that the integration can still authenticate and access the required data.
5. Revoke the previous secret after validation, when the vendor supports an overlap period.

## Change application or scopes

Changing the vendor application, client ID, or scopes requires a new System Setting. Application and permission changes can affect existing authorisations and must be tested before migration.

1. Create or update the replacement vendor application and confirm its scopes or permissions.
2. Create and publish a new System Setting instead of changing or removing the active setting.
3. Ask the vendor whether existing customers must authorise the new application or scopes.
4. Validate the complete workflow with a test company.
5. Move one production connection first and confirm the result.
6. Archive the previous setting only after all affected connections have been accounted for.

## Security checklist

* Request only the permissions required by your integration.
* Use separate vendor credentials for development and production when the vendor supports it.
* Store client secrets in the System Setting rather than application logs or internal notes.
* Rotate credentials immediately if they may have been exposed.
* Test credential replacements before migrating production connections.
* Never include secrets when contacting Zwapgrid or vendor support.

## Configure a specific system

Open the [System Setup Guides](/client-portal/systems/setup-guides.md) for vendor-specific prerequisites, fields, permissions, test environments, and production considerations.

{% hint style="info" %}
Need help with a particular configuration? Contact <support@zwapgrid.com> with the Accounting System, Consent ID, UTC timestamp, and correlation or request ID. Do not include credentials or tokens.
{% endhint %}


---

# 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/client-portal/systems/system-settings.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.