A connector links your project to an external tool or service, such as Gmail, Stripe, a database, or any HTTP API. The agent calls it as a tool. Kortix brokers every call, so the sandbox never holds the connector's credential. The dashboard may label this area Connections — it is the same feature.

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

Providers

A connector uses one provider type:

pipedream — one-click OAuth for supported SaaS apps, when the deployment has Pipedream configured.
openapi, postman, graphql, http — a direct connector to an API.
mcp — a remote MCP server, reached over HTTP or SSE.
channel — a chat platform connection. See Slack & channels.
computer — a tunnel to a machine you connect. See Computers.

Authentication and policy

A connector authenticates one of two ways:

OAuth — through Pipedream, through a channel install, or through native OAuth2 client credentials for direct API connectors.
API key or token — you declare the connector in kortix.yaml and enter the credential yourself, or reference it from a project secret (legacy).

Kortix never gives a connector's credential to the sandbox. It stores the credential encrypted and resolves it server-side, at call time. The agent requests the action. Kortix attaches the credential, calls the external API, and returns the result.

By default, a connector action runs without approval. Set policy.default_mode: risk in the manifest to require approval for write and destructive actions. Mark a connector sensitive: true to require approval for every action on it, including reads.

Connect with OAuth

Open the project's Connectors page

From the dashboard, open the project's Connectors page and search for the app.

Connect the app

Click Connect and complete the OAuth flow. Kortix stores only the connected-account ID, never the credential itself.

This path creates the connector for you. Skip the next section.

Connect a direct API with OAuth2 client credentials

Use this path for server-to-server APIs that require OAuth2. Microsoft Graph and SharePoint Online use this pattern.

Declare the direct connector

In the Custom connector form, select OAuth 2.0 client credentials under Auth. Kortix configures bearer-token injection and shows the OAuth2 fields before it creates the connector.

Enter the OAuth2 configuration

Enter the token URL, client ID, scopes, and client secret. Existing connectors expose the same fields under Set credential.

For certificate authentication, select Certificate assertion. Enter the PKCS#8 private key PEM and the certificate's Base64url SHA-256 thumbprint (x5t#S256).

Save and verify

Kortix requests a token before it saves the configuration. A rejected client ID, secret, certificate assertion, scope, or resource returns an error.

Kortix encrypts the OAuth2 configuration and access token. The Executor refreshes the token 60 seconds before expiry. PostgreSQL serializes concurrent refreshes for one connection profile. Revoking the profile blocks the next Executor call.

For Microsoft Graph, use https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token and the scope https://graph.microsoft.com/.default.

For direct SharePoint REST endpoints under https://{tenant}.sharepoint.com/_api, use the scope https://{tenant}.sharepoint.com/.default instead of the Microsoft Graph scope.

Connect a user-facing API with OAuth2

For APIs that require a user's consent — Google, Microsoft, GitHub, or any identity provider that speaks standard OAuth2 — use the Authorization Code with PKCE or Device Authorization grant instead of client credentials. Kortix runs the full lifecycle: discovery, authorization redirect (or device pairing), token exchange, refresh, and revocation.

Declare the direct connector and pick a grant

In the Custom connector form, select OAuth 2.0 under Auth, then choose a Grant: Client Credentials (server-to-server, covered above), Authorization Code with PKCE, or Device Authorization.

Enter the OAuth2 application configuration

Enter the Token URL, Client ID, and Scopes. For Authorization Code you also provide an Authorization URL; for Device Authorization a Device Authorization URL.

A Discovery URL (RFC 8414 or OpenID metadata) can fill the endpoint URLs for you — paste it and Kortix fetches the authorization, token, device-authorization, and revocation URLs from the metadata.

Pick a token-endpoint authentication method

Method	When to use it
Public client (`none`)	A public/native client with no secret.
Client secret with Basic (`client_secret_basic`)	The standard server-side client secret, sent in the `Authorization` header.
Client secret in body (`client_secret_post`)	Client secret sent in the request body.
Client secret JWT (`client_secret_jwt`)	The client asserts itself with an HS256-signed JWT derived from the shared secret.
Private key JWT (`private_key_jwt`)	Asymmetric assertion — paste a PKCS#8 private key PEM; Kortix signs RS256 client assertions with it. No shared secret crosses the wire.

Authorize and verify

For Authorization Code, Kortix generates a consent URL with a PKCE code challenge — send your user to it; they approve, and Kortix exchanges the code for tokens. For Device Authorization, Kortix returns a verification URL and code the user enters on another device; Kortix polls until they complete it.

Kortix encrypts the tokens and refreshes them before they expire. Revoking the profile blocks the next Executor call.

Connect with an API key

Declare the connector in `kortix.yaml`

connectors:
  - slug: stripe
    name: Stripe API
    provider: openapi
    spec: "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
    auth:
      type: bearer

provider is one of openapi, graphql, postman, http, or mcp. auth.type is bearer, basic, custom, oauth1, or none.

Merge the change request

Merge the change request. Kortix reads the manifest only from the default branch, so the connector does not exist until you merge.

Set the credential

Open the connector on the project's Connectors page and enter the credential value. Kortix stores it encrypted and never writes it to the manifest.

Grant an agent access

An agent cannot use a connected tool until you grant it access. Add the slug to the agent's connectors field in kortix.yaml:

agents:
  kortix:
    connectors: all
  release-bot:
    connectors: [stripe]

Omit connectors on an agent, and it gets none — a v2 manifest denies access by default. Merge the change before it takes effect.

Use it in a session

Inside a session, the agent reaches connectors through the kortix executor CLI, never with raw credentials:

kortix executor connectors
kortix executor call stripe <action> '<json-args>'

connectors lists what the session can call. call runs one action. The Kortix Executor Gateway resolves the credential, checks the agent's grant, runs the call, and audits 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.

Connectors