Available Scopes in Bitrix24

A scope is a code for a group of methods. It defines which Bitrix24 tools an application or a webhook can access through the REST API. To find out how to select scopes for an application scenario and how a scope differs from user permissions, see Access Permissions for Methods and Scopes.

Quick navigation: Scope Codes

Where to Specify a ScopeWhere to Specify a Scope

For an application, scopes are selected when it is added, and the place depends on the solution type.

• A mass-market solution is added in the Developer's Area. Scopes are specified in the technical specifications as the system sections the application interacts with. The procedure is described in the article How to Add a Solution in the Developer's Area.
• A local application is added in Bitrix24, in Applications > Developer resources. The procedure is described in the article Local Applications.

For a webhook, scopes are selected when it is created, in the Assign permissions section. Requests run within the selected scopes and with the permissions of the employee who created the webhook. For details, see Inbound and Outbound Webhooks.

What Happens if a Method Is Called Outside the Granted ScopeWhat Happens if a Method Is Called Outside the Granted Scope

If an application or a webhook calls a method whose scope has not been granted, Bitrix24 returns the insufficient_scope error and does not execute the request. Response to a call from an application:

{
            "error": "insufficient_scope",
            "error_description": "The request requires higher privileges than provided by the access token"
        }
        

For a webhook, only error_description differs — it contains provided by the webhook token.

To make the call succeed, add the required scope to the application or webhook settings. Other system errors are collected in the article Error Codes.

When a Scope Alone Is Not EnoughWhen a Scope Alone Is Not Enough

Some methods work only in the application context. When a webhook calls such a method, Bitrix24 returns the WRONG_AUTH_TYPE error with the Application context required description. The placement.bind method behaves this way, for example.

Scope CodesScope Codes