Attio Install & Auth
Overview
Configure authentication for the Attio REST API (https://api.attio.com/v2). Attio offers two auth methods: access tokens (scoped to a single workspace) and OAuth 2.0 (for multi-workspace integrations). There is no official first-party Node SDK -- use fetch or a community client like attio-js.
Prerequisites
- Node.js 18+ or Python 3.10+
- Attio account at app.attio.com
- API access enabled in workspace settings
Instructions
Step 1: Generate an Access Token
- Open Settings > Developers > Access tokens in your Attio workspace
- Click Create token and name it (e.g.,
my-integration-dev)
- Configure scopes (tokens have no scopes by default -- you must add them):
| Scope | Grants access to |
|---|
object_configuration:read | List/get objects and attributes |
record_permission:read | Read records (people, companies, deals) |
record_permission:read-write | Create/update/delete records |
list_entry:read | Read list entries |
list_entry:read-write | Create/update/delete list entries |
note:read-write | Create and read notes |
task:read / task:read-write | Read or manage tasks |
user_management:read | Read workspace members |
webhook:read-write | Manage webhooks |
- Copy the token -- it starts with
sk_ and never expires (but can be revoked)
Step 2: Configure Environment
ATTIO_API_KEY=sk_your_token_here
.env
.env.local
.env.*.local
Step 3: Initialize the Client
const ATTIO_BASE = "https://api.attio.com/v2";
interface AttioRequestOptions {
method?: string;
path: string;
body?: Record<string, unknown>;
}
export async function attioFetch<T>({
method = "GET",
path,
body,
}: AttioRequestOptions): Promise<T> {
const res = await fetch(`${ATTIO_BASE}${path}`, {
method,
headers: {
Authorization: `Bearer ${process.env.ATTIO_API_KEY}`,
"Content-Type": "application/json",
},
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) {
const error = await res.json();
throw new Error(
`Attio ${res.status}: ${error.code} - ${error.message}`
);
}
return res.json() as <T>;
}
Step 4: Verify Connection
const objects = await attioFetch<{ data: Array<{ api_slug: string }> }>({
path: "/objects",
});
console.log(
"Connected! Objects:",
objects.data.map((o) => o.api_slug)
);
curl -s https://api.attio.com/v2/objects \
-H "Authorization: Bearer ${ATTIO_API_KEY}" | jq '.data[].api_slug'
OAuth 2.0 Flow (Multi-Workspace)
For apps that other workspaces install, use OAuth 2.0 Authorization Code Grant (RFC 6749 section 4.1).
const authUrl = new URL("https://app.attio.com/authorize");
authUrl.searchParams.set("client_id", process.env.ATTIO_CLIENT_ID!);
authUrl.searchParams.set("redirect_uri", "https://yourapp.com/callback");
authUrl.searchParams.set("response_type", "code");
const tokenRes = await fetch("https://app.attio.com/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
grant_type: "authorization_code",
client_id: process.env.ATTIO_CLIENT_ID,
client_secret: process.env.ATTIO_CLIENT_SECRET,
code: authorizationCode,
redirect_uri: "https://yourapp.com/callback",
}),
});
const { access_token } = await tokenRes.json();
Error Handling
| Error | HTTP Status | Cause | Solution |
|---|
invalid_grant | 401 | Bad or expired auth code | Re-authorize the user |
insufficient_scopes | 403 | Token missing required scope | Add scope in dashboard, regenerate |
invalid_request | 400 | Malformed Authorization header | Use Bearer <token> format |
not_found | 404 | Token revoked or workspace deleted | Generate new token |
Attio Error Response Format
All Attio errors return JSON with a consistent structure:
{
"status_code": 403,
"type": "authorization_error",
"code": "insufficient_scopes",
"message": "Token requires 'record_permission:read' scope"
}
Resources
Next Steps
After verifying auth, proceed to attio-hello-world for your first real API call.
