How to Manage Space Integrations

This guide shows you how to reach the Space integrations settings area and how the available integration sections are exposed in the UI.

Integrations Entry Point

Open a Space, then open this route:

/spaces/<spaceId>/settings/integrations

That route forwards you to the integration section available for the Space.

Available Sections

The integrations settings area currently supports these sections:

• OAuth 2.0 credentials
• SQL Connections

When both sections are available, the Integrations page renders two subtabs in this order:

1. OAuth 2.0
2. SQL Connections

When only one section is available, the subtab bar is hidden and the page opens that section directly.

Export and Import

Saved OAuth 2.0 credentials and SQL connections are included in Space export and import operations when you select them for export. When imported into another Space, the credentials are recreated in the target Space, and Flow nodes that used them use the imported copies.

URLs

Use these routes for direct navigation:

• /spaces/<spaceId>/settings/integrations/oauth
• /spaces/<spaceId>/settings/integrations/oauth/create
• /spaces/<spaceId>/settings/integrations/oauth/<credentialId>
• /spaces/<spaceId>/settings/integrations/sql
• /spaces/<spaceId>/settings/integrations/sql/create
• /spaces/<spaceId>/settings/integrations/sql/<connectionId>

If you open /spaces/<spaceId>/settings/integrations:

• with both sections available, you are sent to the OAuth section first
• with only OAuth 2.0 credentials available, you are sent to the OAuth section
• with only SQL Connections available, you are sent to the SQL section

OAuth 2.0 Credential Configuration

An OAuth credential is used by the Auth - OAuth Get Access Token node.

When creating an OAuth credential, you choose a grant type:

1. User Authorization (Authorization Code) — a user authenticates with the provider via browser redirect and grants consent. This is suitable for integrations that act on behalf of a named user.
2. App-Level Token (Client Credentials) — the credential exchanges a client ID and secret directly with the provider's token endpoint. No browser redirect, no user sign-in, and no callback URL is needed. This is suitable for service-to-service integrations that authenticate as the application itself.

Endpoint Configuration

Choose an endpoint source when creating or editing a credential:

1. Discover from issuer — provide an issuer endpoint. Ligantic discovers the authorisation and token endpoints. An issuer is required for both grant types.
2. Enter endpoints manually — provide the authorisation endpoint for User Authorization credentials and the token endpoint for either grant type. An issuer is optional except that User Authorization credentials using the openid scope require one.

You can switch between issuer discovery and manual endpoints when editing a credential. After switching, provide the fields required by the selected source and save the credential.

Client Authentication

Manual endpoint configuration lets you choose how the client secret is sent to the token endpoint:

• client_secret_basic (default) — sends the secret with HTTP Basic authentication.
• client_secret_post — sends the secret in the token request body.

For User Authorization credentials, the typical flow is:

• Depending on the endpoint source, you provide an issuer endpoint or the manual authorisation and token endpoints, plus the client ID and client secret (stored in secrets).
• Click Authorize to open the provider's login page in a browser.
• After granting consent, you are redirected back and the credential is authorised.

For App-Level Token credentials, the flow is simpler:

• Depending on the endpoint source, you provide an issuer endpoint or the manual token endpoint, plus the client ID, secret (stored in secrets), and desired scopes.
• Click Create. The system immediately exchanges the credentials with the provider's token endpoint.
• If the exchange succeeds, the credential is authorised and saved. If it fails (for example, invalid client, invalid scope), an error is shown and the credential is not created.

App-Level Token credentials renew their access without any user action, so they stay authorised.

Grant type is immutable after credential creation. You cannot change from User Authorization to App-Level Token or vice versa on an existing credential; you must create a new one.

When you change the endpoint source or sensitive fields (issuer endpoint, authorisation endpoint, token endpoint, client authentication method, client ID, secret, or scopes) on an existing credential, the credential is re-authorised so you are told immediately if the new configuration is valid:

• App-Level Token credentials are re-authorised automatically as part of the save. If the provider accepts the new configuration, the credential stays authorised with a fresh token. If it rejects it (for example, invalid client or scope), the credential is marked as Refresh Failed and the provider's error is shown so you can fix the configuration.
• User Authorization credentials reset to pending status and require a manual Authorize click, because re-authorisation needs a browser redirect and user consent.

SQL Connection Configuration

The SQL form currently supports these dialects:

• PostgreSQL
• SQL Server

For each dialect, the SQL settings UI supports two setup paths:

1. Use individual parameters (default)
2. Store the full connection string as a secret

Import tools are opened from the Import from Connection String button in the Use individual parameters section. For PostgreSQL, this button appears on the same row as Require SSL. The import popup only applies values to individual parameters. If a password is parsed from the connection string, it is written to the selected password secret path when you save the SQL connection, and on edit pages it is also written before Test Connection runs.

When you create a new secret from SQL connection settings, the suggested path starts with sql/.

On SQL and OAuth edit pages, secret selectors provide two actions when a secret path is selected:

• Add a new secret path (plus button)
• Edit the selected secret value (edit button)

When editing an existing secret from these forms, the secret path stays locked and only the value is updated.

The create and edit pages persist the saved SQL credential configuration for the Space. The SQL detail page also lets you remove a saved connection.

Saved SQL credentials can be tested from the SQL detail page. On the edit page, clicking Test Connection first saves the latest form changes so tests run against the current configuration. The test then runs in three stages:

1. Reach the server with a short initial connection check
2. Confirm the username and password are accepted
3. Confirm the configured database can be opened and queried

The first stage fails quickly when the server is unreachable, for example because of a blocked port, a VPN issue, or a corporate firewall.

On the create page, Test Connection shows a message asking you to save the connection first, so run the test from the edit page.

The test also checks that the server responds as the selected dialect (PostgreSQL or SQL Server), so a port that does not serve that dialect fails early.

Shared Connection Health Behaviour

Saved SQL credentials track recent connection outcomes. When connection attempts fail repeatedly, the credential status moves through Degraded and Failed, and can be temporarily Suspended.

• After enough consecutive failures, the credential becomes Suspended for a cooldown window.
• While suspended, Flow nodes using that shared credential, such as Integration - SQL Query in shared credential mode, fail fast and trigger their error path without attempting a connection.
• When the cooldown window expires, the next Flow run using that credential tries to connect again.
• A successful connection returns the credential to Succeeded.
• Updating SQL credential configuration (for example, rotating passwords or changing database host details) resets the status to Pending and allows an immediate retry.