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

> Create, configure, and manage integrations and their connections.

## Endpoints

| Method   | Path                           | Purpose               |
| -------- | ------------------------------ | --------------------- |
| `POST`   | `/integrations`                | Create integration    |
| `GET`    | `/integrations`                | List integrations     |
| `GET`    | `/integrations/:id`            | Get integration       |
| `PATCH`  | `/integrations/:id`            | Update integration    |
| `DELETE` | `/integrations/:id`            | Archive integration   |
| `POST`   | `/integrations/:id/validate`   | Validate connectivity |
| `GET`    | `/integrations/:id/oauth`      | Get OAuth config      |
| `PUT`    | `/integrations/:id/oauth`      | Replace OAuth config  |
| `DELETE` | `/integrations/:id/oauth`      | Remove OAuth config   |
| `POST`   | `/integrations/:id/connection` | Add user token        |
| `GET`    | `/integrations/:id/connection` | Get connection status |
| `DELETE` | `/integrations/:id/connection` | Revoke connection     |

`id` path params are UUIDs.

## Create integration

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X POST https://api.kontext.security/api/v1/integrations \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "GitHub",
      "url": "https://mcp.github.com/sse",
      "category": "gateway_remote_mcp",
      "authMode": "oauth",
      "oauth": {
        "provider": "github",
        "scopes": ["repo", "read:user"]
      }
    }'
  ```

  ```typescript SDK theme={"system"}
  const { integration } = await client.integrations.create({
    name: "GitHub",
    url: "https://mcp.github.com/sse",
    authMode: "oauth",
    oauth: {
      provider: "github",
      scopes: ["repo", "read:user"],
    },
  });
  ```
</CodeGroup>

### Request body

| Field              | Type     | Required    | Description                                                        |
| ------------------ | -------- | ----------- | ------------------------------------------------------------------ |
| `name`             | `string` | Yes         | Display name                                                       |
| `url`              | `string` | Yes         | MCP endpoint URL of the integration                                |
| `category`         | `string` | No          | `"gateway_remote_mcp"` (default) or `"internal_mcp_credentials"`   |
| `authMode`         | `string` | No          | `"oauth"`, `"user_token"`, `"server_token"`, or `"none"` (default) |
| `oauth`            | `object` | No          | OAuth configuration. Fields: `provider?`, `issuer?`, `scopes?`     |
| `capabilities`     | `object` | No          | Declared capabilities: `{ tools?, resources?, prompts? }`          |
| `credentialSchema` | `object` | No          | Schema for user-provided credentials                               |
| `serverToken`      | `string` | Conditional | Required when `authMode` is `"server_token"`                       |

### Categories

* **`gateway_remote_mcp`** -- A remote MCP integration accessed through the Kontext gateway. Kontext proxies requests and handles auth.
* **`internal_mcp_credentials`** -- A credential-only integration. Kontext stores and brokers credentials but does not proxy MCP traffic.

### Auth modes

| Mode           | Description                                                        |
| -------------- | ------------------------------------------------------------------ |
| `oauth`        | Users authenticate via OAuth. Kontext manages the token lifecycle. |
| `user_token`   | Users provide a personal access token or API key manually.         |
| `server_token` | A single shared token configured at the organization level.        |
| `none`         | No authentication required.                                        |

## List integrations

<CodeGroup>
  ```bash curl theme={"system"}
  curl "https://api.kontext.security/api/v1/integrations?limit=50" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { items, nextCursor } = await client.integrations.list({ limit: 50 });
  ```
</CodeGroup>

Returns a paginated list of all integrations in the organization.

Query parameters: `limit`, `cursor`, and optional `name` substring filter.

## Get integration

<CodeGroup>
  ```bash curl theme={"system"}
  curl https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111 \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { integration } = await client.integrations.get(
    "11111111-1111-4111-8111-111111111111",
  );
  ```
</CodeGroup>

### Response fields

Response shape: `{ "integration": { ... } }`

| Field                   | Type      | Description                                                  |
| ----------------------- | --------- | ------------------------------------------------------------ |
| `id`                    | `string`  | Integration ID                                               |
| `name`                  | `string`  | Display name                                                 |
| `url`                   | `string`  | Base URL                                                     |
| `category`              | `string`  | `"gateway_remote_mcp"` or `"internal_mcp_credentials"`       |
| `authMode`              | `string`  | Authentication mode                                          |
| `oauth`                 | `object?` | OAuth configuration (if applicable)                          |
| `capabilities`          | `object?` | Declared capabilities                                        |
| `credentialSchema`      | `object?` | Schema for user credentials                                  |
| `serverTokenConfigured` | `boolean` | Whether a server token is set                                |
| `validationStatus`      | `string`  | Last validation result (`"pending"`, `"valid"`, `"invalid"`) |
| `validationMessage`     | `string?` | Human-readable validation message                            |
| `lastValidatedAt`       | `string?` | ISO 8601 timestamp of last validation                        |
| `userConnection`        | `object?` | Current user's connection status                             |
| `createdAt`             | `string`  | ISO 8601 timestamp                                           |
| `updatedAt`             | `string`  | ISO 8601 timestamp                                           |

## Update integration

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X PATCH https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "name": "GitHub Enterprise" }'
  ```

  ```typescript SDK theme={"system"}
  const { integration } = await client.integrations.update(
    "11111111-1111-4111-8111-111111111111",
    {
      name: "GitHub Enterprise",
    },
  );
  ```
