Overview - Kontext

The KontextManagementClient is the typed management layer for the Kontext identity control plane. Use it to automate applications, integrations, service accounts, sessions, and traces in CI/CD pipelines, admin tooling, or internal automation.

Install

npm install @kontext-dev/js-sdk

Initialize

import { KontextManagementClient } from "@kontext-dev/js-sdk/management";

const client = new KontextManagementClient({
  baseUrl: "https://api.kontext.dev",
  credentials: {
    clientId: "sa_your-service-account",
    clientSecret: "your-secret",
  },
});

The client authenticates using OAuth client credentials. It fetches and caches an access token on the first request and refreshes it automatically when it expires.

Constructor config

Option	Type	Default	Description
`baseUrl`	`string`	—	API base URL. Use `"https://api.kontext.dev"` for production.
`credentials`	`{ clientId, clientSecret }`	—	Service account credentials from the dashboard.
`apiVersion`	`string`	`"v1"`	API version prefix.
`tokenUrl`	`string`	`${baseUrl}/oauth2/token`	OAuth token endpoint. Override for custom auth servers.
`scopes`	`string[]`	`["management:all"]`	OAuth scopes to request.
`audience`	`string`	`${baseUrl}/api/${apiVersion}`	Token audience claim.

Create service account credentials in the Kontext dashboard under Settings > Service Accounts, or programmatically with client.serviceAccounts.create(). Resource IDs used by the Management API are UUIDs. OAuth client IDs are separate (app_<uuid> for applications and sa_<uuid> for service accounts).

Applications

Manage applications registered with your organization.

List applications

const { items, nextCursor } = await client.applications.list({ limit: 10 });

Get an application

const { application } = await client.applications.get(
  "550e8400-e29b-41d4-a716-446655440000",
);

Create an application

const { application, oauth } = await client.applications.create({
  name: "My AI App",
  oauth: { redirectUris: ["http://localhost:3000/callback"] },
});

console.log(oauth.clientSecret); // Save this -- it is only shown once

Update an application

const { application } = await client.applications.update(
  "550e8400-e29b-41d4-a716-446655440000",
  {
    name: "Renamed App",
  },
);

Archive an application

await client.applications.archive("550e8400-e29b-41d4-a716-446655440000");

Rotate client secret

const { oauth } = await client.applications.rotateSecret(
  "550e8400-e29b-41d4-a716-446655440000",
);
console.log(oauth.clientSecret); // Save this -- it is only shown once

Generates a new client secret and returns the full OAuth configuration. The previous secret is revoked immediately.

OAuth configuration

const { oauth: oauthConfig } = await client.applications.getOAuth(
  "550e8400-e29b-41d4-a716-446655440000",
);

await client.applications.updateOAuth(
  "550e8400-e29b-41d4-a716-446655440000",
  {
    redirectUris: ["https://myapp.com/callback"],
  },
);

Manage integrations

Attach or detach integrations from an application. An application can only use tools from its attached integrations.

// List attached integrations
const { integrationIds } = await client.applications.listIntegrations(
  "550e8400-e29b-41d4-a716-446655440000",
);

// Attach a single integration
await client.applications.attachIntegration(
  "550e8400-e29b-41d4-a716-446655440000",
  "11111111-1111-4111-8111-111111111111",
);

// Detach a single integration
await client.applications.detachIntegration(
  "550e8400-e29b-41d4-a716-446655440000",
  "11111111-1111-4111-8111-111111111111",
);

// Replace all integrations at once
await client.applications.setIntegrations(
  "550e8400-e29b-41d4-a716-446655440000",
  {
    integrationIds: [
      "11111111-1111-4111-8111-111111111111",
      "22222222-2222-4222-8222-222222222222",
    ],
  },
);

Method reference

