Create a connector and connect an account

How to create a connector from a package, connect its organisation account with a key, a password or OAuth, and test, reconnect, disconnect, disable or delete it.

Enterprise module

Connectors is the enterprise connectors module. Creating needs write access to Connectors in the project; connecting, changing settings and deleting need an admin of the project.

Create a connector

1. Open Build → Connectors → Catalog and choose Install on a card. Or open Build → Connectors → Installed, choose Add connector and pick the type under What do you want to connect?
2. Fill in the form. It has three sections: Name, Settings and Sign-in.
3. Choose Create and connect (key, token or password), Create and sign in (OAuth) or Create without connecting.

Create without connecting suits a member who is not an admin: you create the connector and an admin connects it later.

Name

Field	Rules
Name	Shown in lists and in Tools. At most 120 characters. Empty means the package name.
Key	Lowercase letters, digits and dashes, up to 40 characters, starting with a letter or digit. Left empty, it is made from the name, with -2, -3 and so on added if it is taken. A key already used in the project is refused. The key cannot be changed later.
Description	What agents use the connector for. At most 500 characters.

Settings

The settings come from the package: a server address, a database host and port, a repository filter, Read only. Each field says what it expects. Common checks:

Message	Cause
Required.	An empty required field.
Not in the expected format.	The value does not match the field's pattern.
Use at most {limit} characters.	Too long.
Enter a full address that starts with https://.	A URL field needs a full address. The address must not contain a user name or password, and the host name must be one the package allows.
Enter a number., Use {limit} or more., Use {limit} or less.	Number fields.
Not valid JSON.	JSON fields.
Pick at most {limit}.	Multi-select fields.

The package also checks the whole set of settings on the server and works out what depends on them (the API address, an MCP server, a self-hosted server's OAuth endpoints). Some lists, such as repositories or buckets, load from the system once the connector has an account. If a list cannot be read, type the value instead.

Change the settings later under Settings → Edit settings. They are saved as a whole: what you leave empty falls back to its default. A change can have side effects:

• If it moves the server the account signs in to, the account goes to Reconnect required and you must connect again.
• If the connected account uses a sign-in method the new settings no longer allow, you are told to connect again.
• A change to what the connector offers, such as Read only, changes the tool. Press Sync tools if the tool does not follow.

Sign in

The Sign-in section lists the methods the package offers with the current settings. Choose one under Sign-in method. Each method has a Setup guide with the steps at the vendor. A badge shows the kind:

Badge	What you give	Notes
API key	A key, token, or user name and password, in the fields of the method	Console checks it with the system before it keeps it.
OAuth	Nothing in the form. You are taken to the vendor and back.	Needs an OAuth app. See OAuth apps.
Sign-in form	A form the package defines
Public access	Nothing	For systems that show data to everyone. Some limit how much an anonymous reader may ask for.

Use a service account, not your own: the account that signs in becomes the organisation account of the connector.

Keys, tokens and passwords

Paste the value into the field. Secret fields are write-only and are not shown again after saving. Console checks the credential before it stores it (the package's identity check runs against the system), so a wrong key fails here and nothing is kept. Pasting the hint Console shows (… and the last four characters) instead of the full value is refused: Enter the full value, not the hint that is shown.

The Microsoft Entra ID method of Azure Blob Storage is a server-to-server OAuth grant. You enter the client ID and client secret, Console requests a token with them right away, and a refused client or a missing scope is an error at that point. Console asks for a new token from the stored client when the old one ends.

OAuth

Choose Create and sign in or Sign in. Console sends you to the vendor with the access listed under Access it asks for, you approve, and the vendor sends you back to Console. The sign-in link is valid for 10 minutes. A package that offers both read-only and read-and-write OAuth methods shows them as separate sign-in methods.

If no OAuth app is set up for the method, the form says No OAuth app is set up for this sign-in method. An admin can add one under OAuth apps; a member is told to ask a tenant admin.

OAuth apps

Console signs in with an OAuth app registered at the vendor. For most packages it is your own app. Manage them at Build → Connectors → OAuth apps. Only tenant owners and admins can open the page, and the apps are shared by every project in the workspace.

1. Open OAuth apps. The Callback address card shows the redirect URL, in the form https://<your Console address>/api/connectors/oauth/callback. Register exactly this address as the callback (redirect) URL of every OAuth app you create at the vendor.
2. Choose Add on the row of the connector type and sign-in method.
3. Enter Client ID and Client secret from the vendor's OAuth app page, then choose Add app. The access scopes are fixed by the package and are shown read-only.

The table shows, for each sign-in method, Your app, Deployment app (Present or Absent) and which one is Used: Your app, Deployment app or None: OAuth is off. Another column says what is expected: Needs your own app or The deployment provides it. Your own app is used whenever it exists. A deployment app is one the operator set in the server environment, with variables named after the package and the method, for example CONNECTOR_COGNIPEER_GITHUB_OAUTH_CLIENT_ID and the matching _CLIENT_SECRET.

The client secret is stored encrypted and never shown again; only its last four characters are. When you edit an app, leave the secret empty to keep the stored one.

Removing an OAuth app does not disconnect the connectors that use it. They keep working until their token has to be renewed. With no app left, renewal fails and they must be connected again.

What Console stores and shows

• Credentials and OAuth client secrets are sealed (encrypted) before they are stored.
• Views never carry a secret. A hint is shown instead: … and the last four characters. A password gives no characters, only ….
• On the Account tab, Credential shows the hint, with the note The credential itself is never shown.
• Error messages that come back from the system are scrubbed of credential values.

After connecting

The Connection result shows Signed in as (the identity the system reported), Sign-in method, Access granted, Valid until if the credential expires, and Tools synced with a count. A connection can succeed and still carry a warning under Connected, but check this. A tool listing that fails does not undo the connection; Sync tools retries it.

An account has these states:

Status	Meaning	What to do
Active	Works.
Reconnect required	The sign-in no longer works. Tool calls fail.	Reconnect.
Revoked	The system no longer accepts the account.	Connect an account again.

When a credential has an end date, the page warns as it nears: The credential ends soon, then The credential ends in {days} days, and The credential has ended after it. Create a new one at the vendor and connect again before then.

Test the connection

On the Account tab choose Test connection. Console asks the system who the account is, using the stored credential. Connection verified sets Last check to Passed and refreshes the identity. A failure shows The check failed with the reason. When the system rejected the credential, the account moves to Reconnect required.

Reconnect

Choose Reconnect on the Installed list or on the Account tab. The form is the same as for connecting. Connecting replaces the account that is connected now.

Disconnect, disable, delete

Action	What it does	Effect on agents
Disconnect	Removes the account and turns the tool off. An OAuth grant is revoked at the vendor on a best-effort basis. A pasted key or token is not revoked at the vendor; remove it there too.	Tool calls fail until an account is connected again. The connector, its settings and the tool stay.
Disable connector	Turns the tool off. The account stays connected. Open database connections of a SQL connector are closed. Enable connector turns it back on.	Agents cannot use the tool until you enable the connector.
Delete	Removes the connector, its account and its tool. The account is revoked best-effort. Its knowledge sources go with it, each as its When the source is removed setting says.	Agents that use the tool stop working. The Used by list on Overview shows which agents and resources are affected.