# Langdock

Connect your Langdock workspace to Capsule Security to inventory the agents your teams build there, along with the models, tools, and knowledge sources they use, who owns them, and how heavily they are used.

## Overview

This integration reads your workspace through two Langdock APIs:

- **Usage Export API** - enumerates every agent and every user in the workspace, together with usage counts
- **Agents API** - enriches each discovered agent with its model, capabilities, actions, and knowledge sources


The integration is **read-only** - it never creates, updates, or deletes anything in Langdock.

Langdock's Agents API has no list endpoint, and `GET /agent/v1/get` only answers for agents that were explicitly shared with your API key. Discovery therefore runs off the admin Usage Export, which covers the whole workspace. This is why the key needs both scopes: with `AGENT_API` alone, Capsule sees only the handful of agents someone shared with the key, not your inventory.

## Prerequisites

Before you begin, ensure you have:

- A **Langdock** workspace on a plan that includes API access
- **Admin** access in Langdock, required to create an API key with the Usage Export scope
- A **Capsule Security** account with admin access


## Step 1: Create an API key with both scopes

1. Sign in to [app.langdock.com](https://app.langdock.com) as a workspace admin
2. Open **Settings** and go to the **API keys** section
3. Create a key and give it a descriptive name (for example, "Capsule Security Integration")
4. Grant **both** scopes:
  - `USAGE_EXPORT_API` - lets Capsule enumerate all agents and users in the workspace
  - `AGENT_API` - lets Capsule read each agent's model, capabilities, actions, and knowledge sources
5. Copy the key immediately - Langdock shows it only once


> **Note:** If your admin will only issue `AGENT_API`, the connection test fails with *"API key is missing the USAGE_EXPORT_API scope."* Capsule can technically operate on that key alone, but coverage collapses to the agents individually shared with it, so the inventory will be incomplete.


### Security notes

- Store the key in a password manager or secret store; never share it in email, chat, or source control
- To rotate it, create a new key, reconnect the integration in Capsule, then delete the old key in Langdock


## Step 2: Note your region

Langdock hosts workspaces in the **EU** or the **US**. Capsule keeps one environment per region, so pick the one your workspace runs in. If your organization runs both, connect each one separately with its own key.

## Step 3: Configure the integration in Capsule

1. Log in to the **Capsule Security** portal
2. Click **Integrations** in the left sidebar
3. Find the **Langdock** card and click **Set up Integration**
4. Paste the **API key** from Step 1 and select your **Region**
5. Capsule validates the key live as you type. When both fields are valid you'll see **Connection successful**
6. Click **Save**


### After setup

- Capsule creates a **Langdock** environment scoped to the region you selected
- Your API key is encrypted and stored in Capsule's secret store - it is never displayed again
- The first sync discovers every agent and user in the workspace; later syncs refresh the inventory and pull new usage incrementally


## What Capsule ingests

| Langdock source | Appears in Capsule as |
|  --- | --- |
| Agents export | **Agents** in the inventory |
| `GET /agent/v1/get` | The agent's **model**, **tools** (web search, data analyst, image generation, canvas, actions), and **data sources** (knowledge folders, vector databases, attachments) |
| Agent actions backed by an MCP endpoint | **MCP servers** in the supply-chain inventory |
| Users export | **Identities**, and the **owner** on each agent |
| Per-agent usage counts | **Activity** on the agent |


Agent and user discovery reads the full retained history on every run, so an agent that sat idle is refreshed rather than removed. Only usage is fetched incrementally, checkpointed per environment so runs resume where they left off.

An agent that was never shared with your API key still appears in the inventory from its export row; it simply carries less detail, because `GET /agent/v1/get` refuses to answer for it. Capsule records that on the agent and continues the run.

## Troubleshooting

If the connection test fails, the portal shows a specific message:

| Message | Cause | Fix |
|  --- | --- | --- |
| **API key is required** | The key field is empty | Paste the key from Step 1 |
| **Region is required** | No region is selected | Select the region your workspace runs in |
| **API key invalid or revoked** | The key is wrong, deleted, or revoked (`401`) | Create a fresh key in Langdock and reconnect |
| **API key is missing the AGENT_API scope** | The key cannot read agent detail (`403`) | Recreate the key with both scopes |
| **API key is missing the USAGE_EXPORT_API scope** | The key cannot enumerate the workspace (`403`) | Recreate the key with both scopes; this scope is admin-only |


Use the **retry** button next to the API key field to re-run the connection test after correcting a value.

## How It Works

Capsule calls Langdock at `https://api.langdock.com`, authenticating with a bearer token. It reads:

- `POST /export/agents` and `POST /export/users` - a date range and timezone in, a CSV download URL out
- `GET /agent/v1/get` - per-agent detail for each id found in the agents export
- `GET /agent/v1/models` - used by the connection test to confirm the `AGENT_API` scope


Your API key is held in an encrypted secret store, scoped to your tenant and region, and is used only to read the endpoints above.

## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your tenant ID, your Langdock region, and any error message shown in the connection test


## References

- [Langdock developer documentation](https://docs.langdock.com/en/developer/agents-api/agent-get)