Connectors

A connector links a project to an external tool or service. The agent calls it as a tool. Kortix brokers each call, so the sandbox never holds the connector credential.

You declare most connectors in kortix.yaml, or in a file it lists under imports:. See the manifest reference for every field. Kortix declares channel and computer connectors when you connect a chat platform or a machine.

Browse and add a connector

Open Connectors to browse the managed catalog. Its default list contains managed-provider toolkits connectable with provider-managed authentication or an enabled custom authentication configuration. It does not require an existing connection in your project. A toolkit that needs an unverified custom OAuth configuration stays hidden until that configuration can be verified.

For direct sources, enable Connectors API Discover in the project's feature flags, then select API / MCP on the same page. Enabling the flag does not replace the managed default. The direct catalog groups published OpenAPI, MCP, GraphQL, Postman, and other API surfaces. Select a card, choose a published surface, and complete its connection form. Documentation-only surfaces open the provider's documentation; they are not presented as a ready-to-connect template. Use Add → Manual for a raw API or a schema that the catalog does not contain. Direct discovery also works without a configured managed provider.

Connectors, connections, and accounts

A connector is the agent-facing reach package: a declared capability (which actions, how to reach the service). It is not a role, and it holds no Kortix permission: an agent reaches a connector only when its manifest grant lists the slug and the role verdict allows the call. See One vocabulary, two bindings. A connector contains:

• a project-unique slug
• a display name
• a provider app
• connector policies

A connection is one account — one authorized identity — for the connector: a credential, an OAuth grant, or an API key. A connector can hold several accounts side by side. Every account uses the connector's policies. Each account's owner_type decides who may run a call as it:

• project — a shared account. Reachable by anyone the connector is granted to, human or service account (agent, trigger).
• member — a private account, owned by one project member (owner_id). Reachable only by that member, and only in a private session. A service account (an agent or a trigger acting unattended) can never run as a member's private account.

Multiple connectors can reference the same provider app. Use separate connectors when one app needs different policies.

Add an account

Open the connector in Customize → Connectors. The Accounts tab lists every account you can use or manage in one list. Each card shows who can use the account: Only you, Everyone in project, or the groups and people it is shared with.

Select Add account, name the account, and choose Who can use it:

• Only you — a private account. Any member can add one.
• Everyone in the project — a shared account.
• Specific people or groups — a shared account, narrowed to the people, groups, and agents you pick.

The two shared choices need project.connector.connections.manage. For Specific people or groups, Machine writes the grants before you authorize the account, so the account never holds a credential while it is open to the whole project. An account name must be new: a name that an account of the same owner already uses is refused.

When an agent needs an account, it posts a Connect card in the chat. The card opens the same dialog, with the name the agent suggests already filled in and the audience it asked for preselected. Machine creates a new account, never re-authorizes an existing one, and tells the agent the new account's name so it can run calls as that account.

Choose who can use a shared account

A shared account is usable by everyone in the project until you narrow it. Select Share on the account card. The dialog is the same Grant access dialog used for agents. It lists who can use the account now, and you add:

• Everyone in the project — the default.
• Groups — every member of each group.
• People — one member each. Pick only yourself to keep the account to you.
• Agents — every session of that agent, triggers and shared sessions included. Anyone who can run the agent can use the account through it.

Nothing changes until you select Save. Removing the last group or person makes the account usable by everyone again; the dialog states the result before you save.

A narrowed account follows the private-account rules, with its audience in place of the owner:

• A person in the audience can use it, and only in a private session.
• An agent in the audience can use it in every one of its sessions.
• Any other agent, and a trigger of any other agent, never uses it.
• A session that binds it cannot be shared, unless the account is shared with that session's own agent.
• Only a person changes who can use an account. An agent session gets 403.

A person outside the audience does not see the account. A person who manages the project's connections still sees it, marked Not shared with you, so they can change who can use it.

Share your own private account

Your own Only you account has a Share button too. Sharing it turns it into a shared account for the people and groups you pick (you stay on it unless you remove yourself), or for everyone in the project. From then on it is a shared account: people who manage the project's connections can manage it too.

• Sharing needs project.connector.connections.manage, the same right as adding a shared account. Without it the button is disabled and says why.
• Machine writes the grants first and turns the account shared in one update, so it is never open to the whole project in between.
• A shared account of the same name on the connector blocks it (409): rename one first.

POST /projects/{projectId}/connections/{connectionId}/share
     {"principals": [{"principal_type": "group", "principal_id": "<group-id>"}]}

An empty principals list shares it with everyone. From the CLI: kortix connectors connections share <connection-id> --group <group-id> (also --user <email|id>, repeatable, or --everyone).

