Web API

Press shift + S to search API reference.

Guide

Scopes

Scopes control what actions a token can perform.

Personal access tokens and OAuth access tokens can only access API endpoints covered by the scopes granted to them. A full reference of available scopes is below.

Note: By default, OAuth integrations can only request basic scopes. See here for more information about requesting enterprise scopes.

On top of requesting the correct scope, the user and token must also have the required resources and permissions to perform the action.

Example 1: a personal access token with the scope data.records:read and a base added to it would be able to use the "Read records" endpoint on that base, but would not be allowed to use the "Write records" endpoint for that base. Similarly, it would not be able to use the "Read records" endpoint to access other bases that have not been added to the token.

Example 2: a personal access token with the scope schema.bases:read and multiple bases added to it would only be able to create fields in bases where the user has Creator permissions (required to customize fields).

For more information on how tokens work, refer to the Authentication reference.

Basic scopes

The following scopes are available to all users:

data.records:read

See the data in records

data.records:write

Create, edit, and delete records

data.recordComments:read

See comments in records

data.recordComments:write

Create, edit, and delete record comments

schema.bases:read

See the structure of a base, like table names or field types

schema.bases:write

Edit the structure of a base, like adding new fields or tables

webhook:manage

View, create, delete webhooks for a base, as well as fetch webhook payloads.

block:manage

Create new releases and submissions for custom extensions via the Blocks CLI.

    user.email:read

    See the user's email address

      Enterprise member scopes

      The following scopes are only available to users on an enterprise account:

      enterprise.groups:read

      View information about user groups under the enterprise, their access, and their members

      workspacesAndBases:read

      View metadata about workspaces, bases, and views including collaborators

      workspacesAndBases:write

      Edit metadata of workspaces and bases, including collaborators, invites, views, and extensions

      workspacesAndBases.shares:manage

      View, enable, disable and delete share links for bases. Note: Share links can be used to view the data in the base.

      Enterprise admin scopes

      The following scopes are only available to enterprise admins:

      enterprise.scim.usersAndGroups:manage

      Manage the organization's users and groups via SCIM APIs, including provisioning and deprovisioning them.

      enterprise.auditLogs:read

      View the organization's audit logs

      enterprise.changeEvents:read

      View the organization's change events

      enterprise.exports:manage

      Manage the organization's data exports, including eDiscovery exports

      enterprise.account:read

      View data about the enterprise account, including workspaces ids, users, groups and email domains

      enterprise.account:write

      Edit data about the enterprise account, including creating descendant enterprise accounts

      enterprise.user:read

      View account information of users under the enterprise, including user id, name, email and bases user has access to

      enterprise.user:write

      Manage users under the enterprise account, including provisioning, deactivating and deleting users

      enterprise.groups:manage

      Manage user groups under the enterprise, including moving them

      workspacesAndBases:manage

      Manage workspaces and bases under the enterprise, including moving them