> ## 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.

# How Kontext Works

> Kontext is the control plane between your agents and the integrations they access. It verifies identity, enforces policy, brokers credentials, and logs every action.

Kontext sits between your applications and the integrations they access. It verifies agent identity, enforces policy, injects short-lived credentials, and logs every action.

```
Your App → Kontext (control plane) → Integration (GitHub, Slack, Linear, ...)
```

Kontext is **not** an identity provider for humans. Your users keep authenticating through your existing IdP (Okta, Google, Azure AD). Kontext is the identity provider for your **applications**: it gives each one a verifiable identity and manages the credentials they need at runtime.

## Control plane vs data plane

The **control plane** is Kontext's hosted service. It manages identity, policy, and credential lifecycle. It decides whether a request is allowed and which credentials to issue.

The **data plane** is where tool execution happens. Depending on how you set up your integrations, this is either:

* **Gateway mode**: Kontext proxies requests to remote MCP servers, injecting credentials automatically
* **Credential-only mode**: Kontext brokers credentials, but your server makes the API calls directly

## Identity structure

```
Organization
 ├── Users       (identity from your existing SSO)
 └── Applications (identity from Kontext)
```

## Access structure

```
User → Connection → Integration
Application → Capability → Integration (using User's Connection)
Policy → Org Layer + User Layer + Application Layer
```

## Core objects

<AccordionGroup>
  <Accordion title="Organization" icon="building">
    The top-level tenant. Organizations provide isolation: users, applications, connections, and policies in one organization cannot access or affect another.

    Organizations typically map to a company, a team, or an environment (dev, staging, prod). Organization identity often comes from your enterprise directory via SSO.
  </Accordion>

  <Accordion title="User" icon="user">
    Humans who delegate to applications. Key characteristics:

    * Identity comes from your external SSO (Okta, Google, Azure AD)
    * Users establish Connections to Integrations via OAuth
    * Users set policies governing what their applications can do
    * Users appear in the Audit Trail as the delegating principal
    * One user can have connections to multiple integrations
  </Accordion>

  <Accordion title="Application (Agent)" icon="robot">
    Non-human actors (AI assistants, bots, automations) that act on behalf of users. Key characteristics:

    * Identity is issued by Kontext (Kontext is the IdP for applications)
    * Each application has a unique Client ID
    * Applications authenticate users via OAuth to receive access tokens
    * Applications invoke Capabilities on Integrations using their user's Connections
    * One application can access multiple integrations (subject to policy)
  </Accordion>

  <Accordion title="Integration" icon="plug">
    External services that applications access: GitHub, Slack, Stripe, or any API. Key characteristics:

    * Integrations have their own authorization servers that issue OAuth tokens
    * Kontext does not issue tokens for integrations. It brokers tokens issued by the integration's auth server
    * Integrations expose Capabilities that can be individually controlled by policy
    * See [Integrations](/concepts/integrations) for auth modes and connection lifecycle
  </Accordion>

  <Accordion title="Capability" icon="bolt">
    Specific operations on an integration. The atomic unit of access control. Key characteristics:

    * Policies can allow or deny at integration level (all capabilities) or capability level (specific operations)
    * Examples: `github:create_issue`, `slack:send_message`, `db:query`
    * Capabilities are discovered from MCP server tool definitions
    * Each capability invocation is logged to the Audit Trail
  </Accordion>

  <Accordion title="Connection" icon="link">
    A user's authenticated link to an integration. Key characteristics:

    * Created when a user completes an OAuth flow or provides an API key
    * The credential is issued by the integration's auth server, not Kontext
    * Kontext stores the credential securely and injects it into application requests
    * Connections can expire or be revoked
    * One user can have one connection per integration
    * Applications use their user's connections (delegated access)
  </Accordion>

  <Accordion title="Policy" icon="shield">
    Rules that allow or deny access across three layers.

    * All three layers (org, user, application) must allow for access to be granted
    * Policies can target integrations (all capabilities) or specific capabilities
    * Explicit deny overrides allow at the same level
  </Accordion>

  <Accordion title="Audit Trail" icon="scroll">
    Immutable log of every capability invocation. Each entry records:

    * Which application made the request
    * Which user the application was acting on behalf of
    * Which capability was invoked on which integration
    * Timestamp, success/failure, and policy evaluation details
  </Accordion>
</AccordionGroup>

## The 3-layer authorization model

Access requires permission at all three layers:

| Layer           | Set by                              | Example                                                  |
| --------------- | ----------------------------------- | -------------------------------------------------------- |
| **Org**         | Admins                              | "Engineering org can use GitHub and Linear"              |
| **User**        | Users (or inherited from SSO roles) | "My applications can create issues but not delete repos" |
| **Application** | Per-application by owner or admin   | "PR-Bot can only access `acme/frontend`"                 |

All three layers must allow. Any explicit deny at any layer blocks the request, and the SDK throws `kontext_policy_denied`.

## Putting it together

> PR-Bot acts on behalf of Alice (authenticated via Acme Corp SSO) and invokes `github:create_issue` on GitHub. Access is authorized by Org Policy (Engineering can use GitHub), User Policy (Alice allows issue creation), and Application Policy (PR-Bot can access acme/frontend). It uses Alice's GitHub Connection, and the action is logged to the Audit Trail.

## What's next

<CardGroup cols={2}>
  <Card title="Authentication & Identity" icon="key" href="/concepts/authentication">
    How agents and users prove who they are
  </Card>

  <Card title="Integrations" icon="plug" href="/concepts/integrations">
    How Kontext connects to external services
  </Card>

  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    Build your first integration in under five minutes
  </Card>
</CardGroup>