Authentication & Identity

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
Build an MCP server that requests credentials inside tool handlers	Credential exchange via `kontext.require()`	Server SDK
Manage infrastructure (create apps, configure integrations, set policies)	Client Credentials	Management SDK 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

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

Step 3: Exchange code for tokens

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:

{
  "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 for details.

Refreshing tokens

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():

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:

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

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:

{
  "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

Quickstart

See these flows in action with a working example

Server SDK: Credentials

Exchange user tokens for integration credentials

Client SDK

Handle auth flows, tool execution, and storage

Errors

Handle auth errors, connection errors, and policy denials

​Which flow do I need?

​How Kontext relates to your IdP

​Applications: Authorization Code + PKCE

​Step 1: Redirect to authorization

​Step 2: User grants consent

​Step 3: Exchange code for tokens

​Step 4: Use access token

​Refreshing tokens

​Server-side credential exchange

​Service accounts: Client Credentials

​What’s next