Each audience entry is one connection object assignment in the grant store:

POST   /accounts/{accountId}/iam/assignments
       {"principal_type": "group", "principal_id": "<group-id>",
        "role_key": "agent-user", "scope_type": "project", "scope_id": "<project-id>",
        "object_type": "connection", "object_id": "<connection-id>"}
DELETE /accounts/{accountId}/iam/assignments/{assignmentId}

From the CLI, the same writes are:

kortix access grant --group <group-id> --connection <connection-id>
kortix access grant --everyone --connection <connection-id>
kortix access revoke <assignment-id>
kortix connectors connections ls   # the WHO CAN USE column

• principal_type is user, group, or project (everyone in the project; principal_id is the project id).
• Granting or revoking one needs project.connector.connections.manage.
• Only a shared account can be narrowed through these grants. A private account, or an id that is not a connection in this project, answers 404; share your own private account with the share route above instead.
• GET /projects/{projectId}/connections returns each shared account's grants in shared_with, and usable: false on an account the caller sees only to manage it. The session picker offers only usable accounts.

Which identity an account acts as

An account's label is a name chosen before authorization. It does not say which login was used. connected_as does: the email, login, or display name the provider reports for the authorized account.

• Kortix reads it when a Composio authorization finalizes: first the connected account's display name, then the toolkit's "who am I" tool (Gmail, Google Calendar, Google Drive, Linear, GitHub, Slack, Notion, Outlook, Microsoft Teams, HubSpot, Jira, Asana, Figma, Airtable, Salesforce, Trello, Dropbox, Calendly). Google Docs and Google Sheets expose no such tool, so their connected_as stays null.
• An account still carrying a default label (Private connection, Project connection, or the connector name) is relabelled to that identity. A label someone chose is never replaced.
• The connect page shows "Connected as …" the moment the account lands, so a shared account authorized with a personal login is visible right away.
• connected_as is on every connection (GET /projects/{projectId}/connections), on the accounts list, in kortix connectors accounts <slug> and kortix connectors connections ls (the CONNECTED AS column), and on the account rows in Customize → Connectors.

Rename an account

Rename an account without re-authorizing it:

PUT /projects/{projectId}/connections/{connectionId}/label   {"label": "Support inbox"}
kortix connectors connections rename <connection-id> Support inbox

In the dashboard, open the connector, then ⋯ → Rename on the account row. Only the label changes. The authorized account, its owner, its default flag, and the provider state stay as they are. The same gate applies as for disconnect: your own private account, or project.connector.connections.manage for a shared one.

A rename is refused with 400 for me, project, or a UUID-shaped label, because --account resolves those before labels. It is refused with 409 when another account of the same owner already has that label, compared case-insensitively.

Connect a different account

A connect link for a slot that already holds an active account does not re-authorize it. The provider reuses the account, and the connect page shows Already connected. To use a different login, add a new account on the connector, make it the default, then disconnect the old one.

A call that names no account resolves to the caller's own default private account first, then the project's default shared account. Every call result echoes which account it ran as (account: { connection_id, label, owner_type }), so the transcript always shows the identity a tool call used. List the accounts a connector can be called as, default first, with GET /connectors/projects/{projectId}/connectors/{slug}/accounts — or kortix.project(projectId).connectors.accounts(slug) on the SDK.

Providers

A connector uses one provider type:

• composio — managed OAuth for supported SaaS apps
• pipedream — legacy managed OAuth, kept for rollback only
• openapi, postman, graphql, http — direct API connectors
• mcp — a remote MCP server over HTTP or SSE
• channel — a chat platform connection
• computer — each member's connected machine is one account

See Slack and channels and Computers for the managed provider flows.

Apps that need your own OAuth app

Composio holds its own OAuth app for most toolkits. For some it holds none: X (twitter) since February 2026, and OAuth-only toolkits such as xero, spotify, google_chat, googleforms, and zoom_chat. On 2026-09-26 there were 47. Composio cannot connect them until the Composio project holds an auth config with your own OAuth app.

• Until that auth config exists, the Connectors catalogue does not list the toolkit. A connector already declared for it fails to sync with 422 composio_auth_config_required, and the message names the toolkit.
• To enable one, register an OAuth app with the provider. In the Composio dashboard, open Auth Configs, create an auth config for the toolkit, and enter the app's client ID and secret. Add the redirect URI the dashboard shows to the provider app.
• Machine finds the enabled auth config itself. You do not restart or redeploy. The catalogue lists the toolkit within 60 seconds. The next sync and connect use the auth config immediately.
• When more than one enabled auth config exists for a toolkit, Machine uses the newest. Disable the old one to rotate an OAuth app.
• Toolkits that Composio connects with its own app keep using it. Machine never selects an auth config for them.

