Scope

What it is

A scope is a permission string that defines what an application or installation is allowed to access.

Scopes are written in the format:

audience:operation

Examples:

sale:read
sale:save
transaction:read
webhook:save

Multiple scopes are separated by a space:

sale:save sale:read transaction:read

The API schema describes application scopes as space-separated values in the audience:operation format.

See all available scopes

Why it exists

Scopes limit what an integration can do.

They make permissions explicit and allow access to be granted only for the resources and operations an integration needs. For example, an application that only reads sales should use a read scope, while an application that creates or updates sales needs a save scope.

How it relates to other concepts

Scopes are defined on an Application to describe the permissions available to that application. The Application page states that an application has scopes and that those scopes control access.

Scopes are also stored on an Installation. This means the installed version of an Application has its own active permission set for a merchant context.

Scopes are used during authentication. When requesting an OAuth token, the scope value contains one or more OAuth scopes separated by spaces.