---

Scope is a security mechanism that enables you to restrict access to specific services or even to specific functions within a service (the so-called “resolvers”).

Scope is an attribute of service access keys, and of a few other entities across SBS. For example, you can configure a service access key to allow access to received email, but disallow sending email. Typically, you declare the scope of a service access key (or an app-level access key) when you generate it. You can also update the scope of existing service access keys at a later time.

The following entities in SBS have scope:

• Service access keys. For such entities, scope defines what services (or even queries and mutations within a service) are permitted to the bearer of the key.
• App-level service access keys. Same as above, except that it is applicable to services that require an app-level access key.
• Service access tokens created through the Authorization Service. For service access tokens, scope defines what services (or queries and mutations within a service) are permitted to the bearer of the token.
• Service access denials. For such entities, scope defines what services (or queries and mutations within a service) are denied to the bearer of the key.
• Account access keys. For such entities, scope defines what services (or queries and mutations) of the Account API are permitted to the bearer of the key.
• Account users. For account users, scope defines, on one hand, what entities in the graphical user interface of the SBS Console are visible to them (for example, you may allow the account user to view tenants but disallow them to view apps). On the other hand, it restricts the actions that the account user can take against entities (for example, you may allow the account user to create tenants but disallow creating or updating applications). Thirdly, the scope defines what queries and mutations are available to the account user from the GraphQL tab of the SBS Console. For more information, see Accounts and account users.
• Portal users. For portal users, scope defines the GUI actions available to them in the graphical user interface of the SBS Portal. Secondly, it defines what queries or mutations are available to the user from a GraphQL interface if they choose to use one. For more information, see Portal users.

In most cases, setting scope on an entity is optional (that is, the scope field may be left blank). Bear in mind, however, that, if scope is not set, this is equivalent to allowing the bearer full access to any service. Note that setting a scope is mandatory in case of service access denials.

GraphQL syntax

In all GraphQL mutations that take a scope input parameter of type string, the scope should be provided as a string composed of three parts, separated by colons (:), as follows:

[prefix]:[query|mutation]:[resolver]

Where:

• prefix is the beginning part (service subdomain) of the service endpoint. For example, the subdomain of the service https://email-api.socrate.io is email-api. For the access endpoint of each service, refer to the API Reference.
• query or mutation indicates whether the scope is supposed to allow or deny queries or mutations, respectively.
• resolver refers to the actual GraphQL resolver (query or mutation) and is specific to each service. For example, sendMessage is one of the resolvers provided for the Email Service. You can also use the asterisk character (*) as a resolver, which signifies that all queries (or mutations, respectively) are allowed (or disallowed, depending on the context).

If necessary, you can concatenate multiple scopes by using the space character as separator. This way, you can create fine-grained scopes bound to as few or as many services as required by your particular business needs.

Here are some examples of valid scope:

Scope	Meaning
file-management-api:query:files	This scope provides access to querying the files resolver of the File Management service.
file-management-api:query:*	This scope provides access to any query on the File Management service.
email-api:query:* email-api:mutation:*	This scope provides full access to the Email Service. Note the space character used as a separator.

Scope editor

When you create or edit from the Web UI any of the entities that require scope, a scope editor is available to help you define or change scope easily. The scope editor provides two ways to enter scope: Visual and Text. You can switch between these two modes by clicking the tab with the same name.

The Visual scope editor lets you add scope with the help of controls such as input boxes, drop-down lists and radio-buttons. You can define multiple scope groups, where each groups consists of the following parts:

• the service (for example, account-api)
• the resolver type (can be either query or mutation)
• the resolver name (for example, the createApp mutation). In some contexts, you can select the resolver from a predefined drop-down list; in other contexts, you must type the resolver name.

Below is an example of setting scope using the Visual scope editor:

In the dialog box above, there are two scope groups defined for the user somebody@example.org:

1. The first scope group gives this user access to all queries of the account-api service.
2. The second scope group gives this user access to the createApp mutation of the account-api service.

Alternatively, you can enter scope through a Text scope editor (available when you click the Text tab). The text scope editor has the same syntax as the GraphQL syntax, except for one difference: each scope string must be on a new line. For example: