# Glean

Connect your Glean instance to Capsule Security to discover and monitor the AI agents built and running in Glean.

## Overview

This integration reads your Glean agent inventory through Glean's Agents API, and each agent's owner through Glean's Insights API:

- **Agents** - Every agent in your Glean instance (name, description, and capabilities), surfaced in **Inventory**
- **Agent owners** - The person who created each agent, surfaced as the agent's owner in **Inventory**
- **Agent tools** - The tools each agent can invoke, with the authentication and write-action type behind each one
- **Agent input and output schemas** - The shapes each agent declares, kept on the agent's details


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

## Prerequisites

Before you begin, ensure you have:

- An active **Glean** instance
- **Admin** access in Glean, required to create a Client API token
- A **Capsule Security** account with admin access


> **Note:** The token must carry the **AGENTS** scope, plus the **INSIGHTS** scope for owner attribution. A token created with **GLOBAL** permissions can only be created by a Glean **Super Admin** and requires an act-as email (the user the token acts on behalf of).


## Step 1: Create a Client API token

Create a Client API token in the Glean admin console. This is the credential Capsule uses to read your agent inventory.

### Steps

1. Go to your Glean admin console and open **Platform - API Tokens** (or visit [app.glean.com/admin/platform/tokenManagement](https://app.glean.com/admin/platform/tokenManagement))
2. Create a new **Client API token** with a descriptive name (e.g., "Capsule Security Integration")
3. Grant the **AGENTS** scope so Capsule can list agents and read their tools and schemas, and the **INSIGHTS** scope so Capsule can attribute each agent to its owner
Scopes cannot be changed after a token is created. A token with only **AGENTS** still syncs the agent inventory, but agents arrive without an owner - to add owners later, create a new token with both scopes and reconnect.
4. Choose the token's permissions:
  - **USER** - the token acts as the user who created it; no extra configuration needed
  - **GLOBAL** - requires a **Super Admin** to create, and Capsule needs an **act-as email** of a permitted user (entered in Step 3)
5. **Important:** Copy and save the token immediately - it is shown only once


### Security notes

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


## Step 2: Find your instance name

Capsule connects to your Glean backend domain, which is derived from your instance name.

### Steps

1. Your instance name is the subdomain of your Glean backend domain - for example, `acme` for `acme-be.glean.com`
2. If you are unsure, your Glean admin can find it in the Glean setup pages; pasting the full backend URL into Capsule also works


### Example instance names

```
acme
https://acme-be.glean.com
```

## Step 3: Configure the Integration in Capsule

Once you have your API token and instance name, set up the integration in the portal.

### Steps

1. Log in to the **Capsule Security** portal
2. Click **Integrations** in the left sidebar
3. Find the **Glean** card and click **Set up Integration**
4. The card displays a 3-step wizard. Step 1 links to the Glean token management page; Step 3 collects your credentials:
  - **Instance name** - the subdomain from Step 2 (e.g., `acme`), or the full backend URL
  - **API token** - paste the Client API token from Step 1
  - **Act-as email (optional)** - required only for GLOBAL tokens; the email of a user the token may act as
5. Capsule validates the credentials live as you type. When the required fields are valid you'll see **Connection successful**
6. Click **Save**


### After setup

- Capsule validates the credentials and creates a **Glean** environment scoped to your instance
- 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

| Glean source | Appears in Capsule as |
|  --- | --- |
| Agents (name, description, capabilities) | **Agents** in Inventory |
| Agent owner (the agent's creator) | **Owner** on the agent |
| Agent tools (from the agent schemas) | **Tools** on the agent |
| Agent input and output schemas | Metadata on the agent's details |


Each sync is a full snapshot of the inventory - agents removed in Glean are removed from Capsule on the next sync.

Glean reports an agent's owner only for agents that have been run in the past year, so an agent that has never been used arrives without one.

## Troubleshooting

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

| Message | Cause | Fix |
|  --- | --- | --- |
| **Instance name is required** | The instance name field is empty | Enter the instance name from Step 2 |
| **API token is required** | The token field is empty | Paste the Client API token from Step 1 |
| **Enter the instance name (e.g. acme) or the full https URL** | The value isn't a valid instance name or URL | Use the plain subdomain (e.g. `acme`) or the full `https://acme-be.glean.com` URL |
| **API token invalid or revoked** | The token is wrong, deleted, or revoked (`401`) | Create a fresh Client API token and reconnect |
| **Token lacks the AGENTS scope, or the act-as email is not permitted for this token** | The token is missing the AGENTS scope, or a GLOBAL token's act-as email is missing or not allowed (`403`) | Recreate the token with the AGENTS scope; for GLOBAL tokens, enter a permitted act-as email |
| **Glean instance not found. Check the instance name** | The instance name doesn't resolve to a Glean backend (`404` or DNS failure) | Confirm the subdomain of your Glean backend domain (e.g. `acme` for `acme-be.glean.com`) |


Use the **retry** button next to the act-as email field to re-run the connection test after correcting a value.

## How It Works

Capsule calls three endpoints on `https://<instance>-be.glean.com`, authenticating with a `Bearer` token. For GLOBAL tokens, Capsule sends the configured act-as email in the `X-Glean-ActAs` header.

| Endpoint | Purpose | Scope |
|  --- | --- | --- |
| `/api/agents/search` | The agent inventory snapshot | AGENTS |
| `/api/agents/{agent_id}/schemas` | Each agent's tools and input/output schemas | AGENTS |
| `/rest/api/v1/insights` | Agent owner attribution | INSIGHTS |


The schemas endpoint is per-agent, so Capsule requests it once per discovered agent, in small waves. An agent deleted between the inventory snapshot and its schemas request is skipped rather than failing the sync.

Owners are not part of the Agents API. To attribute them, Capsule calls the Insights API at `https://<instance>-be.glean.com/rest/api/v1/insights` for the agents it just discovered. If the token lacks the **INSIGHTS** scope, Capsule logs the rejection, skips owner attribution, and still records the agent inventory.

Capsule honors `Retry-After` on `429`, retries 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 instance, and is used only to read the endpoints above.

## Support

For help with this integration:

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


## References

- [Glean Agents API](https://developers.glean.com/agents/overview)
- [Get agent schemas](https://developers.glean.com/api/platform-api/platform-agents-get-schemas) - the tools and input/output schemas Capsule reads
- [Glean Insights API](https://developers.glean.com/api/client-api/insights/overview) - the source of agent owner attribution
- [Client API authentication](https://developers.glean.com/api-info/client/authentication/overview) - token types, scopes, and act-as