Connections

A connector describes how Cengrid reaches an external service. A connection is one configured account or service identity using it. API and MCP are interfaces; OAuth, client credentials, API keys and personal access tokens are authentication methods. The two are independent.

The agent never holds the secret. Calls go through core’s scoped broker, which attaches the credential, so the token does not enter the agent’s computer.

Who owns a connection

Connection	Set up by	Available to
Shared organisation connection	An organisation administrator	Eligible activity across the organisation, including future rooms
Shared team connection	An organisation administrator	That team’s rooms and threads, and its members’ direct messages when it is their primary team
Personal connection	The person, in their Keychain	Only their private scope. Using one in a shared room needs the owner’s approval.

The Connections table marks connections a team inherits from the organisation as Inherited. Connection ids are unique within a scope. A team can reuse an organisation connection’s id and its version takes precedence for that team, even if the team’s connection is disabled. Removing the team connection restores inheritance.

Slack the bot is not Slack the connection

The Slack bot is a chat platform: it receives conversations and replies as the bot. A Slack account connection authorises actions as a particular Slack user. See Connect Slack.

Authentication methods

auth	Use for
none	Public or network-restricted APIs
bearer	A bearer token or personal access token
api-key	A key sent in a named header (apiKeyHeader)
google-service-account	A Google API reached with a service-account JSON key and fixed scopes

MCP connections additionally support the client-credentials flow. Built-in OAuth account definitions are covered under Connect your tools.

Declare a REST API in a plugin

A plugin ships secret-free templates in connections.json. Importing a template supplies no credentials.

connections.json

{
  "connections": {
    "reports": {
      "name": "Reports API",
      "description": "Read reports through the shared API",
      "endpoint": "https://reports.example.com/api",
      "auth": "bearer",
      "readOnly": true
    }
  }
}

Each key is the connection id: 2 to 40 lowercase letters, digits or hyphens, starting with a letter.

Field	Requirement
endpoint	Required. A fixed HTTP(S) URL with no credentials, query string, fragment, placeholders or ambiguous path separators.
auth	Required: none, bearer, api-key or google-service-account.
apiKeyHeader	Required for api-key, and only valid there. A valid HTTP header name.
readOnly	Optional, defaults to true. false permits writes through the broker.
headers	Optional map of non-secret extra headers, lower-cased. Reserved and API-key headers are rejected.
writeRules	Optional method and path rules for POST, PUT, PATCH and DELETE. Requires readOnly: false. Paths are relative to the endpoint and * matches one segment. GET and HEAD stay open.
tokenScopes	Required for google-service-account, rejected otherwise.
healthPath	Optional GET path used by Test connection.
name	Optional display name, up to 100 characters. Defaults to the key.
description	Optional, up to 1,000 characters.

A bare map of definitions without the connections wrapper is also accepted. The manifest’s connections field can name a file, an array of files or an inline map. Unknown fields, embedded tokens, reserved authentication headers, OAuth and client-credentials auth are rejected.

Configure a connection

1. Open Connections → Available and choose Configure on the definition.
2. Pick Organisation or a team. Configuring at team scope creates that team’s own connection, even if the organisation has one with the same id.
3. Enter the token or API key. For a Google service account, upload or paste the JSON key and Cengrid derives the service-account email and renews access tokens automatically.
4. Optionally narrow the endpoint to a more specific path under the same origin and base path. The preview shows the effective access mode, write rules and test path.
5. Save, then run Test connection.

Saved secrets are encrypted and never read back into the form. Leave the field blank to keep the saved credential while the endpoint, authentication method and header are unchanged; changing any of those requires re-entering it.

Test and monitor

Test connection never reuses a cached client or token. The durable result is one of:

• Working: a 2xx answer from the test path, or a connection with no authentication that answers 2xx.
• Reachable: the host responded, but with no test path the credential is unverified.
• Failing: with a code and a message naming the cause, such as credentials rejected (401), access refused (403), a redirect, a blocked egress host or an unreachable host. Redirects are never followed.

Every API call and Git request is recorded durably with the connection, scope, principal, outcome and upstream status, and the Connections table shows a 30-day summary.

GitHub as a connection

GitHub is a built-in shared definition with the id github. REST calls go to https://api.github.com and Git remotes live under https://github.com. One token covers both, so anyone in the scope can have the agent clone, push and open pull requests without a personal GitHub connection. It is also the connection Cengrid uses to read plugin repositories. See GitHub connection.

Safety rules the broker enforces

• Requests stay within the configured origin and path, and redirects are rejected.
• A read-only connection allows GET and HEAD only, and refuses Git push.
• With write rules, only the listed methods and path prefixes may write. Git push is checked against the same rules relative to the Git base, so for GitHub, pushing to org/repo needs a POST rule for /org/repo, while REST writes use /repos/org/repo.
• Calls that tunnel a method through a query parameter or body key, such as _method or x-http-method-override, are refused on any connection that limits writes.
• The turn’s egress policy, private-network rules and security posture apply exactly as for any other call.

Reconnect and approvals

Credentials refresh on demand when used near expiry. A failed or revoked refresh token puts the connection in a reconnect-required state. A personal connection is usable in its owner’s private scope. Using one in a shared room needs the owner’s approval, and the design limits that grant to the conversation instead of making it permanent. Approval policies for shared connections, such as requiring a designated group to approve, and session grants are future work.