Setting up your first integration

An integration is a set of configuration in your developer workspace, that allows you to:

• Generate access tokens and set permissions for working with our APIs
• Setup webhooks for listening to system changes
• Configure OAuth for connecting other workspaces
• Add branding and metadata for when other users use your integration

You can create an integration in the Settings > Developers page in your Attio workspace.

Let's discuss the settings that you can configure on integrations.

Scopes

Scopes are restrictions on the abilities of your integration. You must specify which parts of the application you'd like to be able to read and/or write from, and access tokens generated in the web application or using OAuth 2.0 will inherit these scopes when they are granted.

Access tokens can only be used on the endpoints they have been scoped for. In some cases, endpoints will require multiple scopes - for example, being able to read records also requires both the "object configuration" and "record" scopes. The required scopes are documented on each endpoint in the reference.

Please note that when your integration is initially created, it has no scopes configured.

If you are planning to request publication of your integration, for use by other workspaces, please ensure you are only using the smallest set of scopes that you need—this aids our security review process.

Access tokens

Attio access tokens are always scoped to a single workspace. When your integration is created, we generate a single access token for you to use, but you can also create more if needed.

If you're planning to connect other workspaces using OAuth 2.0, it is advisable to delete all access tokens and instead rely purely on OAuth-generated tokens.

OAuth

By default, OAuth is disabled on new integrations, since we assume most developers will be building something for their own workspace. However, it can be enabled in OAuth section of the settings page.

For more information about using OAuth 2.0, please check out our OAuth guides.

Webhooks

Webhooks let you make an HTTP POST request to an endpoint of your choosing, whenever something relevant changes in Attio. For example, you could fire a notification whenever a new entry is created in a list, or power a realtime sync of user records to internal admin tooling.

Use the webhook settings to setup webhooks and specify one or more events to subscribe to, as well as trigger test events.

For more information about webhooks, please check out our Webhooks guide.