OAuth Scopes

When a client app is added to the Developer Console, you need to specify OAuth scopes for the app. A scope means a set of permissions for the resources that the client app has access to, specifying available API operations. It also applies to the access permissions for the access token that is issued for the app.

At least one scope is required to make an API call. For more information, see the description of each API operation.

OAuth scope format {#scope-format}

An OAuth scope name is formatted as {resource name}.operation, where a resource name can include child resources separated by dots (.) if needed. The following scope shows a resource named "group" that has a child resource named "folder".

• group (group resource)
• group.folder (group folder resource)

A child resource inherits permissions from its parent resource.

An operation refers to the scope of permissions for the resource. For example, the user resource has the following two operations:

• user (read/write)
• user.read (read only)

The user scope allows API operations which can read or read/write the user resource. The user.read scope, however, allows API operations which can only read the user resource, so you cannot make an API call to add a new user or delete an existing one. In this way, an OAuth scope specifies the scope of permissions for the resource that the client app accesses.

Note

• To send a message to members by using a message bot, you need to add the bot scope, not the user scope.

You can select one or more scopes for each client app in the Developer Console. The specified scopes are shown to users after they log in to the client app. Note that some scopes may not be shown depending on the pricing plan.

You can guess the OAuth scopes of an API operation, based on its method. Here are user scopes by method.

• user (read/write): GET/POST/PUT/PATCH/DELETE methods
• user.read (read only): GET method

Since the user scope covers all the API operations allowed by the user.read scope, you do not need to add both scopes at the same time. However, using the user scope alone can produce unintended data changes, so if you need to simply view user information, using the user.read scope is recommended.

Note

• Guessing the OAuth scopes from a method is not always correct. See the description of each API operation for the exact OAuth scopes.

List of scopes {#scope-list}

The following table shows the scopes and plans available in the Developer Console. Each scope specifies a client app's access permissions for the resource.

LINE WORKS Core

AiStudio Drive