Authentication and policy

A connection authenticates with:

• OAuth through Composio, a channel install, or a native OAuth2 grant
• an API key or token entered through the dashboard or SDK

Kortix encrypts connection data and resolves it server-side for each tool call. The agent requests an action. Kortix attaches the credential, checks the agent grant and connector-connection policy, calls the external API, and returns the result.

Connector policies belong to the connector. A connection cannot override them. Project guardrails apply above connector-connection policies.

By default, an unmatched connector action runs without approval. Set policy.default_mode: risk to require approval for unmatched write and destructive actions. Set sensitive: true to make require_approval the connector's unmatched-action default, including reads. Explicit project or connector-connection rules still apply first.

Approve one governed call

require_approval creates one decision for one connector call. The Connector returns 202 pending_approval with approval_url, approval_summary, and execution_id. It does not keep an HTTP request open.

Share approval_url with any teammate. The URL identifies the request but does not grant authority. The page requires a signed-in Kortix account. Kortix then verifies that the account can access and approve actions in the project.

The approval page shows the redacted parameters that the connector will receive. A caller can add approval_context (CLI: --reason) to describe the effect. Use it when the parameters are only references: gmail.send_draft takes a draft id, so the agent states the recipient, subject, and body. The page shows this text as the agent's description, not verified. The parameters remain the evidence. Machine never sends approval_context to the provider.

Approve or deny the call once. Add an optional message to the decision. The message goes back to the agent with the decision, so a deny can say what to do instead.

Every pending call also appears in Review → Needs you for the project. Open Review from the sidebar; its count shows how many items wait for you. A call opens in the same approval view as its approval link, so you see the connector, the parameters, and the agent's description before you decide.

When the call comes from a Slack or Teams session, Machine posts an approval card in that thread. The card shows the agent's description, the parameters, and Approve / Deny. In Slack, Reply… opens a box for a message to the agent; in Teams, the card has the message box inline. Only a project manager or the person who started the session can decide. A decision made anywhere (the thread, Machine, or the approval page) replaces the card's buttons with the outcome, and the agent continues in the same thread. Machine sends the decision back into the session through a durable callback. An approval applies only to the exact request digest. A changed recipient, subject, body, channel, URL, or other parameter requires a new decision.

Open the session's Audit panel to use the same parameter view. Historical entries remain read-only. There is no session-wide approval option. Use an explicit always_run policy only when a connector action must run unattended.

Connect with OAuth

Connect an MCP server that uses OAuth 2.1

Kortix implements the MCP authorization specification. Open the connector, select Add credential, then select the OAuth 2.0 tab. Kortix probes the server and reads its metadata:

1. The unauthenticated probe returns 401 with WWW-Authenticate: Bearer resource_metadata="…".
2. Kortix reads the protected resource metadata (RFC 9728) at that URL, or at /.well-known/oauth-protected-resource.
3. Kortix reads the authorization server metadata (RFC 8414 or OpenID Connect discovery) for the first authorization server the resource names.

When that server advertises registration_endpoint, Kortix registers itself as an OAuth client (RFC 7591) and shows one button: Connect <server>. You create no application, and you copy no client ID or secret. Kortix then runs Authorization Code with PKCE (S256) and binds the token to the server with the resource parameter (RFC 8707).

Register this redirect URI when a server needs one in advance:

https://api.kortix.com/v1/connectors/oauth2/callback

When the server publishes endpoints but no registration_endpoint, Kortix prefills the authorization URL, token URL, and scopes. Enter the client ID of an app you create with that provider. When the server publishes no metadata, enter every field.

Kortix keeps the MCP session: it runs initialize and notifications/initialized on demand, then sends Mcp-Session-Id on later calls. A server that answers without a session never sees the handshake.

Kortix binds each connection to the authorization server that issued it. When the callback carries an iss parameter (RFC 9207), Kortix rejects it unless it matches the recorded issuer — a code minted by a different server is refused before it is redeemed.

Authorize from the CLI

The dashboard is one way to run this flow, not the only one. Declare the connector in kortix.yaml, then authorize it from a terminal or an agent session:

connectors:
  - slug: read-ai
    name: Read AI
    provider: mcp
    url: 'https://api.read.ai/mcp'
    auth:
      type: bearer

kortix connectors authorize read-ai --json

The command creates the connection, runs the discovery chain, registers Kortix as a client when the server supports RFC 7591, and returns the URL to approve:

