Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// admin

Connector authentication

Overview

How basebox and your users authenticate to connected systems: personal credentials per user, shared service accounts, tokens. Which variant a connector uses determines who sees what – which is why this is the most important security question around connectors.

What it is for

When the assistant accesses a wiki, a ticket system or a mailbox through a connector, it has to identify itself there. As an administrator you decide which model is used, and you need to be able to explain to users why they should store a token.

The three models

Model How it works Who sees what Typical connectors
Personal credentials Each person stores their own access token; basebox passes it on to the system with every request Exactly what the person may see in the system themselves E-mail (IMAP), DokuWiki, YouTrack, Nextcloud, Atlassian, Roxtra
Shared service account The administrator stores one account used for all requests All users see what the service account sees Read-only access to generally accessible content, where the connector supports it
No sign-in No account needed – Calculator; web search (the query goes to the provider without user identity)

basebox never uses a shared admin token to fetch data and then filter it per user. With personal credentials, the connected system enforces its own permissions – ACLs, roles, project memberships – exactly as with a direct sign-in by that person.

Where to find the setting

  • Administration → Connectors: per connector the base URL, where applicable a shared service account or an organisation-level API key (e.g. for web search), Test connection, switch.
  • Users: in the chat, click the connector via the "+" icon next to the input bar and enter the personal token there. Alternatively under Settings → Connectors.

Step by step

Introduce a connector with personal credentials:

  1. Enable the connector under Administration → Connectors and enter the system's base URL (on basebox Server, the Platform Operator sets some external endpoints via Helm – see Configuring connectors).
  2. Click Test connection.
  3. Enable the connector in the app settings of the apps in which it should be usable.
  4. Tell your users how to generate a token – for YouTrack the guide is under Create a YouTrack token. Emphasise: a dedicated token, not the login password.
  5. Users enter their token and click Test connection. Only then are the connector's tools available in their chat.

Use a shared service account (where supported):

Only for content that all users may see anyway – a public wiki, a general manual. Create a dedicated account with minimal, read-only rights; do not use a real person's account.

How credentials are stored

  • Write-only. Stored credentials are never returned to the browser, are hidden in logs and are never filled in automatically. A badge merely shows that some are set. Even you as administrator can neither see nor use other users' credentials.
  • Separate per user. Credentials are loaded fresh for every request based on the user identifier; they are not shared or cached between users or sessions.
  • Immediately revocable. If the token is withdrawn in the connected system or the account is deactivated, basebox loses access with the next request.

The complete technical flow with sequence diagram: MCP permission and authorization flow.

Notes

Enable write access deliberately

Tools that change things in the connected system (create, update, delete) are disabled by default per app. Enable them only where that is intended, and only for connectors with personal credentials – so that every change is attributable to the acting person.

Note

  • Web search needs no user sign-in. Optionally you store an API key of your organisation with the search provider; if it is left empty, searches run on the shared basebox quota. A rejected key produces an error, not a silent fallback. Details: Web search.
  • E-mail: IMAP host, port and connection type are set by the Platform Operator; mailbox credentials are entered by users themselves and do not belong in any configuration file.
  • Credentials never appear in production logs; only at log level DEBUG during targeted diagnostic runs.

Frequently asked questions

Why can't I as administrator view a user's credentials? Because they are stored write-only. That protects the users – and you.

Can I store one token for all users so nobody has to enter anything? Only as a shared service account, and only where the connector provides for it and everyone may see the same content. For systems with individual permissions that is the wrong approach.

What happens when a user changes their token? They enter the new token; it is used from the next request on. They can revoke the old one in the source system.

Does the connected system see that the request comes from basebox? It sees a normal API request with the person's credentials – indistinguishable from a direct sign-in by that person.

Need help? Contact support