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

# Authentication & Identity

> How agents and users prove who they are. Two OAuth2 flows, two SDK surfaces, and how they connect to your existing identity provider.

Kontext uses OAuth2 for all authentication. There are two flows for two different contexts, and two SDK surfaces that map to them.

## Which flow do I need?

| I want to...                                                                    | Flow                                        | SDK                                            |
| ------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------- |
| Build an app where users connect accounts and agents call tools on their behalf | Authorization Code + PKCE                   | [Client SDK](/client/overview)                 |
| Build an MCP server that requests credentials inside tool handlers              | Credential exchange via `kontext.require()` | [Server SDK](/server/overview)                 |
| Manage infrastructure (create apps, configure integrations, set policies)       | Client Credentials                          | [Management SDK](/sdks/management) or REST API |

Most applications use **both** the Client SDK (for the user-facing auth flow) and the Server SDK (for credential exchange inside tool handlers).

## How Kontext relates to your IdP

Kontext does not replace your identity provider for humans. Your users keep signing in through Okta, Google, Azure AD, or whatever IdP you use today.

```
User authenticates → Your IdP (Okta, Google, Azure AD)
Application authenticates → Kontext (the IdP for agents)
Integration credentials → Issued by the integration (GitHub, Slack, etc.)
```

Kontext is the identity provider for **applications**. It issues each application a verifiable identity (Client ID), manages the OAuth consent flow between users and applications, and brokers credentials from integrations at runtime.

## Applications: Authorization Code + PKCE

When your application needs to act on behalf of a user, it uses the standard OAuth2 authorization code flow with PKCE.

### Step 1: Redirect to authorization

```
https://api.kontext.security/oauth2/authorize?
  client_id=app_xyz
  &response_type=code
  &redirect_uri=http://localhost:3000/callback
  &code_challenge=BASE64_CHALLENGE
  &code_challenge_method=S256
  &scope=mcp:invoke
```

### Step 2: User grants consent

The user sees what permissions are being requested and approves. One approval per session.

### Step 3: Exchange code for tokens

```bash theme={"system"}
curl -X POST https://api.kontext.security/oauth2/token \
  -d grant_type=authorization_code \
  -d client_id=app_xyz \
  -d code=$AUTH_CODE \
  -d redirect_uri=http://localhost:3000/callback \
  -d code_verifier=$CODE_VERIFIER
```

**Response:**

```json theme={"system"}
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Step 4: Use access token

Use the access token to call MCP tools via `POST /mcp`, or pass it to `kontext.require()` on your server to exchange it for integration credentials.

The Client SDK handles this entire flow automatically. See the [Client SDK](/client/overview) for details.

### Refreshing tokens

```bash theme={"system"}
curl -X POST https://api.kontext.security/oauth2/token \
  -d grant_type=refresh_token \
  -d client_id=app_xyz \
  -d refresh_token=$REFRESH_TOKEN
```

## Server-side credential exchange

Once your application has a user's access token (from the PKCE flow above), your server exchanges it for integration-specific credentials using `kontext.require()`:

```typescript theme={"system"}
const github = await kontext.require("github", authInfo.token);
// github.authorization → "Bearer ghp_..."
```

This is not a third OAuth flow. It's a credential exchange. Kontext validates the user's token, checks policy, and returns a short-lived credential from the user's existing connection to that integration.

Confidential servers can also exchange against an external end-user subject when they already know that stable ID:

```typescript theme={"system"}
const github = await kontext.require("github", {
  userId: "partner-user-123",
});
```

In that mode, Kontext validates the configured external identity mapping and returns the same short-lived integration credential shape.

See [Server SDK: Credentials](/server/credentials) for the full API.

## Service accounts: Client Credentials

Service accounts authenticate using OAuth2 client credentials. This is a machine-to-machine flow with no user interaction.

Use this flow when your backend needs to manage infrastructure: create applications, configure integrations, set policies.

```bash theme={"system"}
curl -X POST https://api.kontext.security/oauth2/token \
  -d grant_type=client_credentials \
  -d client_id=$SERVICE_ACCOUNT_ID \
  -d client_secret=$SERVICE_ACCOUNT_SECRET
```

**Response:**

```json theme={"system"}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Use this token for Management API requests (`/api/v1/*`). Service accounts cannot invoke tools or access integration credentials. They are for infrastructure management only.

## What's next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    See these flows in action with a working example
  </Card>

  <Card title="Server SDK: Credentials" icon="server" href="/server/credentials">
    Exchange user tokens for integration credentials
  </Card>

  <Card title="Client SDK" icon="desktop" href="/client/overview">
    Handle auth flows, tool execution, and storage
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Handle auth errors, connection errors, and policy denials
  </Card>
</CardGroup>