Working with Capabilities and Tags
Capabilities are permissions required to perform actions to entities on the BlackBerry IoT Platform. Before any device can perform an action, it must be granted the capability to do so. In fact, capabilities are useful only in the context of device entities because devices are the only entities that can perform an action. In general, entities that you create within an organization should have default capabilities assigned to allow devices to perform a minimal set of actions. You can either assign system-defined capabilities or extend some of the existing capabilities for application-specific usage for your application code.
You can add a capability to a target entity, and give (grant) that capability to an organization, application, user, device, or tag entity. Targets can be organization, firehose, application, device, or tag entities. That grant allows a device to perform an action on the target. You might wonder: why would you grant a capability to a non-device entity if devices are the only entities that can perform an action? The answer is simple–to assign a capability to more than one device using capability inheritance. For example, you could grant a capability to an application entity. That grant permits devices of that application to inherit the capability that was granted to the application. If capability inheritance was not possible, you would need to assign that capability to each device. For more information about capability inheritance, see Use capability inheritance.
The following illustration shows when a device wants to perform an action, there's a check to determine whether it has the capability granted to it. If the device does, then the platform allows the action to occur. If the device doesn't have the capability, the device won't be able to perform the action.
Capabilities can be granted or removed at any time with the effect being immediate. By default, granted capabilities don't expire, but they can be configured to expire on a specific date and time. Expiring capabilities are useful to grant a device temporary capability for specified time to perform an action on a target. For more information, see Assign capabilities.
As you can imagine, as the number of applications, users, and devices grow, the assignment of capabilities can be a challenging task. To simplify the management of capabilities on multiple entities that scales appropriately, you can use tags and associations. For more information, see Use tags to simplify permission management and Use associations to simplify permission management.
The BlackBerry IoT Platform comes with predefined system capabilities. These capabilities are granular and allow the granted entity to perform specific actions on another target. You can secure your data stored in the cloud to fit your business rules using these capabilities.
The following system-defined capabilities are available:
These are capabilities that can be performed on any entity.
||Create a capability on an entity|
||Delete a capability from an entity|
||Read a capability|
||Perform a search on device data. You can further limit the search using categories or data objects. For more information, see Working with Data.|
||Perform a search on device information.|
||Perform a search on file metatdata.|
Capabilities to perform actions on organization entities
These are capabilities that can be performed on organizations.
||Read an organization|
||Update an organization|
||Allow the organization to be tagged|
||Allow a tag to be removed from an organization|
Capabilities to perform actions on application entities
These are capabilities that can be performed on an application. This includes ability to manage data-retention policies.
||Create an application|
||Delete an application|
||Read application metadata|
||Update an application|
||Read applications in an organization|
||Read the API Key and Secret for an application|
||Update the API Key and Secret for an application|
||Tag an application|
||Allow a tag to be removed from an application|
||Create a data retention rule|
||Delete a data retention rule|
||Read data retention rule|
||Update data retention rule|
Capabilities to perform actions on device entities
These capabilities that can be performed on devices. Included as part of the capabilities for a device are capabilities to manage file entities, messages, and data.
||Create a device|
||Delete a device|
||Read device metadata|
||Update a device|
||List all devices by user and application|
||Read device associated to user|
||Allow the device to be tagged|
||Allow the tag to be removed from a device|
||Create data associated with a device|
||Read data associated with a device|
||Delete device data|
||Create a file|
||Delete a file|
||Read a file|
||Update the file's metadata|
||Create a message. Typically, you require a defined message type (i.e., message.create.[message type]_) with this capability|
Capabilities to perform actions on firehose entities
These capabilities that can be performed on firehoses.
||Consume or read data from a firehose|
||Create a firehose|
||Delete a firehose|
||Read the list of firehoses available|
||Read the parameters for a firehose|
||Update the parameters for a firehose|
||Add a subscription to the firehose|
||Delete a subscription from a firehose|
||Read a list of subscriptions for a firehose|
||Read the parameters of a subscription|
Capabilities to perform actions on tag entities
The capabilities to manage and use tags.
||Create a tag|
||Delete a tag|
||Required to tag another entity using this tag|
||Read a tag|
||Read tagged entities by tag|
||Update a tag|
Capabilities to perform actions on user entities
The capabilities to manage user entities within an organization.
||Read a user|
||Read the profile for a user|
||Add a user to an organization|
||Remove a user from an organization|
||Read users in organization|
||Allow the user to be tagged|
||Allow a tag to be removed from a user|
You can extend some of the system-defined capabilities to create a custom capability that are application-specific. Extended capabilities (or custom capabilities) are useful for granting other devices the ability to read messages, read specific data stored on devices, or perform searches on data. You can extend these capabilities:
To extend the
search.data capabilities, you should know
how the data is organized, the category the data belongs to, and the name of the
standard (always called
For information about the categories and standards, see Data.
To extend the
search.data capabilities, use the following notation:
'data.read.' + standard name + '.' + name of the category + '.' + name of data object
The data objects are application-specific. The available data objects and fields within the the data object are based on what you define in your application code. Data objects can have multiple fields. You specify access to each data object by its name.
For example, if you could have the following data objects:
To grant the search capability to the
car_fuel_level data objects, here's what
the capabilities would look like:
To grant the read capability to the
car_alarm data object, here's what
the capability looks like:
search.dataare the names of the capabilities to extend
defaultis the name of the standard
stateare the categories
car_alarm, and car_fuel_level are the data object names
You can also specify wildcards (
*) to indicate all data objects in a category. For example,
you could grant
data.read.default.state.* to specify both the
data objects (and any other data objects) under the
To extend the
message.create, you can append a period ('
.') and a
string to it. You must grant a separate capability for each message that you want to send.
Note: You can't use a wild card (
*) to specify multiple capabilities like
For example, lets say that a target device handles the message types of
message.create.hello must be granted to the sending device if you
wanted it to send the message type of
hello. However, if you wanted
the sender to send all message types, you must grant the capability to send each
message type individually. In this case, you must grant capabilities for both
message.create.bye. If you had a third message type,
you would need to grant that message type as a capability as well.
Before you configure an entity to grant another entity a capability (permission) to perform an action on it, you should identify:
- What the action is (in general, the name of the capability maps to the action on the entity).
- Who gets to perform the action (the entity that you grant the capability to).
- What target the action can be performed on (the entity you add the capability on).
- (Optional) A date and time of when the capability expires on (or is removed). If you don't specify an expiry time, the capability assigned won't expire.
You can grant capabilities to entities so that they can perform actions on a target entity. For example, if Entity B is granted the read capability to entity A, Entity B is able to read information from Entity A (target). Capabilities can be granted using the REST API or using the administration console.
For more information about how to grant capabilities, see the information for the respective entity as follows:
Here's an example to help illustrate how to assign a capability that expires at a specific time:
Bob is going to borrow Alice's car. Alice has parked the car in a public parking lot, and Bob is going to pick it up after work. To make it easy for Bob to find her car, Alice gives Bob permission to read the GPS position of her car for the next 23 hours (the current date and time is April 30 at 12:00 PM). In this case, both Bob and Alice are running the same application. Here's how the capability would be configured:
- Granted on the target device: Alice's car
- Action or capability name:
- Grant type: User
- Entity granted to: Bob
- Expiry (time-to-live): May 1 at 11:00 AM
Note: On the administration console, you can see the granted capabilities under the My devices section on the Dashboard in the administration console. For more information, see View devices associated to your account.
Use capability inheritance
Capabilities can be inherited based on where they are granted in to the hierarchy of entities. The hierarchy simply shows how entities to relate to each other. Capabilities that are granted to entities higher in the hierarchy are passed down (inherited) by more devices. For example, if you grant a capability to an organization, all devices of that organization inherit that capability. If you grant a capability to an application, only the devices of that application type inherit the specified capability.
Capabilities can be granted to organizations, applications, devices, and tags. The capabilities that are granted to an entity are useful only for device entities, which are the only entities that can perform actions.
The capabilities that a device has is the superset of capabilities granted to:
- the organization, to which the device belongs
- application, to which the device belongs
- the user logged into the device (if the
inherit_permissionwas specified as part scope during user-based authentication)
- the tags that are applied to the organization, application, user, and device
For example, the following capabilities are granted to these entities:
- Tag A is granted permission
- Tag B is granted permission
- Organization C is granted
app.readand tagged with Tag A
- Application D is granted
app.writeand tagged with Tag B
- Device E is granted
- User Alison logged is granted
- User Bob is granted m
The superset of capabilities for the device would be the following if Alison logged in to the device:
However, if Bob logged into the device, his capabilities would be:
Note: It doesn't matter if a capability appears more than once in the hierarchy.
The following illustration shows how capabilities are a superset based on the entity hierarchy based on the above example:
Use tags to simplify permission management
Tags are entities that can be granted capabilities, but can also be the target of a capability. When you apply a tag to an entity, the capabilities are transposed to the tagged entity. This concept is described later, but here are some scenarios to help you understand when it's best to use tags:
- You have multiple capabilities that need to be granted to multiple devices. Rather than grant the capabilities individually to each device, you can grant a set of capabilities to a tag. Then, use that tag to grant the set of capabilities to each device.
- You may need to add or remove capabilities to multiple devices. If you tagged the devices with a tag, you could update the tag rather than update each device individually. Updating the tag results in multiple devices being updated simultaneously (and consistently) in one step.
The user, device, application, and organization entities can have tags applied to them. You can apply one or more tags on an entity. Tags can be either exposing or non-exposing. Here's the difference:
Non-exposing: Non-exposing tags can be granted capabilities to perform actions on other entities. When an entity is tagged with a non-exposing tag, the capabilities are transposed to the tagged entity. This transposition causes the tagged entity to be granted the same capabilities that were granted to the tag.
To use a non-exposing tag, it must have the
tag.grantcapability (or the organization/user must have the
tag.grantcapability that that tag belongs to). The entities that apply a non-exposing tag to don't require any special capabilities. For example, a non-exposing tag, is granted the
device.readcapability to application A (target). When an entity is tagged with XYZ, it's granted the
device.readcapability to application A.
Exposing: Exposing tags work like non-exposing tags to grant capabilities on targets. In addition, exposing tags can be targets that grant capabilities to other entities. Therefore, any capabilities that were granted by an exposing tag, as well as any capabilities granted to the tag are transposed to the tagged entity. The effect of the transposition is that the tagged entity is granted the same capabilities that were granted to the tag and the tagged entity grants the same capabilities to other entities as the tag. The latter makes that tagged entity accessible to other entities because capabilities are granted that weren't there before tagging. This reason is why these tags are called, exposing tags.
To use an exposing tag, it must have the
tag.grantcapability (or the organization/user must have the
tag.grantcapability that that tag belongs to). Depending on the entity type that you apply an exposing tag to, that tagged entity must have the
device.tagcapability for users, organizations, applications, and devices respectively. Because capabilities are granted to other entities that weren't there before applying the tag, the addition capability is required on the tagged entity.
For example, an exposing tag is granted
device.readon Application X, but the tag itself, also grants
message.create.updateto Application X. The following transposition occurs when Application Y is tagged:
- Application Y has the
device.readcapability on Application X (target)
- Application X is granted the
message.create.updatecapability by Application Y
- Application Y has the
Here are some examples to further illustrate the difference between the two scenarios:
Use of a non-exposing tag is useful when you want only the capabilities
that have been granted to a tag to be granted to the tagged entities.
For example, a non-exposing Tag XYZ is granted the
to Application A. After Application B and Device C are tagged with XYZ,
both entities have the
message.create.ping capability to Application A (target). The
following diagram illustrates this concept:
You can use an exposing tag like a non-exposing tag to grant capabilities. This means that the entity that you tagged has the same capabilities that were granted to the tag. An exposing tag can also be a target that grants capabilities to other entities. Entities that are tagged with an exposing tag also grant the same capabilities to entities as the tag does.
For example, Application X is granted capability
message.create.update on Tag ABC.
If Application Y and Device Z are tagged with ABC, Application X is granted the
message.create.update capability on Application Y and Device Z.
The following diagram illustrates the concept of how an exposing tag grants the same capabilities
to entities that the tag does:
Use associations to simplify capability management
Another way to simplify the assignment of capabilities to devices is to use associations. Associations grant capabilities to an entity only when both the granting entity (target) and entity being granted the capability are associated to the same user. Associations are useful when you want the BlackBerry IoT Platform to validate the relationship of the entities and when you don't know the UUID of the device to grant a capability to (usually because the device entity hasn't been created). As a user adds more devices, capabilities are automatically granted between devices that they log in to. For example:
All devices that are logged in to by the same user are automatically granted capabilities to read information from each other. Granting a capability as an association by the same user makes this possible.
Association by same user: These associations dynamically assign capabilities between
devices that belong to the same user–no matter what organization the user belongs to.
This assignment of capabilities helps simplify capability management because you won't have to
explicitly assign capabilities to new devices that a user logs in to. For example,
Alice owns a car that has an application running, which shares
its location. The application entity has associations created that grant
message.create.unlock capability that belong to the same user.
data.read capability allows for other applications belonging to
Alice to read the location of the car. The
allows an unlock car message to be sent to the car.
Here's an example that illustrates how associations work when a capability has an association configured as by user:
Application X grants
read.device and also configures the grant as an
association by same user to Application Y. As a result, the devices of Application
Y are only able read information of the devices of Application X only if they associated to
the same user. If you granted the capability without creating the
association by user, it would mean that any device of Application Y could read data on
any device of Application X.
Here's a diagram that shows multiple devices how capabilities are granted between devices belonging to the same user.
Here's a practical example of how an association by same user would be useful:
Alice just purchased a smart phone that has an application that connects to the BlackBerry IoT Platform. The applications that run on the smart phone and on the car have an association belonging to the same user. After Alice logs in to the application on the smart phone, a new device entity is created on the BlackBerry IoT Platform. That new device is automatically granted capabilities to read the location of the car because the car application was configured to grant the read capability as an association by same user. No additional configuration was required.
In the scenario described above. If the car application didn't grant the capability by association, that new device would need to be explicitly granted to Alice's device on the BlackBerry IoT Platform.
Now you might wonder why you wouldn't simply configure the car application to grant the capability to read data to the smart phone application. They key point to remember is that when you create associations, granting of capabilities based on whether both devices belong to the same user. If you had configured the car application to grant the smart phone application the capability to read the GPS location; then those smart phone applications (no matter who was logged in), would be able to read the location of all car applications. This configuration is probably not what you want or intended.
For more detailed steps about creating and configuring associations, see the following documentation:
- Assigning capabilities (for instructions about creating an association for the capability)
Best practices for managing capabilities
Capabilities are required to handle the network of devices and what they can do with one another. Depending on your business rules, you can choose to handle how permissions are configured. However, the following are some general good practices:
We recommend that you use inheritance (apply permissions as high up the entity hierarchy as possible), as this can greatly simplify managing permissions. For example, if you have an application that can manage vending machines, you may want to grant a permission to the application rather than every device. If you had millions of devices, managing the change of permissions would be a very difficult process if you applied permissions at the lowest level.
Keep in mind that capabilities are always inherited (device inherit from the application and the organization the application belongs to). Devices can also inherit capabilities from the user when the
inherit_userparameter is passed as part of the
scopeparameter during user-based authentication. Understanding what is inherited helps you to determine what additional permissions are required and how to best grant the proper capabilities.
Use tags to group multiple capabilities that you want and transpose capabilities to tagged entities:
- to grant on entities (targets)
- specify capabilities for the tagged entity to grant to other entities
Use associations to dynamically grant capabilities based on the relationship of entities to the user or organization. Use associations to match the business rules you require.