Introducing Webscale Role-based Access

An introduction to Webscale role-based access


Webscale role-based access (RBAC) uses the permissions of the roles to which a user has accepted invitations to determine their Webscale API access. Account owners can configure roles with granular Webscale API permissions, allowing administrators to deploy to users the least amount of API access needed for the user to complete their task.

This overview will focus on the concepts and mechanisms necessary to understand RBAC.


Roles used for RBAC are configured with permissions. These permissions describe exactly the parts of the API the user can access. Permissions are defined using three pieces of information:

  • method: For a permission to apply to an incoming API request, the HTTP method on the request and the permission must match. Supported methods include GET, POST, PATCH, PUT, DELETE.
  • spec: This contains the collection of API endpoints to which this permission applies. The incoming request’s target (e.g. /v2/applications/abc123) will be compared to this collection. In addition to matching the HTTP method, if the request’s target is contained in the collection, the permission’s effect is applied.
  • effect: An effect of permit will grant the user access to the requested resource. An effect of deny will prevent access and return a 403 status code.

By default, if a relevant permission is not found in any roles to which the user has accepted invitations, the user is denied access to the request target and a 403 status code is returned.

A role may contain any number of permissions and a user may have access to multiple roles in a particular account. In this case, as long as one matching permission with an effect of permit exists, the user is granted access.

When defining a permission, wildcards can be used in the spec definition to apply to multiple endpoints at once:

  • A single wildcard (*) applies to a specific collection of resources or a specific resource but not the sub-resources. For example, spec: [ '/v2/accounts/*' ] applies to /v2/accounts/abc123 and /v2/accounts/xyz789 but not to /v2/accounts/abc123/invitations or /v2/accounts/xyz789/roles.
  • A double wildcard (**) behaves like a single wildcard but also applies to sub-resources. This means /v2/applications** applies to /v2/applications, /v2/appplications/abc123 and /v2/applications/xyz789/logs.

Inviting users

In order to assume a role, a user must be invited and have accepted an invitation to that role. Only Account owners are permitted to invite users to roles.

Only roles defined in the account hierarchy the user is authenticated in are relevant when determining their access to a particular endpoint. If the user has accepted multiple invitations to roles across accounts, roles outside the relevant account hierarchy are ignored.

RBAC integration

RBAC has been integrated into all v2 API endpoints. As a result, searching in the Control Panel for resources like accounts, applications and clusters will only show those resources to which the user has access (GET /v2/accounts/{id}), in the account in which the resource resides. Similarly, in order to authenticate into another account, the user must have access to the account in question. Lastly, the types of tasks a user is permitted to run via the tasks API are determined by the following permissions:

Task Description Permission
enter_maintenance Put an application into maintenance mode. PATCH /applications/{id}
exit_maintenance Take an application out of maintenance mode. PATCH /applications/{id}
run-action Run an application action. PATCH /applications/{id}
start Start an application. PATCH /applications/{id}
stop Stop an application. PATCH /applications/{id}
generate-origin-certificate Generate a TLS certificate for an application. GET /applications/{id}
invalidate-cache Flush the application cache. PUT /applications/{id}

Control roles

When an account is created, a set of roles with preconfigured API access are created in the account. These include:

  • Account owner: This role encapsulates the permissions necessary to manage any role in the account. The account owner is determined during the onboarding process.
  • Editor: Editors can create, update and delete most resources in the account.
  • Reader: Readers are limited to read-only access to all resources in the account.

Once created, these roles are not be maintained by Webscale, allowing the administrator to refine the access users with each role should have. Problems related to API access should first be reported to the account’s owner and then to Webscale.

Administrator-created roles

Administrators also have the option to define unique roles that capture any API access they need to match their use cases. For example:

  • General application edit access vs. specifically configuring CloudEDGE workers on an application.
  • Putting the application into maintenance mode.
  • Running application load tests vs creating application load tests.

See creating roles for more information.

Last modified October 27, 2022