Attio

The Attio auth provider enables tools and agents to call Attio APIs  on behalf of a user.

What’s documented here

This page describes how to use and configure Attio auth with Arcade.

This auth provider is used by:

• The Arcade Attio MCP server, which provides pre-built tools for interacting with Attio
• Your app code that needs to call Attio APIs
• Or, your custom tools that need to call Attio APIs

Use Arcade’s default Attio auth provider

Arcade offers a default Attio auth provider that you can use in the Arcade Cloud Platform. In this case, your users will see Arcade as the name of the application requesting permission.

If you choose to use Arcade’s Attio auth, you don’t need to configure anything. Follow the Attio MCP server examples to get started calling Attio tools.

Use your own Attio app credentials

In a production environment, you will most likely want to use your own Attio app credentials. This way, your users will see your application’s name requesting permission.

Before showing how to configure your Attio app credentials, let’s go through the steps to create an Attio app.

Create an Attio app

• In your Attio workspace, go to Settings → Developer → Apps
• Click Create app and give it a name and description
• In your app’s settings, navigate to the OAuth tab
• Toggle Enable OAuth 2.0 at the top of the page
• Under Redirect URIs, add the redirect URL generated by Arcade (see below)
• Under Scopes, enable the scopes your app needs. If you plan to use the Arcade Attio MCP server, enable:
  • call_recording:read
  • list_configuration:read-write
  • list_entry:read-write
  • meeting:read
  • note:read-write
  • object_configuration:read-write
  • record_permission:read-write
  • task:read-write
  • user_management:read
• Copy the Client ID and Client Secret from the OAuth tab

Configure your own Attio auth provider in Arcade

Using the Arcade Attio MCP server

The Arcade Attio MCP server provides tools to interact with Attio CRM objects, such as records, notes, tasks, lists, and meetings.

Refer to the MCP server documentation and examples to learn how to use the MCP server to build agents and AI apps that interact with Attio.

Using Attio auth in app code

Use the Attio auth provider in your own agents and AI apps to get a user-scoped token for the Attio API. See authorizing agents with Arcade to understand how this works.

Use client.auth.start() to get a user token for the Attio API:

from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "{arcade_user_id}"
 
# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="attio",
    scopes=[
        "record_permission:read-write",
        "note:read-write",
    ],
)
 
if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
# Do something interesting with the token...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
 
const userId = "{arcade_user_id}";
 
// Start the authorization process
let authResponse = await client.auth.start(userId, "attio", {
  scopes: ["record_permission:read-write", "note:read-write"],
});
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);
 
const token = authResponse.context.token;
// Do something interesting with the token...

Using Attio auth in custom tools

You can author your own custom tools that interact with the Attio API.

Use the Attio() auth class to specify that a tool requires authorization with Attio. The authentication token needed to call the Attio API is available in the tool context through the context.get_auth_token_or_empty() method.

from typing import Annotated
 
import httpx
 
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Attio
 
 
@tool(
    requires_auth=Attio(
        scopes=["record_permission:read-write"],
    )
)
async def query_attio_companies(
    context: ToolContext,
    limit: Annotated[
        int,
        "Maximum number of company records to return.",
    ] = 10,
) -> Annotated[dict, "List of company records from Attio"]:
    """Query company records from Attio."""
    url = "https://api.attio.com/v2/objects/companies/records/query"
    headers = {
        "Authorization": f"Bearer {context.get_auth_token_or_empty()}",
        "Content-Type": "application/json",
    }
 
    async with httpx.AsyncClient() as http_client:
        response = await http_client.post(
            url,
            headers=headers,
            json={"limit": limit},
        )
        response.raise_for_status()
        return response.json()