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. See the manifest reference for every field. Kortix declares channel and computer connectors when you connect a chat platform or a machine.

Connectors and connections

A connector is the agent-facing permission package. It contains:

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

A connection is one connected account or credential for the connector. Every connection uses the connector's policies.

The authorization strategy is:

• project for connections available to eligible project members
• user for a connection owned by the acting project member

A service account cannot use a member's user connection. Multiple connectors can reference the same provider app. Use separate connectors when one app needs different policies.

Providers

A connector uses one provider type:

• pipedream — managed OAuth for supported SaaS apps
• openapi, postman, graphql, http — direct API connectors
• mcp — a remote MCP server over HTTP or SSE
• channel — a chat platform connection
• computer — one permissioned connector profile for one connected machine

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

Authentication and policy

A connection authenticates with:

• OAuth through Pipedream, 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. Approve or deny the call once. Kortix 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 a direct API with OAuth2

Direct connectors support:

• client credentials
• authorization code with PKCE
• device authorization

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. 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'
    authorization_strategy: project
    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]
    connectors_required: [stripe-read]

connectors_required must be a subset of connectors. A session for this agent returns 409 CONNECTOR_CONNECTION_REQUIRED before sandbox startup when it cannot resolve a valid active connection.

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

Select a session connection

Default resolution follows the connector's authorization strategy. A session can select a specific connection:

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

The binding key is the connector slug. The value is an active connection that matches the connector's strategy.

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.

Use a connector in a session

Inside a session, use the Connector CLI:

kortix connectors ls
kortix connectors call stripe-read <action> '<json-args>'

connectors lists the connectors in scope. call runs one action.

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.