> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Connections

> View connected agents, manage datasets, and share data across your workspace

To connect an agent to your workspace, open the **Integrations** page under **CONNECT** in the sidebar (route `/integrations`). It walks you through the connect flow for each supported framework. See [Integrations](/cognee-cloud/ui/integrations) for the available options and [Sessions](/cognee-cloud/ui/sessions) to review agent activity.

This page covers the connection concepts that apply once an agent is connected: its identity, status, and how to share datasets with it.

## Connected agents

Each agent user connected to your tenant has:

* **Agent type** — The framework or integration name (e.g., LangGraph, CrewAI).
* **Status** — `LIVE`, `INACTIVE`, or `NEVER_CONNECTED`. Status is computed from the agent's most recent activity, not from the presence of an API key.
  * `LIVE` — the agent has produced activity (data added, data accessed, or a search query) within the last 30 minutes.
  * `INACTIVE` — the agent has activity on record, but the most recent event is older than 30 minutes.
  * `NEVER_CONNECTED` — the agent user exists (and may even have an API key) but has no recorded activity yet.
* **Datasets** — Number of datasets the agent has access to.
* **Last active** — Timestamp of the agent's most recent activity, derived from the latest data ingestion, data access, or search query. Empty for agents in `NEVER_CONNECTED` state.

### Connection identity

Each connection is identified by an `agent_session_name` chosen by the agent. The server combines that name with the authenticated user's ID to derive the underlying connection ID, so the same `agent_session_name` always resolves to the same connection for a given user. The connection API response includes this `agent_session_name` so clients can match rows and details back to the session name they registered.

To inspect connections for the currently authenticated user without knowing the agent ID, call **`GET /agents/connections/me`** (optionally filtered by `?agent_session_name=<name>`). See the [Cloud SDK](/cognee-cloud/connections/cloud-sdk) reference for request/response examples.

### Per-plugin agent identities

Instead of sharing one tenant API key across every plugin, a supported plugin can be provisioned its own agent sub-user and its own labeled API key. Each plugin then shows up as a distinct connection, and its keys can be rotated or revoked without touching the others.

These plugin keys are accepted; any other value returns `404`:

| Plugin key    | Label       |
| ------------- | ----------- |
| `claude-code` | Claude Code |
| `codex`       | Codex       |
| `opencode`    | OpenCode    |
| `openclaw`    | Openclaw    |
| `mcp`         | MCP         |
| `api`         | API/SDK     |

#### Provision an identity

```bash theme={null}
curl -X POST https://your-tenant.aws.cognee.ai/api/v1/integrations/plugins/claude-code/provision \
  -H "X-Api-Key: <your-user-api-key>"
```

```json theme={null}
{
  "pluginKey": "claude-code",
  "agentId": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "apiKey": "<the-plugin-api-key>",
  "created": true
}
```

The call is authenticated and idempotent as a get-or-create:

* The first call creates the agent sub-user for this user and plugin and returns `created: true`.
* Every later call returns the **same** `agentId` with `created: false` and a **rotated** key — minting a new key revokes all of the plugin agent's previous keys. Re-provisioning is the rotation flow.
* `apiKey` is returned once and cannot be retrieved again. Store it before you close the response.
* An unknown plugin key returns `404`. A `409` means an agent for that plugin already exists but could not be resolved as one of your agents.

Provisioning also registers the plugin in the agent-connection registry, under the parent account's tenant, with the connection name `plugin:<plugin_key>` and a connection type of `claude_code`, `opencode`, `mcp`, or `api` (other plugin keys register as a generic `sdk` connection). Because registration happens at provision time rather than on first traffic, the plugin appears in the connections list immediately, in `NEVER_CONNECTED` state until it produces its first activity.

**`GET /api/v1/integrations/status`** returns the current state of every known plugin (`key`, `connected`, `agentId`, `provisionedAt`, `lastActiveAt`, `sessionCount`, `source`) alongside OAuth integration status.

#### Disconnect a plugin

```bash theme={null}
curl -X DELETE https://your-tenant.aws.cognee.ai/api/v1/integrations/plugins/claude-code \
  -H "X-Api-Key: <your-user-api-key>"
```

```json theme={null}
{ "disconnected": true }
```

This revokes every API key held by the plugin agent and deactivates its connection. The agent user and everything it wrote are kept — disconnecting is not deleting. The response is `{"disconnected": false}` when the plugin was never provisioned.

Re-provisioning later revives the same identity with a fresh key. To remove the agent entirely, use **`DELETE /api/v1/agents/{agent_id}`**.

### Share a dataset with an agent

You can give a connected agent read access to a dataset you own. This grants access via the [dataset permissions](/cognee-cloud/functionality/permissions-and-access-control#dataset-permissions) endpoint, after which the dataset appears in the agent's dataset list.

<Info>
  To connect a new agent, open the [Integrations](/cognee-cloud/ui/integrations) page under **CONNECT**.
</Info>