Skip to main content

Scopes

Scopes are a concept that groups and limits the access permissions of the mStudio public API. A scope is a set of permissions that allow a user or application to access specific operations of resources.

Scopes always act limiting for access permissions. Therefore, a scope cannot grant more permissions than are already available without said scope. However, a scope can deny permissions that are available without said scope.

Scopes of the mStudio Public API​

We generally name the scopes of the mStudio public API according to their conceptual domain. Such domains are, for example, project, app, or database. We split the scopes for each domain into reading, writing, and deleting access. So for the project domain, the scopes project:read, project:write, and project:delete exist.

Identifying Required Scopes​

You can generally identify the required scopes for an operation from the API reference of the mStudio public API. It defines all conceptual domains as OpenAPI tags at the root level and describes the individual operations inside the tags. Usually, the scope required for the respective operation is derived from the tag and the method of the operation.

We prefix the operation ID of operations with the corresponding conceptual domain. Therefore, you can identify the conceptual domain from the operation ID. The API reference displays the operation ID in the detail view of the operation.

In some cases, an operation may require multiple scopes or the scopes can't be derived directly from the operation for technical reasons. In those cases, the reference lists the required scopes explicitly in the description of the operation.

Availability of Scopes​

Note: Not all scopes for the mStudio API are currently implemented.

If your organization has been promoted to a contributor, you can view the available scopes in mStudio.

  1. Navigate to the Entwicklung tab within your organization.
  2. Here you will find a list of all your Extensions, or you can create a new one.
  3. Open an Extension and go to the Berechtigungen tab.
  4. In the Berechtigungen section, click the Bearbeiten button to edit the requiredScopes of your Extension.
    Here you can select from all available scopes.

Alternatively, you can retrieve all available scopes via the API endpoint:

GET /v2/scopes HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

[
  {
    "name": "project:read"
  },
  {
    "name": "project:write"
  },
  {
    "name": "project:delete"
  }
]
See full request reference at: GET/v2/scopes/

mittwald works on implementing more scopes to expand the list of available scopes. If you need a scope that is not available yet, you can ask us for it. We strive to deliver the scope promtly.

Example​

The GET/v2/projects/{projectId}/ operation has the ID project-get-project and the OpenAPI tag Project. It also has the HTTP method GET. This results in the required scope project:read.

Outlook​

We plan to enable users to immediately identify required scopes from the API reference. We also plan to document the cases where the operation is not intended for use via OAuth2 or Extensions.