Method	Parameters	Returns
`list(params?)`	`{ limit?, cursor? }`	`{ items: Application[], nextCursor? }`
`get(id)`	`string`	`{ application: Application }`
`create(data)`	`CreateApplicationInput`	`{ application: Application, oauth: ApplicationOAuth }`
`update(id, data)`	`string, UpdateApplicationInput`	`{ application: Application }`
`archive(id)`	`string`	`void`
`rotateSecret(id)`	`string`	`{ oauth: ApplicationOAuth }`
`getOAuth(id)`	`string`	`{ oauth: ApplicationOAuth }`
`updateOAuth(id, data)`	`string, UpdateApplicationOAuthInput`	`{ oauth: ApplicationOAuth }`
`listIntegrations(id)`	`string`	`{ integrationIds: string[] }`
`setIntegrations(id, data)`	`string, { integrationIds: string[] }`	`{ integrationIds: string[] }`
`attachIntegration(appId, integrationId)`	`string, string`	`void`
`detachIntegration(appId, integrationId)`	`string, string`	`void`
`revokeAllAgentSessions(id)`	`string`	`{ success: boolean, disconnectedCount: number }`

Integrations

Manage integrations — the external services your applications connect to.

List integrations

const { items, nextCursor } = await client.integrations.list();

Create an integration

const { integration } = await client.integrations.create({
  name: "GitHub",
  url: "https://github-mcp.example.com/mcp",
  authMode: "oauth",
});

Validate an integration

const { status, message } = await client.integrations.validate(
  "11111111-1111-4111-8111-111111111111",
);

Tests the connection to the integration’s MCP endpoint and returns the result. status is one of "pending", "valid", or "invalid".

Method reference

Method	Parameters	Returns
`list(params?)`	`{ limit?, cursor? }`	`{ items: Integration[], nextCursor? }`
`get(id)`	`string`	`{ integration: Integration }`
`create(data)`	`CreateIntegrationInput`	`{ integration: Integration }`
`update(id, data)`	`string, UpdateIntegrationInput`	`{ integration: Integration }`
`archive(id)`	`string`	`void`
`validate(id)`	`string`	`{ status: "pending" \| "valid" \| "invalid", message? }`

Service accounts

Service accounts provide machine-to-machine credentials for the Management API. Each service account gets a clientId and clientSecret pair.

Create a service account

const { serviceAccount, credentials } = await client.serviceAccounts.create({
  name: "CI Pipeline",
  description: "Used by GitHub Actions",
});

console.log(credentials.clientId);     // "sa_xxx"
console.log(credentials.clientSecret); // Save this -- shown once

Rotate credentials

const { credentials } = await client.serviceAccounts.rotateSecret(
  "33333333-3333-4333-8333-333333333333",
);

The previous secret is revoked immediately.

Revoke a service account

await client.serviceAccounts.revoke("33333333-3333-4333-8333-333333333333");

Method reference

Method	Parameters	Returns
`list(params?)`	`{ limit?, cursor? }`	`{ items: ServiceAccount[], nextCursor: string \| null }`
`get(id)`	`string`	`{ serviceAccount: ServiceAccount }`
`create(data)`	`{ name, description? }`	`{ serviceAccount, credentials: { clientId, clientSecret } }`
`revoke(id)`	`string`	`void`
`rotateSecret(id)`	`string`	`{ credentials: { clientId, clientSecret } }`

Sessions

View and manage active MCP sessions for your applications.

List sessions

const { items } = await client.agentSessions.list(
  "550e8400-e29b-41d4-a716-446655440000",
  { limit: 20 },
);

Get a session

const { session } = await client.agentSessions.get(
  "550e8400-e29b-41d4-a716-446655440000",
  "44444444-4444-4444-8444-444444444444",
);

Revoke all sessions

const { success, disconnectedCount } = await client.agentSessions.revokeAll(
  "550e8400-e29b-41d4-a716-446655440000",
);

Terminates all active sessions for the application. Connected clients will need to re-authenticate.

Method reference

Method	Parameters	Returns
`list(applicationId, params?)`	`string, { limit?, status?, includeInactive? }`	`{ items: AgentSession[] }`
`get(applicationId, sessionId)`	`string, string`	`{ session: AgentSession }`
`revokeAll(applicationId)`	`string`	`{ success: boolean, disconnectedCount: number }`

Traces

Query tool execution traces for observability and debugging.

List traces

const { items } = await client.traces.list({
  userId: "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
  limit: 50,
});

Filter by userId, sessionId, or agentId to narrow results.

Get a trace with events

const { trace, events } = await client.traces.get(
  "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
);

