# Agent Access Overview

> Source: https://docs.trailspark.ai/docs/agent-access-overview

## Overview

**Agent Access** lets an AI agent — such as Claude Desktop, Claude Code, or Cursor — read and manage your TrailSpark workspace on your behalf. An agent can look up leads and accounts, review evaluations, adjust your ICP rules, correct data, and more — always limited to the permissions you choose.

You'll find it under **Settings** > **Agent Access**. Only organization admins can open this page and manage access.

There are two ways to give an agent access, and they share the same permission model:

- **Agent keys** — a long-lived key you create and paste into an agent's configuration. Best for an agent that runs on its own, without a person signed in.
- **Connected agents** — an agent you link through a sign-in-and-approve flow (OAuth), the same way you'd connect any app to an account. Best for tools like claude.ai that walk a person through connecting.

> [!NOTE]
> Both approaches are scoped to a single workspace and can be revoked at any time. An agent can only ever see and act on the one organization it was granted access to.

## Permissions

Every agent key and connected agent uses the same three permission levels. You pick any combination when you create the key or approve the connection:

| Permission | What it allows |
|---|---|
| **Read** | View leads, evaluations, and workspace configuration |
| **Configure** | Change ICP rules and workspace configuration |
| **Data corrections** | Correct lead and account data |

Grant only what the agent needs. A reporting or analysis agent usually needs just **Read**; an agent that maintains your ICP needs **Configure** as well.

## Account re-evaluation

Re-evaluating accounts is a billable action, so it's controlled separately from the permissions above.

- **Off by default.** No agent can trigger re-evaluation unless you explicitly allow it.
- **Allow it per key or per connection** with the **Allow this key to trigger account re-evaluation (billable)** switch (or the matching switch on the approval screen for a connected agent).
- **Set a daily limit.** When you allow re-evaluation, you also set a **Daily re-evaluation limit** — the maximum number of accounts the agent can re-score in a day. This caps spend even if the agent is very active.

## Choosing between an agent key and a connected agent

| Use an **agent key** when… | Use a **connected agent** when… |
|---|---|
| The agent runs unattended (a script, a background assistant, a server) | A person is connecting a tool like claude.ai and can approve access in a browser |
| You want to paste a credential directly into a config file | You'd rather approve access with a sign-in step and no key to copy |
| You want to name and rotate credentials yourself | You want the agent to request access and you approve or deny it |

Next steps:

- [What Agents Can Do](/docs/what-agents-can-do) — the common use cases (reviewing signals, building ICPs, connecting CRMs, mapping signals) and the permission each needs
- [Managing Agent Keys](/docs/agent-keys) — create, view, and revoke keys
- [Connecting an AI Agent](/docs/connect-an-agent) — link an agent through the approval flow and manage connected agents