> ## Documentation Index > Fetch the complete documentation index at: https://docs.kontext.security/llms.txt > Use this file to discover all available pages before exploring further. # Integrations > How Kontext connects your applications to external services. Auth modes, OAuth credential management, connection lifecycle, and runtime access. 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](#runtime-access). ## Auth modes Each integration uses one of four authentication modes: | Mode | How users connect | When to use | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `oauth` | Users 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_token` | Users provide a personal access token or API key manually. | Services without OAuth, or when users prefer PATs | | `server_token` | A single shared token configured at the organization level. | Internal APIs, shared infrastructure | | `none` | No 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 | Status | Meaning | | -------------- | ---------------------------------------------------- | | `connected` | Credential is stored and valid | | `disconnected` | No credential stored, or credential has been revoked | You can check connection status and manage connections via the [Integrations API](/api/integrations). ## 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. ```typescript theme={"system"} // 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 Create, configure, and manage integrations via the REST API Exchange user tokens for integration credentials in your tool handlers The full object model and authorization architecture