Permissions

Permissions define specific actions that users or machines are allowed to perform on resources within your application. They provide granular control over access to application functionality, such as creating, reading, updating, or deleting resources.

Permissions can be assigned to roles and permission groups, allowing you to organize and manage access rights across your application.

Permission Types

Wristband supports two types of permissions: predefined permissions and custom permissions. Both types can be assigned to roles and permission groups.

Predefined Permissions

Predefined permissions are system-managed permissions that control access to Wristband APIs and resources. They are defined by Wristband and cannot be created, modified, or deleted.

For example, Wristband provides predefined permissions such as user:read and user:create, which control access to operations on Wristband-managed User resources.

Custom Permissions

Custom permissions are application-defined permissions that you can use to control access to your application's own resources and functionality. Unlike predefined permissions, custom permissions are fully managed by you and can be created, modified, or deleted as needed.

Custom permissions are independent of Wristband's API authorization model. Your application is responsible for evaluating these permissions and enforcing the appropriate access controls.

Structuring Custom Permissions

When defining custom permissions, we recommend using a structured naming convention that identifies both the resource and the action being performed. This approach helps keep permissions consistent, organized, and easy to manage as your application grows.

For example, an application that manages projects might define the following custom permissions:

• project:create — Create new projects.
• project:read — View existing projects.
• project:update — Modify existing projects.
• project:delete — Delete projects.

Although this naming convention is recommended, custom permissions are ultimately treated as string values by Wristband. Your application is responsible for interpreting these values and enforcing the corresponding access controls.

Effective Permissions

When a user or machine is assigned multiple roles, their effective permissions are the combined set of permissions granted by all assigned roles.

For example, consider two roles with the following permissions:

• Role A: Read, Write
• Role B: Write, Delete

A user assigned both roles would have the following effective permissions:

• Read (granted by Role A)
• Write (granted by both Role A and Role B)
• Delete (granted by Role B)

Because permissions are additive, assigning additional roles can only expand a user's or M2M client's effective permissions, not restrict them.

Permission Groups

Permission groups allow you to organize related permissions into reusable collections that can be assigned to roles. Instead of assigning the same set of permissions individually to multiple roles, you can create a permission group and assign it to each role that requires those permissions.

A role can have both individual permissions and permission groups assigned to it.

How Permission Groups Affect Effective Permissions

Permissions granted through permission groups follow the same additive model as individually assigned permissions. A role's effective permissions are the combined set of permissions assigned directly to the role and those inherited through its permission groups.

For example, if a role has the project:read permission assigned directly and a permission group containing project:create and project:update, the role grants all three permissions.

Because permissions are additive, assigning a permission group to a role can only expand the role's permissions, not restrict them.

Application-Level vs. Tenant-Level Permission Groups

Wristband supports permission groups at both the Application and Tenant levels, allowing you to define reusable permissions across your application while supporting tenant-specific access control requirements.

A role can be assigned a combination of Application-level and Tenant-level permission groups, provided those groups are available to the role's tenant.

Application-Level Permission Groups

Application-level permission groups can be shared across multiple tenants, allowing you to define common sets of permissions that can be reused throughout your application.

By default, these permission groups are available to all tenants. However, you can use the Tenant Visibility setting to control which tenants can view and assign them to roles.

Application-level permission groups support the following Tenant Visibility options:

Tenant-Level Permission Groups

Tenant-level permission groups belong to a specific tenant and can only be assigned to roles within that tenant. They cannot be shared with or assigned to roles in other tenants.

This allows individual tenants to define their own permission groups without affecting the authorization configurations of other tenants.

Permission Boundaries

Permission boundaries define the scope of resources that a user or machine can access through their assigned permissions. They provide an additional layer of authorization control by restricting where permissions can be exercised.

Permission boundaries are optional and can be assigned to roles and permission groups. When a role requires permissions with different boundaries, you can organize those permissions into separate permission groups, assign the appropriate boundary to each group, and then assign those groups to the role.

Permission Boundary Types

Wristband supports two categories of permission boundaries: predefined boundaries and custom boundaries.

Predefined Permission Boundaries

Predefined permission boundaries are system-managed boundaries that control the scope of access to Wristband APIs and resources. They are defined by Wristband and cannot be created, modified, or deleted.

Wristband provides the following predefined permission boundaries:

Tenant Inclusion and Exclusion List Boundaries

Wristband also supports tenant inclusion and exclusion list boundaries, which restrict access to specific tenants within an application.

These boundaries are particularly useful for administrative roles that require access to multiple tenants without granting application-wide permissions.

For example, consider an account manager responsible for Tenant A and Tenant B. By assigning a Tenant Inclusion List boundary containing those two tenants, you can restrict the account manager's permissions to resources belonging to Tenant A and Tenant B.

Similarly, a Tenant Exclusion List boundary can grant access across the application while excluding specific tenants.

Custom Permission Boundaries

Custom permission boundaries are application-defined boundaries that you can use to implement resource-level access restrictions specific to your application's business logic.

Unlike predefined boundaries, custom boundaries are fully managed by you and can be created, modified, or deleted as needed.

Custom permission boundaries are independent of Wristband's API authorization model. Your application is responsible for interpreting and enforcing these boundaries when evaluating access to its own resources.

Effective Permission Boundaries

Permission boundaries follow the same additive model as permissions. When a user or machine receives the same permission through multiple roles or permission groups with different boundaries, their effective access is the combined scope granted by those boundaries.

For example, consider a user assigned two roles:

• Role A (Admin User): Grants the user:read permission with an Application boundary.
• Role B (End User): Grants the user:read permission with a Self boundary.

Because permission boundaries are additive, the user's effective access for user:read includes the Application boundary, allowing them to retrieve user information across the entire application.

Assigning an additional role with a more restrictive boundary does not reduce access already granted through another role.