{
  "connection_id": "7b1a16b2-...",
  "registered": true,
  "scopes": ["openid", "offline_access", "mcp:execute", "meeting:read"],
  "authorization_url": "https://authn.read.ai/oauth2/auth?response_type=code&...",
  "expires_at": "2026-08-19T14:48:26.345Z"
}

An agent returns authorization_url to the person it is working with. After they approve, the agent confirms:

kortix connectors authorize read-ai --status

The command exits non-zero while the status is error. Use --scope to narrow what is requested. Use --client-id and --client-secret for a server that does not support dynamic client registration.

The same steps are available on the SDK — discoverConnectionOAuth2Resource, registerConnectionOAuth2Client, startConnectionOAuth2Authorization, and getConnectionOAuth2Status.

Kortix refetches the connector's tool catalog as soon as authorization completes, so the connector leaves the error state without a manual sync.

Self-hosted: give the box a stable public URL

The callback URL is derived from KORTIX_URL, the public origin of your API. Authorization servers compare redirect_uri byte for byte, so the value must be stable.

A self-host install started with the zero-config quick tunnel gets a new https://<random>.trycloudflare.com hostname every time cloudflared restarts. The callback URL changes with it. A server that supports dynamic client registration recovers on its own — the next authorization registers a new client against the current URL. A server that needs a pre-registered OAuth app does not: you must update its allowed redirect URI after every restart.

Set CLOUDFLARE_TUNNEL_TOKEN and CLOUDFLARE_TUNNEL_HOSTNAME for a named tunnel, or point KORTIX_URL at your own domain. Then register one callback URL once:

https://<your-kortix-host>/v1/connectors/oauth2/callback

Connect a direct API with OAuth2

Direct connectors support:

• client credentials
• authorization code with PKCE
• device authorization
• dynamic client registration (RFC 7591)

For client credentials, enter the token URL, client ID, scopes, and client secret. You can use client_secret_basic, client_secret_post, client_secret_jwt, or private_key_jwt token-endpoint authentication.

For authorization code, enter the authorization URL and token URL. For device authorization, enter the device-authorization URL and token URL. An RFC 8414 discovery URL can provide these endpoints.

Kortix encrypts the OAuth2 configuration and tokens. It refreshes access tokens before expiry, and it stores each rotated refresh token. Revoking the connection blocks the next connector call.

For Microsoft Graph, use:

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
https://graph.microsoft.com/.default

For direct SharePoint REST calls, use the SharePoint resource scope:

https://{tenant}.sharepoint.com/.default

Connect with an API key

connectors:
  - slug: stripe-read
    name: Stripe read access
    provider: openapi
    spec: 'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json'
    auth:
      type: bearer
    policies:
      - match: 'get_*'
        action: always_run
      - match: '*'
        action: block

Grant an agent access

Add the connector slug to the agent's connectors field:

agents:
  release-bot:
    connectors: [stripe-read]

Omit connectors, and the agent gets none. Merge the change before it takes effect.

connectors_required is deprecated. The manifest still accepts it, but nothing reads it: a session is never refused at create time for a connector with no usable account. A session-create refusal for a missing connector was unreachable in practice — a private-only connector had no shared account to offer, so the refusal had no remedy the caller could act on. The gate is now the connector call: an agent granted stripe-read can start its turn immediately, and only a call that actually needs the connector is denied (see When a call is denied) — with a remedy attached.

Select an account

Two independent ways to pick which account a call runs as — pin one for the whole session, or name one on a single call.

Pin a session-wide default

A session can override the connector's default account for every call it makes:

{
  "connector_bindings": {
    "stripe-read": {
      "connection_id": "00000000-0000-4000-8000-000000000000"
    }
  }
}

The binding key is the connector slug. The value is an account (connection) this session's caller is entitled to reach.

Use GET /projects/{projectId}/sessions/{sessionId}/scope to read the effective binding. Use PUT on the same path to replace it. The replacement applies to the next tool call without restarting the session.

Name an account on one call

List the accounts a connector can be called as — default first — with:

GET /connectors/projects/{projectId}/connectors/{slug}/accounts

{
  "connector": "stripe-read",
  "accounts": [
    { "connection_id": "...", "label": "Shared workspace", "owner_type": "project", "is_default": true, "connected_as": "billing@example.com" },
    { "connection_id": "...", "label": "My Stripe", "owner_type": "member", "is_default": false, "connected_as": null }
  ]
}

