Request-Level Authorization

When calling most Wristband APIs, authenticated subjects (either users or machines) must be granted a specific permission to pass the authorization checks. To determine which permissions are required for an API, 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 examine the Required Permissions section for the Get User API, to help illustrate how Wristband utilizes 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:

Example application entities — Figure 1. Diagram illustrating the tenant and user entities associated with 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 can retrieve User A, User B, User C, and User D.