# monday.com

Connect your monday.com account to Capsule Security to discover and monitor the AI agents running in your work boards.

## Overview

This integration reads your monday.com agent inventory through monday's platform API:

- **Agents** - Every agent in the account (name, role, goal, execution plan, and state), surfaced in **Inventory**
- **Models** - The LLM each agent runs on
- **Skills** - The catalog skills attached to each agent
- **Knowledge** - The boards, docs, and uploaded files each agent can access, surfaced as data sources
- **Triggers** - The events that start an agent run, surfaced as access channels


The integration is **read-only** - it never creates, modifies, activates, or runs agents in monday.com. Each sync takes a full snapshot of the agent inventory, so agents deleted in monday.com disappear from Capsule on the next sync.

> **Note:** monday's agents API is a **pre-release** feature, available only in the `dev` API version. Your account needs early access to it before Capsule can read agents. Signatures and behavior may change until it lands in a dated API version.


## Prerequisites

Before you begin, ensure you have:

- An active **monday.com** account with the agents API enabled
- **Admin** access in monday.com, so the token can see every agent in the account rather than only your own
- A **Capsule Security** account with admin access


## Step 1: Create an API token

monday API tokens are personal - they carry the permissions of the user who created them. Use an admin account so Capsule sees the whole account inventory.

### Steps

1. In monday.com, click your **avatar** in the bottom-left corner
2. Open **Developers**, then **My Access Tokens**
3. Copy the **API v2 Token**
4. **Important:** Store the token immediately - treat it like a password


### Security notes

- Store the token in a password manager or secret store; never share it in email, chat, or source control
- The token inherits its creator's board and doc permissions, so agents owned by other users may be invisible to a non-admin token
- To rotate it, regenerate the token in monday.com, then reconnect the integration in Capsule


## Step 2: Confirm agents API access

The agents API is in early preview and is not enabled for every account.

### Steps

1. Confirm your account has been granted access to the monday agents API
2. If the connection test in Step 3 reports that the token is not permitted to read agents, request access through monday's [early access form](https://developer.monday.com/api-reference/reference/agents)


## Step 3: Configure the Integration in Capsule

### Steps

1. Log in to the **Capsule Security** portal
2. Click **Integrations** in the left sidebar
3. Find the **monday.com** card and click **Set up Integration**
4. Paste the **API token** from Step 1 into Step 3 of the wizard
5. Capsule validates the credential live as you type. When it is valid you'll see **Connection successful**
6. Click **Save**


### After setup

- Capsule resolves your monday account from the token and creates an environment named after it
- Your API token is encrypted and stored in Capsule's secret store - it is never displayed again
- Capsule syncs the agent inventory on a schedule. View agents under **Inventory**


## What Capsule ingests

| monday.com source | Appears in Capsule as |
|  --- | --- |
| Agents (name, role, goal, plan, state) | **Agents** in Inventory |
| Agent model | **Models** |
| Skills attached to an agent | **Skills** |
| Boards and docs granted to an agent as knowledge | **Data sources** |
| Files uploaded as agent knowledge | **Data sources** |
| Active triggers on an agent | **Access channels** |


Personal agents are scoped to their operator; account-level and external agents are visible account-wide. An agent that is not in the `ACTIVE` state is recorded as disabled.

Each sync is a full snapshot of the inventory. If your account holds more agents than a single read returns, Capsule keeps the agents it already knows about rather than removing the ones it could not see.

## Troubleshooting

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

| Message | Cause | Fix |
|  --- | --- | --- |
| **API token is required** | The token field is empty | Paste the API v2 token from Step 1 |
| **API token invalid or revoked** | The token is wrong, expired, or regenerated (`401`) | Copy a fresh token from **Developers - My Access Tokens** and reconnect |
| **The token is valid but not permitted to read agents. Use an admin token on an account with agents API access enabled.** | The account lacks agents API access, or the token's user cannot read agents (`403`) | Request agents API access for the account, and use an admin token |
| **Connection test failed. Please check the API token and try again.** | monday.com rejected the request for another reason | Retry; if it persists, contact support with the tenant ID and the message |


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

## How It Works

Capsule calls monday's GraphQL API at `https://api.monday.com/v2`, sending the API token in the `Authorization` header and pinning `API-Version: dev` because the agents API is not yet part of a dated version.

Per sync, Capsule reads the account's agents and skills catalog, then reads each agent's knowledge and active triggers. It honors `Retry-After` on `429`, retries rate-limit, complexity, and transient `5xx` and network errors with exponential backoff, and never retries `401`/`403`. Your API token is held in an encrypted secret store, scoped to your tenant and monday account, and is used only for the reads above.

## Support

For help with this integration:

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


## References

- [monday.com agents API](https://developer.monday.com/api-reference/reference/agents)
- [monday.com API authentication](https://developer.monday.com/api-reference/docs/authentication)