Resource permissions

Both individual element resources (such as Activity) and collection resources (such as Activities) can have a permissions section. This section defines the actions associated users can take on accessible resources.

The permissions section consists of a list of permissions, each of which is followed by a Boolean expression. The permission is granted if and only if the Boolean expression returns true.

For example, the following code defines the permissions for the Accounts resource (for a collection of accounts) as declared in the internal_core-1.0access.yaml file. The view permission is granted if the caller has the acctabview and acctsummview permissions. The create permission is granted if the user has the acctcreate permission.

Accounts:
  permissions:
    view:
    - perm.System.accttabview
    - perm.System.acctsummview
    create: perm.System.acctcreate
Java

Permissions for element resources

For individual elements, you can specify view, create, edit, and delete permissions. You can also specify permissions for custom business actions. For example, if there is a POST /activities/{activityId}/assign endpoint, then for an Activity resource, you can specify an assign permission. For custom actions, the permission name must match the verb used at the end of the endpoint path.

Warning: If you create a new endpoint that executes a custom action, do not name the endpoint with a name that would conflict with a base permission, such as view, edit, create, or delete. Doing so will result in unexpected permission behaviors.

If a given permission is not specified in an access file, then the permission defaults to the permission of the resource's parent. If a given resource does not have a permissions section, then all permissions default to the permission of the resource's parent.

Possible Boolean expressions

Any Gosu expression that returns true or false can be used as a permission's Boolean expression.

For permissions, the base configuration includes the following types of Boolean expressions:

  • A Boolean value
  • The keyword __inherit (in which case the permission is inherited from the resource's parent, such as AccountInvoices...view: __inherit)
  • A Gosu expression, including:
    • A Gosu system perm expressions (such as "perm.system.actview")
    • A Gosu resource perm expressions (such as "perm.Activity.view(resource.Activity)")
    • A Gosu expression (such as "!resource.Note.Confidential || resource.Note.Author == entity.User.util.CurrentUser || perm.Claim.viewconfidentialnotes(resource.Note.Claim)")
    • A Gosu method declared at the system API layer (such as "gw.rest.core.pl.util.v1.ActivityInternalPermissionUtil.canApprove(resource.Activity)")

For more information on writing Gosu expressions that check for system permissions or resource permissions, refer to the Rules Guide.

In some cases, multiple expressions are listed on several lines, such as the following example. In this case, the expressions are ANDed together. All expressions must return true for the permission to be granted.

Accounts:
  permissions:
    view:
    - perm.System.accttabview
    - perm.System.acctsummview
Java