</CodeGroup>

Partial update. Send only the fields you want to change.

## Archive integration

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X DELETE https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111 \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  await client.integrations.archive("11111111-1111-4111-8111-111111111111");
  ```
</CodeGroup>

Archives the integration. It will no longer be available for new connections, but existing data is preserved.

## Validate connectivity

<CodeGroup>
  ```bash curl theme={"system"}
  curl -X POST https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/validate \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```typescript SDK theme={"system"}
  const { status, message } = await client.integrations.validate(
    "11111111-1111-4111-8111-111111111111",
  );
  console.log(status); // "pending" | "valid" | "invalid"
  ```
</CodeGroup>

Tests whether Kontext can reach the integration's URL and authenticate. Updates the `validationStatus`, `validationMessage`, and `lastValidatedAt` fields on the integration.

## Get OAuth config

```bash theme={"system"}
curl https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/oauth \
  -H "Authorization: Bearer $TOKEN"
```

Returns the OAuth configuration for the integration. Only available when `authMode` is `"oauth"`.

### Response fields

Response shape: `{ "oauth": { ... } }`

| Field      | Type       | Description               |
| ---------- | ---------- | ------------------------- |
| `provider` | `string`   | OAuth provider identifier |
| `issuer`   | `string`   | Token issuer URL          |
| `scopes`   | `string[]` | Requested OAuth scopes    |

## Replace OAuth config

```bash theme={"system"}
curl -X PUT https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/oauth \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "scopes": ["repo"]
  }'
```

Full replacement -- you must include all OAuth fields. Existing user connections may need to re-authenticate.

## Remove OAuth config

```bash theme={"system"}
curl -X DELETE https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/oauth \
  -H "Authorization: Bearer $TOKEN"
```

Removes the OAuth configuration. You need to set a different `authMode` before removing OAuth, or the integration will have no auth.

## Add user token

```bash theme={"system"}
curl -X POST https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/connection \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "token": "ghp_xxxxxxxxxxxx" }'
```

Stores a personal access token or API key for the current user on this integration. Used when `authMode` is `"user_token"`.

## Get connection status

```bash theme={"system"}
curl https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/connection \
  -H "Authorization: Bearer $TOKEN"
```

Returns the current user's connection status for this integration.

### Response fields

Response shape: `{ "connection": { ... } }`

| Field         | Type      | Description                       |
| ------------- | --------- | --------------------------------- |
| `connected`   | `boolean` | Whether a credential is stored    |
| `status`      | `string`  | `"connected"` or `"disconnected"` |
| `expiresAt`   | `string?` | ISO 8601 expiry timestamp         |
| `displayName` | `string?` | Display name from the provider    |

## Revoke connection

```bash theme={"system"}
curl -X DELETE https://api.kontext.security/api/v1/integrations/11111111-1111-4111-8111-111111111111/connection \
  -H "Authorization: Bearer $TOKEN"
```

Removes the current user's stored credential for this integration. For OAuth connections, this also revokes the token with the upstream provider when possible.

<Note>
  The OAuth config, connection, and revoke endpoints are REST-only. Use the Management SDK for the core CRUD operations (create, list, get, update, archive, validate).
</Note>