Setting up your first integration

Getting access to Attio data

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 appearance in customers' integrations page

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

Let's discuss the settings that you can change after creating your first integration.

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.

Publication

If you're just building an integration for yourself, you can skip this section.

However, if you're building an integration for use by multiple workspaces, Attio implements a publication process to ensure that all integrations are secure, high quality and appropriately promoted to our users.

When developing your integration, your OAuth flow will function within your development workspace only. When you're ready to share your work with the wider world, you may request publication from the Attio team so that your integration can be used by all workspaces. From this point, we'll be in touch to help ensure your integration meets all requirements and collaborate on any documentation and co-marketing as appropriate.