Skip to main content
An integration represents an external service your application needs access to — GitHub, Slack, Linear, Stripe, or any API.

​
How integrations work

When you create an integration, you configure two things:
  • Which service it connects to — the provider name or OAuth issuer
  • How users authenticate — OAuth, API key, shared token, or no auth
Kontext then manages the credential lifecycle: storing secrets, refreshing OAuth tokens, and enforcing access policy. Your application never sees or stores long-lived credentials. How your application consumes those credentials at runtime is a separate concern — see Runtime access.

​
Auth modes

Each integration uses one of four authentication modes:
ModeHow users connectWhen to use
oauthUsers authenticate via OAuth. Kontext resolves the OAuth app identity, manages scopes, and handles the full token lifecycle including refresh and revocation. Multiple providers work zero-config.GitHub, Slack, Google, and most SaaS APIs
user_tokenUsers provide a personal access token or API key manually.Services without OAuth, or when users prefer PATs
server_tokenA single shared token configured at the organization level.Internal APIs, shared infrastructure
noneNo authentication required.Public APIs, development/testing

​
Credential management

Kontext manages credentials for all auth modes, not just OAuth.

​
OAuth integrations

For OAuth, Kontext needs to know which OAuth app to use when initiating consent flows. There are two options: Platform-managed (default): The platform operator configures OAuth app credentials for supported providers via environment variables. All integrations for that provider share them. Multiple providers have built-in support — Kontext already knows their OAuth endpoints, default scopes, and required parameters, so adding an integration is zero-config. Integration-specific override: An admin configures a clientId and clientSecret directly on a single integration. That integration uses its own OAuth app; others continue using the platform credentials. Use this when a customer requires OAuth app isolation or different redirect behavior. Kontext resolves credentials top-down: integration-specific first, then platform-managed. If no credentials can be resolved and the provider requires a client secret, the flow is blocked with an actionable error. Each OAuth integration can also specify which scopes to request during consent. For supported providers, the dashboard provides a searchable scope catalog.

​
API key integrations (user_token)

Users provide their own API key or personal access token through the connect page. Kontext encrypts and stores it, then brokers it to authorized applications at runtime. The user manages their own token — Kontext handles storage and access control.

​
Shared token integrations (server_token)

An admin configures a single token at the organization level. All users of that integration share the same credential. Useful for internal APIs or shared infrastructure where per-user auth isn’t needed.

​
Connections

A connection is a user’s authenticated link to an integration. Connections are created when a user completes an OAuth flow or provides an API key.

​
Lifecycle

  1. User connects through the OAuth consent flow or by providing credentials
  2. Kontext stores the credential, encrypted and associated with the user and integration
  3. Applications request access via kontext.require() in tool handlers
  4. Kontext checks policy across org, user, and application layers
  5. Credential is returned, short-lived and scoped to the current request
  6. Connections refresh automatically (Kontext handles OAuth token refresh)
  7. Connection can be revoked by the user, an admin, or programmatically via the API
Each user can have one connection per integration. Applications use their user’s connections (the delegation model). The application never sees or stores the long-lived credential.

​
Connection status

StatusMeaning
connectedCredential is stored and valid
disconnectedNo credential stored, or credential has been revoked
You can check connection status and manage connections via the Integrations API.

​
Runtime access

​
Gateway mode (MCP)

Kontext acts as an MCP proxy. Your application calls tools through the Kontext gateway, and Kontext injects the user’s credential into the request automatically. The application never handles credentials directly. MCP (Model Context Protocol) is a standard for connecting AI models to external tools and data sources. When an integration has an MCP endpoint URL, Kontext can:
  • Discover capabilities: query the MCP server for available tools and their schemas
  • Proxy tool calls: forward execution requests with credentials injected
  • Validate connectivity: test that the endpoint is reachable and responding
You don’t need to build your own MCP server to use Kontext. Many services already provide MCP endpoints.

​
Credential-only mode (token exchange)

Your server requests the user’s credential via the token exchange endpoint (RFC 8693) and calls the external API directly. Use this when you have your own backend, need to make API calls outside of MCP, or want full control over how requests are made. 
// Server-side: exchange for the user's credential
const token = await kontext.require({ integration: "github" });
// Use the token to call the GitHub API directly

​
Capabilities

Capabilities are specific operations an integration exposes. They are the atomic unit of access control. Examples:
  • github:create_issue
  • slack:send_message
  • linear:create_ticket
Capabilities are discovered automatically from MCP server tool definitions when using gateway mode. You can also declare capabilities manually when creating an integration. Policies can allow or deny access at two granularities:
  • Integration level: all capabilities on that integration
  • Capability level: a specific tool on that integration

​
What’s next

Integrations API

Create, configure, and manage integrations via the REST API

Server SDK: Credentials

Exchange user tokens for integration credentials in your tool handlers

How Kontext Works

The full object model and authorization architecture