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

# Let AI Agents Manage Attio CRM Records

> Let agents manage Attio contacts, companies, deals, notes, and tasks. Connect with OAuth or a scoped API key that the gateway keeps out of the agent.

## Overview

Buckle connects AI agents to Attio through OAuth or a scoped API key. Agents can read and manage CRM data such as contacts, companies, deals, lists, notes, and tasks, with credentials injected into requests to the Attio API automatically.

This is useful for agents that enrich records, move deals through a pipeline, or capture notes and tasks without manual CRM data entry.

## What you will set up

* An Attio connection through OAuth, or a scoped API key for tighter control
* Automatic credential injection and token refresh on requests to `api.attio.com`
* Per-agent, per-tool access to CRM data

## How it works

Buckle sits between your agent and Attio as a transparent proxy. When an agent calls the Attio API, the gateway matches the request, injects the stored credential, and forwards it to `api.attio.com`. Your agent never sees the token or API key.

Because the gateway speaks the Attio REST API directly, agents use the same endpoints and request shapes as any Attio client. There is no SDK to install and no Attio-specific code in your agent. You connect Attio once, assign it to an agent, and the agent can read and write CRM data within the permissions you grant.

Buckle also handles the connection lifecycle. For OAuth connections it refreshes expiring access tokens for you. For API key connections it injects your key on every request. In both cases credentials are encrypted at rest and only decrypted inside the gateway at request time.

## Setup

OAuth is the default connection method and requires no setup beyond authorizing Buckle.

**1. Open the app**

Open the Buckle dashboard and navigate to **Settings** > **Apps** > **Attio**.

**2. Authorize**

Click **Connect to Attio**. You'll be redirected to Attio to sign in and authorize Buckle. Review the requested permissions and click **Allow**.

![Buckle connect window for Attio with the Access level choice (Workspace access or Personal access), the Connect to Attio button, and Use an API key instead.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/attio/buckle-connect-attio.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=6d87ae81d1061586afb601fef2e49a67)

The Attio connect window on Buckle Cloud.

**3. Verify**

After authorizing, you'll return to the dashboard. The connection shows as **Connected** with your Attio workspace name.

## Configure

> [accordion] Optional: connect with a scoped API key instead
>
> OAuth works out of the box. If you want tighter control over what an agent can reach, connect Attio with your own API key instead and grant it only the scopes you need, rather than the full OAuth scope set. For example, create a read-only key, or one limited to specific objects.
>
> **1. Create a scoped API key in Attio**
>
> In Attio, create an API key and select only the scopes your agents require. Attio's guide walks through this: [Generating an API key](https://attio.com/help/apps/other-apps/generating-an-api-key).
>
> **2. Connect in Buckle**
>
> In the Buckle dashboard, open **Settings** > **Apps** > **Attio**, choose **Use an API key instead**, and paste your key. Buckle injects it into requests the same way it does an OAuth token.
>
> ![Buckle connect window for Attio with the Connection label and API key fields, the Connect Attio button, and a Back link to OAuth](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/attio-api-key-v2.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=4153a6b1be5179fc08de5f667934f9b2)

## Self-hosted: use your own Attio app

> [!NOTE]
>
> **Skip this section on Buckle Cloud.** It's only for self-hosted Buckle without `ATTIO_CLIENT_ID` and `ATTIO_CLIENT_SECRET` set, or if you want your own company name on Attio's consent screen. The API key option above works on self-hosted with no app at all.

> [accordion] 1. Create the Attio app
>
> Go to the [Attio developer dashboard](https://build.attio.com/) and create an app named `Buckle`. Open its **OAuth** settings.
>
> ![Attio New app dialog with the name Buckle and the slug buckle, and the Create app button.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/attio/01-provider-setup.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=99a2902582b9000f64ff98936aa373d9)
>
> Create the app in Attio's developer dashboard.

> [accordion] 2. Add the scopes
>
> Turn on the scopes your agents need. Buckle can request all of these:
>
> | Scope | Access |
> | - | - |
> | `record_permission`, `object_configuration` | Read-write |
> | `list_entry`, `list_configuration` | Read-write |
> | `note`, `task`, `comment`, `file` | Read-write |
> | `meeting`, `webhook` | Read-write |
> | `user_management`, `call_recording` | Read |

> [accordion] 3. Add the redirect URI
>
> In Buckle, open **Settings** > **Apps** > **Attio** > **Custom credentials** and copy the **Redirect URI**. In Attio, paste it into **Redirect URIs**, and save.
>
> ![Buckle Custom credentials card for Attio with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/attio/buckle-custom-credentials-attio.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=61d67f87c0d6a573cc3eda8183b1ecea)
>
> Copy the Redirect URI from Custom credentials in Buckle.
>
> ![Attio app OAuth tab with OAuth enabled, the Client ID, a hidden Client Secret, and https://buckle.example.com/v1/apps/attio/callback under Redirect URIs.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/attio/02-provider-redirect.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=543c743d77157b5e6bc36306b537693a)
>
> The OAuth tab of your Attio app, with the Buckle Redirect URI.

> [accordion] 4. Connect with your app
>
> In Attio, copy the app's **Client ID** and **Client secret**. Paste both into **Settings** > **Apps** > **Attio** > **Custom credentials**, select **Save credentials**, then **Connect** and allow access in Attio.

## Permissions

OAuth connections request the following scopes. With an API key, you choose the scopes when you create the key in Attio.

| Permission | Access | Description |
| - | - | - |
| Records | Read & write | Contacts, companies, and deals |
| Object configuration | Read & write | Custom objects and attributes |
| List entries | Read & write | Entries in lists |
| List configuration | Read & write | Lists and their columns |
| Notes | Read & write | Notes on records |
| Tasks | Read & write | Tasks and assignments |
| Comments | Read & write | Threads and comments |
| Files | Read & write | Upload and view files |
| Webhooks | Read & write | Manage webhooks |
| User management | Read | View workspace members |
| Meetings | Read & write | View and manage meetings |
| Call recordings | Read | Transcripts and speakers |

## What agents can do

* Search and manage contacts, companies, and deals
* Create and update records, custom objects, and attributes
* Organize lists and list entries
* Add notes, tasks, and comments to records
* Upload and read files attached to records
* Read meeting details and call recording transcripts
* Manage webhooks for real-time updates

## Disconnecting

You can disconnect Attio at any time.

**OAuth connections**

* In Buckle, open **Settings** > **Apps** > **Attio** and remove the connection.
* In Attio, you can also revoke access by uninstalling Buckle from the installed apps section of your workspace settings.

**API key connections**

* In Buckle, open **Settings** > **Apps** > **Attio** and remove the connection.
* In Attio, revoke or delete the API key so it can no longer be used.

## Controlling access

Access is per agent: [grant](/docs/guides/agent-access.md) the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization [rules](/docs/guides/rules.md) add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches Attio.

## FAQ

> [accordion] Should I use OAuth or an API key for Attio?
>
> OAuth works out of the box. Use a scoped API key when you want the agent to reach less than the full OAuth scope set, such as a read-only key. See [Configure](#configure).

> [accordion] How do I rotate an Attio API key?
>
> Create a new key in Attio, then paste it into **Settings** > **Apps** > **Attio** in Buckle. Agents pick up the new key automatically. OAuth tokens are refreshed for you.

> [accordion] Does the agent see my Attio token?
>
> No. Credentials are encrypted at rest and only decrypted inside the gateway at request time. See [How it works](/docs/how-it-works.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.