# Set up a connector

> Install a connector for your organisation, fill in its configuration, register an OAuth app or store an API key, and decide who may use it. With every screen, the provider guides, the network allowlist and the fix for each connection error.

Every connector is set up the same way, whatever it connects to: you install it for the organisation, fill in what the connector needs to know, prepare the sign-in at the provider, and decide who may use it. After that, each person connects their own account with one click, or works with a shared account you connected for everyone.

This guide follows Jana Brandt, admin at Brandt & Söhne, through two typical cases. **Outlook Mail** signs in with OAuth, so Jana registers an app in Microsoft Entra once, and every employee then signs in with their own Microsoft account. **Paperboi**, the company's archive, runs on a server in the office network and uses API keys, so Jana enters the API address, releases the server in the network allowlist and stores one shared key. Most other connectors are a variation of one of these two.

## Before you start

- You need the right `ai.plugin.admin`. Administrators have it.
- Look up how the connector signs in. The [catalog](/plugins/catalog/) lists it per connector, and the connector page shows it in its <Ui>Setup</Ui> section.
- **For OAuth connectors:** you need admin access to the provider's developer console (Microsoft Entra admin center, Google Cloud Console, Atlassian developer console and so on) to register an app.
- **For API key connectors:** decide whether each person brings their own key or one shared key covers everyone.
- **For systems in your own network:** the system must be reachable from the nexxus server. You release its address under <Ui>Network allowlist</Ui>, see [below](#reach-systems-in-your-own-network).

## Install the connector

<Steps>

1. Open <MenuPath to="AI > Set up AI > Connectors" />.

   The catalog shows <Ui>Installed</Ui> connectors first, then <Ui>Popular</Ui> ones (by number of people connected in your tenant), then every category. As an admin you see the whole catalog. Everyone else only sees what is installed.

2. Find the connector with <Ui>Search connectors</Ui>, or narrow the list with the tabs <Ui>All</Ui>, <Ui>Integrations</Ui>, <Ui>Skills</Ui>, <Ui>Tools</Ui>.

3. Click **+** (<Ui>Install</Ui>) on the connector's card.

   If the connector needs a value before it can work, for example Paperboi's API address, nexxus opens the connector page at <Ui>Configuration</Ui> and puts the cursor into the first empty required field. Otherwise you see <Ui>{'{name} is installed.'}</Ui>

   <Screenshot src={shot_plg_catalog_install} url="/plugins" alt={"The section Files and storage with the install button on the Paperboi card"} caption={"\"+\" installs the connector, or opens its configuration first if it needs a value."} />

4. Click the connector's name to open its page.

</Steps>

You can also open a connector first and click <Ui>Install</Ui> at the top of its page. The page starts with the description and one sentence on where the data goes, for Paperboi for example that requests go with the person's key straight to the configured Paperboi instance. Below come the sections that apply to this connector:

| Section | Who sees it | What it is for |
|---|---|---|
| <Ui>Setup</Ui> | Everyone, admins in more detail | What to set up at the provider and what each person needs before connecting |
| <Ui>My connection</Ui> | Everyone, for connectors with a personal sign-in | Connect, reconnect, add permissions, disconnect |
| <Ui>Connection for everyone</Ui> | Admins, for connectors with a shared sign-in | Connect one account for the whole organisation |
| <Ui>Permissions</Ui> | Everyone, for connectors with permission groups | Which groups the organisation allows and the person grants |
| <Ui>Requires</Ui> | Skills | The connectors this skill switches on with it |
| <Ui>Actions</Ui> | Everyone, checkboxes for admins | Every action, reading or writing, allowed or not |
| <Ui>Triggers</Ui> | Connectors with triggers | Start one of your AI schedules when something new arrives |
| <Ui>Installation</Ui> | Admins | On or off, preselected or not, limited to roles or business units |
| <Ui>Configuration</Ui> | Admins | Values for everyone: API address, OAuth app, regional server |
| <Ui>Recent calls</Ui> | Admins | Who called which action when, without content |

<Screenshot src={shot_plg_detail_hero} url="/plugins/paperboi" alt={"The top of the Paperboi connector page with its chips and description"} caption={"The connector page starts with what the connector is and how much it is used."} />

## Fill in the configuration

<Ui>Configuration</Ui> holds the values that apply to the whole organisation: the address of a self-hosted system, the region of the provider, or your own OAuth app. The labels of these fields come from the connector itself and are in German, for example <Ui>API-Adresse</Ui> (API address) for Paperboi.

| Field type | Shown as | Notes |
|---|---|---|
| Address (URL) | Text field | Must start with `http://` or `https://`, otherwise <Ui>Please enter an address starting with http:// or https://.</Ui> |
| Number | Number field | Whole numbers where the connector asks for one, such as a port |
| Yes or no | Switch <Ui>On</Ui> / <Ui>Off</Ui> | For example Paperboi's <Ui>In Dateien anzeigen</Ui> (show in Files) |
| Choice | Drop-down | For example the region of DeepL, Intercom, Make, Pylon or Wrike |
| Secret | Password field, never filled in | After saving it shows <Ui>Stored. Leave empty to keep it.</Ui> |
| Text | Text field or text area | Anything else |

Required fields are marked <Ui>Required</Ui>. Click <Ui>Save</Ui> (or <Ui>Install</Ui> if the connector is not installed yet). nexxus encrypts the configuration as a whole and never shows a secret again.

OAuth connectors always offer <Ui>Client-ID</Ui> and <Ui>Client-Secret</Ui> here. Connectors that sign in at Microsoft also have <Ui>Entra-Mandant (Domain oder ID)</Ui> (Entra tenant, domain or ID). An empty field takes the connector's default, which is why many connectors install without opening the form at all.

<Screenshot src={shot_plg_detail_install_config} url="/plugins/paperboi#konfiguration" alt={"Installation and configuration of Paperboi before installing"} caption={"Installation decides who gets the connector, Configuration holds the values for everyone."} />

## Decide who gets it

### Installation

<Ui>Installation</Ui> decides, for this tenant, whether the connector is on, whether it is preselected in new conversations and who may use it.

- <Ui>Connector</Ui>: <Ui>Switched on</Ui> or <Ui>Switched off</Ui>. Switched off, it disappears from everyone's selection and the settings stay.
- <Ui>In new conversations</Ui>: the connector's own default, shown as <Ui>Connector default (preselected)</Ui> or <Ui>Connector default (not preselected)</Ui>, or your choice <Ui>Preselected</Ui> or <Ui>Not preselected</Ui>.
- <Ui>Only for roles</Ui>: empty means everyone allowed to use connectors.
- <Ui>Only for business units</Ui>: empty means all business units. A unit includes the units below it.

People who are not covered do not see the connector anywhere: not in the catalog, not in the chat.

### Actions

<Ui>Actions</Ui> lists every action with a <Ui>Read</Ui> or <Ui>Write</Ui> chip. Two checkboxes per action:

- <Ui>Allowed</Ui>: untick an action and the AI Assistant no longer gets it, for anyone in the tenant. Brandt & Söhne unticks <Ui>Archive inbox document</Ui> in Paperboi until the archive team has agreed on document types.
- <Ui>Always confirm</Ui>: make an action ask before every call, even a reading one. Where the connector already requires a confirmation, the checkbox is locked: <Ui>This action always asks; that cannot be switched off.</Ui>

### Permissions

For connectors with permission groups, <Ui>Permissions</Ui> shows each group with what it unlocks. The checkbox <Ui>Allowed</Ui> decides whether the organisation offers the group at all. Groups switched off are not requested from the provider and not offered in the chat. Required groups are locked: <Ui>The connector does not work without this permission.</Ui>

<Ui>Check connection</Ui> signs you in once with everything allowed and shows what the provider actually grants, group by group: <Ui>Granted</Ui>, <Ui>Not granted</Ui> or <Ui>Switched off</Ui>.

<Screenshot src={shot_plg_detail_permissions} url="/plugins/outlook-mail" alt={"The permission groups of Outlook Mail with the Allowed checkboxes"} caption={"Each group unlocks a set of actions. Groups switched off are never requested."} />

## Connect with an API key

Connectors with an API key or a login need no app at the provider. Each person creates their own key there, or you store one key for everyone.

<Steps>

1. On the connector page, choose who the key belongs to.

   - Your own: under <Ui>My connection</Ui>, click <Ui>Connect</Ui>.
   - Everyone's: under <Ui>Connection for everyone</Ui>, click <Ui>Connect for everyone</Ui>. This is only offered for connectors that allow a shared connection.

2. Enter the fields the connector asks for in the dialog <Ui>{'Connect to {name}'}</Ui> or <Ui>{'Connect {name} for everyone'}</Ui>. For Paperboi this is one field, <Ui>Paperboi-API-Schlüssel</Ui> (Paperboi API key): the secret key of a Paperboi API key with the scope "api".

   <Screenshot src={shot_plg_dlg_credentials} url="/plugins/paperboi" alt={"The dialog to connect Paperboi with an API key"} caption={"Keys are stored encrypted and used only for your own calls."} />

3. Click <Ui>Connect</Ui>. You see <Ui>{'{name} is connected.'}</Ui>

</Steps>

The values are stored encrypted. A personal key is used only for your own calls. A shared key is used by everyone who has not connected their own. If a connector allows both, a person's own key always wins.

:::caution[A shared key shares its view]
With a connection for everyone, every person with access to the connector sees what that key sees at the provider. For an archive or a CRM, create a dedicated key with just the rights the organisation should have, or let each person connect their own.
:::

## Connect with OAuth

OAuth means each person signs in at the provider with their own account, and nexxus receives a token for that account. For this the provider needs to know nexxus: you register an **app** there once. The app has a client ID and a client secret, lists the **redirect URI** the provider may send people back to, and allows the **permissions** (scopes) the connector asks for.

<Flow
  steps={[
    { icon: 'app-window', title: 'You register an app', text: 'In the provider console, with the redirect URI and permissions from the connector page.', tone: 'cyan' },
    { icon: 'key-round', title: 'You store the app in nexxus', text: 'Client-ID and Client-Secret in the connector configuration.' },
    { icon: 'user-check', title: 'Each person signs in', text: 'In a pop-up at the provider, with their own account.', tone: 'lavender' },
    { icon: 'circle-check-big', title: 'The AI Assistant works with that account', text: 'Tokens stay on the server and refresh by themselves.' },
  ]}
  caption="You register the app once. Every Microsoft connector can share one app, and so can every Google connector."
/>

<Steps>

1. Open the connector page and look at <Ui>Setup</Ui>.

   The head says <Ui>{'At {name}'}</Ui> with the chip <Ui>No app set up yet</Ui>, a button to the provider's console and the provider's guide. Below are numbered steps. The step that mentions the redirect URI carries a copy box <Ui>Redirect URI (enter it in the provider's app)</Ui> with <Ui>Copy</Ui>, and the step about permissions lists <Ui>Permissions the app has to allow</Ui>. Steps that only this connector needs are marked <Ui>{'Only for {name}'}</Ui>.

   <Screenshot src={shot_plg_detail_oauth_setup} url="/plugins/outlook-mail" alt={"The setup guide for Outlook Mail with redirect URI and permissions"} caption={"Setup shows the provider's steps with the redirect URI and the permissions built in."} />

2. Register the app in the provider's console and follow the steps. The guides for the main providers are summarised [below](#provider-guides).

3. Back in nexxus, enter <Ui>Client-ID</Ui> and <Ui>Client-Secret</Ui> under <Ui>Configuration</Ui> and click <Ui>Save</Ui>.

4. <Ui>Setup</Ui> now shows <Ui>{'{name} is all set up'}</Ui>. Copy the <Ui>Message to your users</Ui> and send it to your team. It tells them where to click and that the assistant only sees what their own account may see. The guide folds away, <Ui>Show guide</Ui> opens it again.

   <Screenshot src={shot_plg_detail_ready} url="/plugins/outlook-mail" alt={"Outlook Mail fully set up, with the message for users"} caption={"When setup is done, the page hands you a message to send to your users."} />

5. Try it yourself: under <Ui>My connection</Ui> click <Ui>Connect</Ui>, tick the permission groups you want to grant, and sign in in the pop-up. After a moment you see <Ui>{'{name} is connected.'}</Ui>

</Steps>

### The redirect URI

nexxus has exactly one redirect URI, the same for every connector and every provider:

```text
https://<your nexxus address>/api/plugins/oauth/callback
```

The connector page always shows the exact value for your installation, so copy it from there. On a self-hosted installation, nexxus builds it from the public address in the setting `sso.issuer` (environment variable `NEXXUS_SSO_ISSUER`). Set that to the public HTTPS address of your backend, otherwise the address is taken from the incoming request and may not match what the provider expects.

### Provider guides

nexxus ships setup guides for 25 OAuth providers. The connector page shows the one that fits, with the redirect URI and the permissions built in. Here is what they ask for.

#### Microsoft

One Entra app covers every connector that signs in at Microsoft: Outlook Mail, Outlook Calendar, Microsoft Teams, SharePoint, OneDrive, Excel, Microsoft Planner, Microsoft Entra ID, Azure DevOps, Dynamics 365, Power BI, Microsoft Fabric, Azure Data Explorer, Azure Databricks and Azure Data Factory. A Microsoft connector without its own client ID uses the app of another installed Microsoft connector. If there is none, it uses the Entra app that your [sign-in with Microsoft](/setup/sign-in/) already uses. In that case, leave <Ui>Client-ID</Ui> and <Ui>Client-Secret</Ui> empty and only add the redirect URI and the permissions to that app.

1. In the Microsoft Entra admin center, go to "Entra ID" › "App registrations" › "New registration", create an app and choose "Single tenant only" under "Supported account types". Skip this if you use the app of your Microsoft sign-in.
2. Under "Authentication" › "Add Redirect URI", pick the platform "Web" and enter the redirect URI.
3. Under "API permissions" › "Add a permission" › "Microsoft Graph" › "Delegated permissions", add the permissions shown on the connector page. If one shows "Yes" under "Admin consent required", click "Grant admin consent for ..." afterwards, otherwise sign-in fails with "Admin approval required".
4. Under "Certificates & secrets" › "Client secrets" › "New client secret", create a secret and copy its "Value" right away. It is shown only once, and it expires after 24 months at most.
5. On "Overview", copy the "Application (client) ID" and the "Directory (tenant) ID". Enter them with the secret in <Ui>Configuration</Ui>. The directory ID goes into <Ui>Entra-Mandant (Domain oder ID)</Ui>.

Azure DevOps adds its own step: under "API permissions", pick the API "Azure DevOps" instead of Microsoft Graph and add `vso.project`, `vso.work_write`, `vso.code`, `vso.build_execute` and `vso.wiki`. It accepts work and school accounts only.

Microsoft Fabric, Azure Data Explorer, Azure Databricks and Azure Data Factory add one step each as well: under "API permissions", pick their API instead of Microsoft Graph. That is "Power BI Service" for Microsoft Fabric, "Azure Data Explorer", "AzureDatabricks" and "Azure Service Management" for Azure Data Factory. The connector page names the permissions to add.

#### Google

One Google app covers Gmail, Google Calendar, Google Drive, Google Docs, Google Sheets and BigQuery. Each connector adds one step: enable its API in the library.

1. In the Google Cloud Console, create a project or pick an existing one.
2. Under "APIs & Services" › "Library", enable the API the connector needs (for Google Docs, the "Google Docs API").
3. Under "Google Auth Platform" › "Branding", click "Get started" and enter an app name and support email. Under "Audience", choose "Internal" if only accounts of your Google Workspace organisation connect. "External" is for all other accounts. While the app is in testing, add everyone who should connect under "Audience" › "Test users".
4. For "External" only: under "Google Auth Platform" › "Data Access" › "Add or Remove Scopes", add the permissions from the connector page and save.
5. Under "Google Auth Platform" › "Clients", create a client of type "Web application" and enter the redirect URI under "Authorized redirect URIs".
6. Copy client ID and client secret right away. Google shows the full secret only when it is created.
7. Enter both values in <Ui>Configuration</Ui> and save.

#### Atlassian

One app covers Jira Cloud and Confluence Cloud.

1. In the Atlassian developer console, choose "Create" › "OAuth 2.0 integration" and give it a name.
2. Under "Authorization", click "Configure" next to "OAuth 2.0 (3LO)", enter the redirect URI as the "Callback URL" and save.
3. Under "Permissions", add the API of the connector (Jira or Confluence) and its permissions via "Configure". Use the same app for both and add both APIs.
4. Under "Distribution", switch on "Enable sharing". Without it, only the person who created the app can use it.
5. Under "Settings", copy the "Client ID" and the "Secret" and enter them in <Ui>Configuration</Ui>.

#### Other providers

These providers have a guide on the connector page as well. Each follows the same pattern: create the app in the console, enter the redirect URI, add the permissions, copy client ID and secret into <Ui>Configuration</Ui>.

| Provider | Where you register the app | Connectors |
|---|---|---|
| Airtable | Airtable, OAuth integrations | Airtable |
| Asana | Asana Developer Console | Asana |
| Box | Box Developer Console | Box |
| Calendly | Calendly Developer | Calendly |
| Canva | Canva Developer Portal, Your apps | Canva |
| ClickUp | ClickUp, Settings, Apps | ClickUp |
| Close | Close, OAuth Apps | Close |
| Cloudflare | Cloudflare Dashboard, OAuth clients | Cloudflare |
| Dropbox | Dropbox App Console | Dropbox |
| GitHub | GitHub, Developer settings | GitHub |
| HubSpot | HubSpot, Development | HubSpot |
| Linear | Linear, Settings, API | Linear |
| Miro | Miro, Settings, Your apps | Miro |
| monday.com | monday.com Developer Center | monday.com |
| Notion | Notion Developer portal | Notion |
| Pipedrive | Pipedrive Developer Hub | Pipedrive |
| Salesforce | Salesforce Setup, App Manager | Salesforce |
| Slack | Slack API, Your Apps | Slack |
| Todoist | Todoist App Management Console | Todoist |
| Webex | Webex for Developers, My Webex Apps | Webex |
| Wrike | Wrike, Apps & Integrations | Wrike |
| Zoom | Zoom App Marketplace | Zoom |

GitLab has no guide of its own. Its page shows general OAuth steps: create an OAuth application in your GitLab instance, enter the redirect URI, allow the permissions, and enter the application ID and secret together with the address of your GitLab instance in <Ui>Configuration</Ui>.

### OAuth without an app

Zapier signs in with **automatic registration**: at the first connection, nexxus registers itself as an app with the provider. <Ui>Setup</Ui> says <Ui>Nothing to set up: on the first connection this application registers itself as an app at the provider. Everyone just clicks "Connect".</Ui>

### Client ID and secret for the organisation

Personio and PayPal sign in as the organisation's app, not as a person. Enter the client ID and secret from the provider's API credentials in <Ui>Configuration</Ui>. <Ui>Connection for everyone</Ui> then says <Ui>Connects by itself with the client ID and client secret from the configuration, on the first call.</Ui> No person connects anything. For PayPal, the connector page adds its own steps: turn on "Transaction Search" for the REST app in the PayPal Developer Dashboard, otherwise PayPal refuses to list transactions.

## How your users connect

After setup, people connect in one of four places. All of them run the same sign-in.

- The connector page under <Ui>My connection</Ui>, the link in your <Ui>Message to your users</Ui>.
- The chat: the card <Ui>Connection missing</Ui> when the AI Assistant needs the account, the <Ui>Connect</Ui> button in the connector menu, or the row <Ui>Connect accounts</Ui> under the input of a new conversation.
- <MenuPath to="My profile > Connected accounts" />, section <Ui>Connect more accounts</Ui>: one row per provider with the connectors it covers.
- The desk, which lists the connectors the organisation set up for the person, one click per provider.

For OAuth connectors with permission groups, the person first sees <Ui>{'What may the assistant do at {name}?'}</Ui> and ticks what to grant. Then the provider's sign-in opens in a pop-up. After signing in, the pop-up closes by itself.

<Screenshot src={shot_plg_dlg_permissions} url="/plugins/outlook-mail" alt={"The permission choice before connecting Outlook Mail"} caption={"Only the ticked groups are requested from the provider."} />

<MenuPath to="My profile > Connected accounts" /> lists every account a person has connected: the provider, the status (<Ui>Connected</Ui>, <Ui>Expired</Ui>, <Ui>Revoked</Ui>, <Ui>Error</Ui>), which connectors use it, which permissions it holds and <Ui>{'Valid until {at}'}</Ui>. Shared connections appear with <Ui>Connection for everyone in this tenant</Ui> and who connected them.

<Screenshot src={shot_plg_connected_apps} url="/profil/verbundene-apps" alt={"The connected accounts of a person with one connection and one account still to connect"} caption={"Each connection shows which connectors use it. Below are the connectors that still need your account."} />

## When someone asks for a connector

People who miss a connector do not need to know who the admin is. On the desk they click <Ui>Missing a connector? Ask an admin</Ui>, type what they need (for example "Jira for our tickets") and click <Ui>Ask</Ui>. Everyone with the right to manage connectors gets an entry in the bell and, unless they switched it off, an e-mail. A person can ask for the same connector once a day.

Each admin decides in <MenuPath to="My profile > Notifications" /> whether the e-mail comes: <Ui>E-mail when someone asks for a connector</Ui>.

## Reach systems in your own network

By default, connectors may only call public addresses over HTTPS. That protects your network: anyone who builds a connector types in an address, and without this rule the nexxus server could be pointed at internal systems. When a connector should reach an internal system on purpose, such as Paperboi on a server in the office network, you release it.

<Steps>

1. On the catalog page, click <Ui>Settings</Ui> in the action bar. <Ui>Connector settings</Ui> opens.

2. Under <Ui>Network allowlist</Ui>, enter what to release:

   - <Ui>Address ranges (CIDR)</Ui>: one per line, for example `10.39.0.0/16`.
   - <Ui>Host names</Ui>: one per line, exact (`paperboi.intern.brandt.example`) or with `*.` in front for all subdomains (`*.intern.brandt.example`).
   - <Ui>Allow unencrypted http:// for these targets</Ui>: internal servers often have no certificate. Public addresses always need HTTPS.

3. Click <Ui>Save</Ui>.

</Steps>

<Screenshot src={shot_plg_settings} url="/plugins/settings" alt={"The network allowlist with an internal range and host names"} caption={"Released targets may be called by connectors, everything else internal stays blocked."} />

The allowlist permits, it does not connect. The target must still be reachable from the nexxus server, through your firewall or VPN. Two rules cannot be switched off: cloud metadata addresses stay blocked, and redirects are checked again at every hop, so a public address cannot bounce a request into your network.

## Check that it works

There is no single test button for catalog connectors, because a connector only works with a real account. Check it this way:

1. <Ui>Setup</Ui> shows <Ui>{'{name} is all set up'}</Ui>.
2. Connect your own account, switch the connector on in a chat, and ask the AI Assistant something that only reads, for example "List my five newest mails".
3. For connectors with permission groups, <Ui>Check connection</Ui> under <Ui>Permissions</Ui> shows which groups the provider granted.
4. <Ui>Recent calls</Ui> lists every call with <Ui>Time</Ui>, <Ui>Action</Ui>, <Ui>Person</Ui>, <Ui>Duration</Ui> and <Ui>Result</Ui> (<Ui>Succeeded</Ui> or <Ui>Error</Ui>, with the error message on hover). The head of the page shows the number of calls in the last 30 days.

Your own MCP connectors do have a test, see [Build your own connector](/plugins/build/).

<Screenshot src={shot_plg_detail_calls} url="/plugins/paperboi" alt={"The recent calls of Paperboi with successful and failed calls"} caption={"Recent calls show who called which action, without content."} />

## What happens behind the scenes

- **One connection per provider and app.** nexxus stores a connection for the provider and the client ID the tokens were issued to. Connectors of the same provider that use the same app share it. A connector with a different app gets a connection of its own and never overwrites another app's tokens.
- **Asking only for what is missing.** When a person connects a second connector of the same provider, the sign-in asks for what is already granted plus what the new connector needs. The provider's consent screen shows only the new part.
- **Tokens stay on the server.** Tokens and keys are stored encrypted with the installation's secret key and are never sent to the AI gateway, the model or the browser. OAuth tokens refresh a minute before they expire, and a background job refreshes them ahead of time every 10 minutes.
- **The sign-in is single-use.** Each sign-in carries a random value that is valid for 10 minutes and used once, and only the person who started it can finish it.
- **Disconnecting revokes.** <Ui>Disconnect</Ui> asks the provider to revoke the access where the provider offers that, then deletes the tokens.
- **Uninstalling keeps connections.** People's connections stay and are used again after a new installation.
- **Rights take effect within seconds.** nexxus checks connector rights on every call and remembers the answer for 5 seconds per person.

## When something goes wrong

### The connection error dialog

When a connection fails, nexxus opens a dialog instead of a short error message. It shows the reason as the title, the provider's own message in a red box, the steps under <Ui>How to fix it</Ui> and, for people who manage the connector, the steps under <Ui>As an administrator</Ui> with the redirect URI to copy. Everyone else reads <Ui>Only an administrator can fix this. Send them this message and try again afterwards.</Ui> At the bottom are the <Ui>Error code</Ui>, <Ui>Close</Ui>, <Ui>Connect again</Ui> and, where it helps, <Ui>Open connector settings</Ui>.

<Screenshot src={shot_plg_dlg_connect_error} url="/plugins/outlook-mail" alt={"The connection error dialog when no OAuth app is set up"} caption={"The dialog explains the failure and how to fix it, with the redirect URI to copy."} />

| Title in the dialog | Error code | What to do |
|---|---|---|
| <Ui>{'Sign-in for {name} is not set up yet'}</Ui> | `OAUTH_APP_MISSING` | Admin: create an OAuth app in the provider's developer console, enter the redirect URI exactly as shown, save client ID and secret in the connector's <Ui>Configuration</Ui>. For Microsoft connectors, the app of another Microsoft connector or of the Microsoft sign-in is used when one exists. |
| <Ui>{'The Entra tenant for {name} is invalid'}</Ui> | `OAUTH_TENANT_INVALID` | Admin: check <Ui>Entra-Mandant (Domain oder ID)</Ui>. It expects a domain like company.onmicrosoft.com or the directory ID. Save and connect again. |
| <Ui>{'{name} does not allow automatic sign-in'}</Ui> | `OAUTH_NO_REGISTRATION` | Admin: if the server also accepts an API key or token, switch the connector to custom headers. Otherwise ask the operator to enable dynamic client registration. |
| <Ui>{'The sign-in to {name} expired'}</Ui> | `OAUTH_STATE_EXPIRED` | Click <Ui>Connect again</Ui> and finish the sign-in in the new window within ten minutes. |
| <Ui>{'The sign-in to {name} belongs to another session'}</Ui> | `OAUTH_OTHER_SESSION` | Make sure you are still signed in to nexxus and the sign-in window opened in the same browser. Then connect again. |
| <Ui>{'The sign-in to {name} was declined'}</Ui> | `OAUTH_ACCESS_DENIED` | Connect again and accept the requested permissions. If the provider says "Admin approval required", an administrator of your organisation approves the app there: in Microsoft Entra under Enterprise applications, in the Google Admin console under API controls. |
| <Ui>{'{name} cancelled the sign-in'}</Ui> | `OAUTH_PROVIDER_ERROR` | Read the provider's message. Admin: check that the redirect URI is entered exactly as shown and that the app may request the connector's permissions. |
| <Ui>{'The provider does not recognise the app for {name}'}</Ui> | `OAUTH_CLIENT_INVALID` | Admin: compare client ID and secret with the app at the provider. Client secrets expire, at Microsoft after two years at most. Check the redirect URI. |
| <Ui>{'The server cannot reach {name}'}</Ui> | `OAUTH_UNREACHABLE` | Connect again in a few minutes. If it persists, check the network allowlist and the server's firewall. |
| <Ui>{'{name} did not confirm the sign-in'}</Ui> | `OAUTH_TOKEN_FAILED` | Connect again. Admin: check the app at the provider and the connector configuration. The message in the dialog contains the provider's answer. |
| <Ui>{'The sign-in window for {name} was blocked'}</Ui> | `POPUP_BLOCKED` | Click the blocked pop-up icon in the address bar, allow pop-ups for nexxus and connect again. |
| <Ui>{'{name} could not be disconnected'}</Ui> | `DISCONNECT_FAILED` | Reload the page and disconnect again. If it persists, send the message to an administrator. |
| <Ui>{'Connecting to {name} did not work'}</Ui> | `UNKNOWN` | Try again. If it persists, send the message to an administrator. |

If the pop-up could not report back, for example because the provider's page cut the link to nexxus, nexxus asks the server what became of the sign-in and shows the same dialog.

### Other messages

Some messages come from the server and are in German in every language of the app:

| Message | Meaning and fix |
|---|---|
| `Pflichtfelder fehlen: ...` | Required fields are missing. Fill in the fields named in the message. |
| `Client-Secret und Client-ID sind gleich. Beim Anbieter steht das Secret in einem eigenen Feld; bitte dieses eintragen.` | Client secret and client ID are identical, usually because a password manager filled in the wrong value. Copy the secret from its own field at the provider. |
| `... ist für den Mandanten noch nicht verbunden; das richtet ein Administrator auf der Connector-Seite ein.` | The connector works only with a shared connection and nobody has connected it. Connect it under <Ui>Connection for everyone</Ui>. |
| `... steht Ihnen nicht zur Verfügung.` | The person may not use the connector: check <Ui>Only for roles</Ui>, <Ui>Only for business units</Ui> and the right `ai.plugin.use`. |
| `Keine Berechtigung (ai.plugin.connect).` | The person lacks the right to connect an account. Add `ai.plugin.connect` to their role. |
| `Die Anmeldung ist abgelaufen. Bitte neu verbinden.` | The provider no longer accepts the token. The person clicks <Ui>Reconnect</Ui>. |
| `...: Ziel gesperrt: ...` | A call was blocked by the network rules. Release the target under <Ui>Network allowlist</Ui>, or use HTTPS. |
| `Verbindung fehlgeschlagen` in the pop-up | The sign-in failed and the pop-up could not tell nexxus. The pop-up shows the reason. Close it with "Fenster schließen" and connect again. |

## Next steps

<CardGrid>
  <LinkCard title="Connector catalog" description="Every connector that ships with nexxus and how it signs in." href="/plugins/catalog/" />
  <LinkCard title="Build your own connector" description="Connect your own MCP server or API, with a connection test." href="/plugins/build/" />
  <LinkCard title="Roles" description="Give people the connector rights they need." href="/setup/roles/" />
</CardGrid>