Returns the trace metadata and its full event timeline.

Trace statistics

const { stats } = await client.traces.stats({ period: "7d" });

Method reference

Method	Parameters	Returns
`list(params?)`	`{ limit?, cursor?, offset?, userId?, sessionId?, agentId?, applicationId? }`	`{ items: Trace[], nextCursor? }`
`get(traceId, params?)`	`string, { userId? }?`	`{ trace: Trace, events: TraceEvent[] }`
`stats(params?)`	`{ period?, userId? }`	`{ stats: TraceStats }`

Events

Query trace events directly, without going through a specific trace.

const { items } = await client.events.list({ limit: 100 });

Method reference

Method	Parameters	Returns
`list(params?)`	`{ limit? }`	`{ items: McpEvent[] }`

Token management

The client handles token lifecycle automatically. Two methods are available for manual control.

// Force a token refresh before the next request
await client.refreshToken();

// Clear the cached token (next request will fetch a new one)
client.clearToken();

Use clearToken() when rotating service account credentials — the client picks up the new secret on the next request.

Complete example

Create an application, set up an integration, and attach them together:

import { KontextManagementClient } from "@kontext-dev/js-sdk/management";

const client = new KontextManagementClient({
  baseUrl: "https://api.kontext.dev",
  credentials: {
    clientId: "sa_your-service-account",
    clientSecret: "your-secret",
  },
});

// 1. Create the application
const { application, oauth } = await client.applications.create({
  name: "My AI App",
  oauth: { redirectUris: ["http://localhost:3000/callback"] },
});

console.log("App created:", application.id);
console.log("Client secret:", oauth.clientSecret);

// 2. Create an integration
const { integration } = await client.integrations.create({
  name: "GitHub",
  url: "https://github-mcp.example.com/mcp",
  authMode: "oauth",
});

console.log("Integration created:", integration.id);

// 3. Attach the integration to the application
await client.applications.attachIntegration(application.id, integration.id);

// 4. Verify the setup
const { integrationIds } = await client.applications.listIntegrations(application.id);
console.log("Attached integrations:", integrationIds);

Error handling

The management client throws the same error types as the rest of the SDK. See Errors for the full reference.

import { HttpError, isKontextError } from "@kontext-dev/js-sdk/errors";

try {
  await client.applications.get("00000000-0000-4000-8000-000000000000");
} catch (err) {
  if (err instanceof HttpError) {
    console.log(err.statusCode);       // 404
    console.log(err.message);          // "Application not found"
  }
}

Common cases:

401 — Invalid or expired service account credentials. Check your clientId and clientSecret.
403 — Insufficient permissions. The service account may need additional scopes.
404 — Resource not found. Verify the ID.
429 — Rate limit exceeded. The error includes a retryAfter value in seconds.

Next steps

TypeScript SDK — Overview of all SDK entry points and subpath exports.
Errors — Full error hierarchy, error codes, and handling patterns.

TypeScript SDK

Server SDK

Client SDK

Frameworks

Management SDK

​Install

​Initialize

​Constructor config

​Applications

​List applications

​Get an application

​Create an application

​Update an application

​Archive an application

​Rotate client secret

​OAuth configuration

​Manage integrations

​Method reference

​Integrations

​List integrations

​Create an integration

​Validate an integration

​Method reference

​Service accounts

​Create a service account

​Rotate credentials

​Revoke a service account

​Method reference

​Sessions

​List sessions

​Get a session

​Revoke all sessions

​Method reference

​Traces

​List traces

​Get a trace with events

​Trace statistics

​Method reference

​Events

​Method reference

​Token management

​Complete example

​Error handling

​Next steps

Install

Initialize

Constructor config

Applications

List applications

Get an application

Create an application

Update an application

Archive an application

Rotate client secret

OAuth configuration

Manage integrations

Method reference

Integrations

List integrations

Create an integration

Validate an integration

Method reference

Service accounts

Create a service account

Rotate credentials

Revoke a service account

Method reference

Sessions

List sessions

Get a session

Revoke all sessions

Method reference

Traces

List traces

Get a trace with events

Trace statistics

Method reference

Events

Method reference

Token management

Complete example

Error handling

Next steps