Learn how Wristband authorizes API requests.
Request-Level Authorization
When calling most Wristband APIs, authenticated subjects (either users or clients) must be granted a specific permission to pass the authorization checks. To determine which permissions are needed for an API, you'll need to refer to the Required Permissions section in the API reference documentation.
Some APIs Don't Require Permissions
If an API’s reference documentation does not include a Required Permissions section, no permissions are needed for the authenticated subject to call that API.
In the next section, we'll take a look at the Required Permissions section for the Get User API, to help illustrate how Wristband uses permissions to enforce authorization.
Required Permissions Example
If we look at the Get User API as an example, we can see that it has the following table under its Required Permissions section (note, the Description column has been omitted from the table for brevity):
| Permission | Boundary |
|---|---|
| user:read | Application |
| Tenant | |
| Tenant Inclusion List | |
| Tenant Exclusion List | |
| Self |
To determine how the API will enforce authorization decisions, we need to look at the Permission and Boundary columns of the table. The Permission column specifies the required permission for a subject, while the Boundary column lists the supported permission boundaries that can be applied to that permission. The sections below explain how these work together to control access to the Get User API.
Permission Column
The Permission column shows that the authenticated subject must have the user:read permission to call the Get User API. Calls made without this permission will return a 403 Forbidden response.
Boundary Column
The Boundary column defines which permission boundaries can be combined with the permission. These boundaries determine the scope of access granted to the authenticated subject. For example, for the Get User API, the permission boundaries dictate which users within an application a subject is authorized to retrieve.
If we look at the Boundary column from the table above, we can see that the user:read permission can be used with the following permission boundaries:
- Application
- Tenant
- Tenant Inclusion List
- Tenant Exclusion List
- Self
To see how these different permission boundaries affect which users can be read using the Get User API, let's imagine we have a Wristband application with the tenants and users shown in the diagram below:
Figure 1. Diagram showing the tenant and user entities belonging to a fictitious Wristband application.
Now, let's examine how different permission boundaries impact the users we can read using the Get User API.
Application Permission Boundary
If the user:read permission is combined with an Application permission boundary, the authenticated subject can call the Get User API for all users within the same application. For example, if User A is the authenticated subject, they would be able to retrieve User A, User B, User C, and User D.
The diagram below illustrates this scope of access. The users in the green box represent those that User A can successfully retrieve using the Get User API.
Figure 2. Diagram illustrating the scope of access granted by the Application permission boundary.
Tenant Permission Boundary
If the user:read permission is combined with a Tenant permission boundary, the authenticated subject can call the Get User API for all users within the same tenant. For example, if User A is the authenticated subject, they would be able to retrieve User A and User B.
The diagram below illustrates this scope of access. The users in the green box represent those that User A can successfully retrieve using the Get User API.
Figure 3. Diagram illustrating the scope of access granted by the Tenant permission boundary.
Tenant Inclusion List Permission Boundary
If the user:read permission is combined with a Tenant Inclusion List permission boundary, the authenticated subject can call the Get User API for all users belonging to tenants specified in the inclusion list. For example, if User A is the authenticated subject, and the tenant inclusion list contains Tenant B and Tenant C, they would be able to retrieve User C and User D.
The diagram below illustrates this scope of access. The users in the green box represent those that User A can successfully retrieve using the Get User API.
Figure 4. Diagram illustrating the scope of access granted by the Tenant Inclusion List permission boundary when the inclusion list contains Tenant B and Tenant C.
Tenant Exclusion List Permission Boundary
If the user:read permission is combined with a Tenant Exclusion List permission boundary, the authenticated subject can call the Get User API for all users belonging to tenants not specified in the exclusion list. For example, if User A is the authenticated subject, and the tenant exclusion list contains Tenant C, they would be able to retrieve User A, User B, and User C.
The diagram below illustrates this scope of access. The users in the green box represent those that User A can successfully retrieve using the Get User API.
Figure 5. Diagram illustrating the scope of access granted by the Tenant Exclusion List permission boundary when the exclusion list contains Tenant C.
Self Permission Boundary
If the user:read permission is combined with a Self permission boundary, the authenticated user can only call the Get User API for itself. For example, if User A is the authenticated subject, they would only be able to retrieve User A.
The diagram below illustrates this scope of access. The users in the green box represent those that User A can successfully retrieve using the Get User API.
Figure 6. Diagram illustrating the scope of access granted by the Self permission boundary.
Unsupported Permission Boundaries
Not all APIs support every type of permission boundary. For example, if we look at the Required Permissions section for the Change Password API, we can see that it only supports the Self permission boundary.
| Permission | Boundary |
|---|---|
| change-password-workflow:execute | Self |
Therefore, in order to call the Change Password API, the authenticated subject must be granted the change-password-workflow:execute permission with a Self permission boundary. Any other combination of permission and permission boundary will result in a 403 Forbidden error. For example, if a user was granted the change-password-workflow:execute permission with an Application permission boundary, they would not be able to call the Change Password API, since the Application permission boundary isn't supported.
Field-Level Authorization
In addition to request-level permissions, some APIs also enforce field-level permissions, which are required to view or update specific fields within an entity. When applicable, these permissions are documented in a Field-Level Permissions section that appears below the Required Permissions section.
To gain a better understanding of how field-level permissions work, let's look at a couple of examples showing how they can restrict updates to specific fields and read access to others.
Field-Level Update Restrictions
To illustrate how field-level permissions restrict modifications to specific fields, let’s look at the Patch User API. In its Required Permissions section, you’ll find a Field-Level Permissions subsection with the following table:
| Permission | Description |
|---|---|
| user:manage-email | Required if the email or emailVerified fields are modified. |
| user:manage-external-id | Required if the externalId field is modified. |
| user:manage-restricted-metadata | Required if the restrictedMetadata field is modified. |
| user:manage-status | required if the status field is modified. |
In this case, there are four field-level permissions, each restricting modification to a subset of user fields. For example, the user:manage-status permission is required to update the status field while the user:manage-restricted-metadatais needed to modify the restrictedMetadata field. If the patch request attempts to update a user field protected by a field-level permission, and the authenticated subject has not been granted that permission, then a 403 Forbidden response will be returned.
Note
Fields protected by field-level permissions may still be included in a patch request, even if the user lacks the required field-level permission, provided the field’s value is not modified.
Field-Level Read Restrictions
To illustrate how field-level permissions restrict reading specific fields, let’s look at the Get Identity Provider API. In its Required Permissions section, you’ll find a Field-Level Permissions subsection with the following table:
| Permission | Description |
|---|---|
| identity-provider:view-protocol | Required to view the protocol field. |
In this case, there's one field-level permission restricting the ability to read the protocol field. If a request is made to the Get Identity Provider API, attempting to read the protocol field, and the authenticated subject has not been granted the identity-provider:view-protocol permission, then the request will succeed, but the protocol field will be undefined in the response.
Field-Level Permission Boundaries
As with request-level permissions, field-level permissions must be assigned the correct permission boundaries. The boundaries that apply to field-level permissions are identical to those for their corresponding request-level permission. For example, in the Patch User API, the user:update request-level permission supports the following boundaries:
- Application
- Tenant
- Tenant Inclusion List
- Tenant Exclusion List
- Self
Therefore, the Patch User API’s field-level permissions also support the Application, Tenant, Tenant Inclusion List, Tenant Exclusion List, and Self boundaries. Permission boundaries function the same way for both request-level and field-level permissions. For instance, to allow a user to update the status of all users within an application, you would grant them the user:manage-status field-level permission with an Application boundary.
Note
In addition to the
user:manage-statusfield-level permission, you must also grant theuser:updaterequest-level permission with an Application boundary to allow the authenticated subject to update the status of all users within an application.