Then name one on the call, by connection id or by label (case-insensitive), or with the two selector words me (your own default private account) and project (the project's default shared account):

kortix connectors call stripe-read get_balance '{}' --account me
kortix connectors call stripe-read get_balance '{}' --account "Shared workspace"

A call that names no account resolves to the caller's own default private account first, then the project's default shared account — unchanged from before a connector could hold more than one account. A named account that does not resolve is denied, never silently substituted onto a different one (see When a call is denied). Every successful call result echoes which account it ran as: account: { connection_id, label, owner_type }.

Use a connector in a session

Inside a session, use the Connector CLI:

kortix connectors ls
kortix connectors accounts stripe-read
kortix connectors call stripe-read <action> '<json-args>' [--account <id|label|me|project>]

connectors lists the connectors in scope. accounts lists the accounts this caller may call stripe-read as — default first, shared before private within each group. call runs one action, as the named --account or, when omitted, the same default resolution used before a connector could hold more than one account.

Large results

A list or search call can return more than a model can read: tool output above ~50 KB is truncated. Save the result to a file and work through it with code:

kortix connectors call linear graphql.issues '{"first":250}' --out /workspace/output/issues.json
# → { "ok": true, "account": …, "saved_to": "/workspace/output/issues.json",
#     "bytes": 93037, "shape": { "issues": { "nodes": "array(250) of {id,title,…}",
#     "pageInfo": { "hasNextPage": true, "endCursor": "…" } } } }
jq '.data.issues.nodes[] | {id, title}' /workspace/output/issues.json

--out writes the full JSON result, creating parent directories. Stdout gets the call envelope without data, plus saved_to, bytes, and shape: the outline of data (keys, array lengths, and every pageInfo). The exit code is unchanged.

The kortix-connectors MCP tool call does the same without a flag. A result larger than 16 KB is saved under /workspace/.kortix/state/connector-results/ and the tool returns { saved_to, bytes, shape, preview, hint }, with a ~2 KB preview. That directory ignores itself in git. A smaller result is returned inline.

Attach files

A call never carries file bytes in its arguments. Stage the file, then put its reference in the arguments. The gateway reads the bytes server-side and writes them into the request.

kortix connectors call microsoft-graph.sendmail @mail.json \
  --attach /workspace/artifacts/report.pdf

--attach stages the file and appends a reference to the action's attachments array. The array is found in the action's input schema: attachments for the Email channel, body.message.attachments for Microsoft Graph sendMail. Name it with --attach-path body.message.attachments when the schema is unusual. Large JSON arguments go in a file (@mail.json) or on stdin (-).

To place a file yourself, stage it first:

kortix connectors upload /workspace/artifacts/report.pdf --connector microsoft-graph
# → { "attachment_id": "…", "ref": { "$kortix_attachment": "…" }, … }

Put ref anywhere in the arguments. The gateway replaces it by position:

Rules:

• Files come from /workspace/output, /workspace/artifacts, /workspace/reports, or /workspace/deliverables. Symbolic links and hard links are refused. Copy a file there first.
• One call carries up to 20 files and 25 MiB in total. The upstream API can set a lower limit: Microsoft Graph documents 3 MB as the largest file one sendMail request can attach.
• A staged file is private to the session that staged it, used once, and deleted after 24 hours. A failed call releases it for a retry.
• The audit record, the approval preview, and the model see only the reference, never the bytes. An upstream error that echoes the file has the base64 removed.
• Pipedream and Composio connectors do not accept staged files (connector_attachments_unsupported).

The MCP server offers the same flow: call takes attachment_files (and an optional attachment_path), and upload_attachment returns a ref. The SDK equivalent is connectors.uploadAttachment(bytes, { filename, contentType, connector }), which returns ref.

When a call is denied

A denied call answers { ok: false, status: "denied", reason, hint }. reason is a stable code; hint says what to do.

connect_url is the whole remedy for an unconnected connector: a session is never refused up front for one (see Grant an agent access), so the denial itself carries the fix. The agent surfaces the link verbatim; the web transcript renders it as a one-click Connect button. The link authorizes a private account for the human who opens it by default — connecting a shared account is an explicit choice (kortix connectors connect stripe-read --owner project, gated on project.connector.write).

The channel connector that created a session (Slack, Teams, email) is always callable from that session, whatever the agent's grant says, so the agent can always report in the thread it was asked from.

A session's grant follows kortix.yaml: a change to the running agent's connectors: (including kortix connectors add --apply) applies on the next call. The grant records which manifest blob and commit it came from; a read that would replace it from the same blob is confirmed by a second read first, and a read from an older commit never replaces it.

Slack and Microsoft Teams connect from the dashboard the same way as OAuth apps. Connecting Slack writes a channel connector to kortix.yaml for you. See Slack & channels.