Skip to main content

Teams

The Teams feature of nRF Cloud enables you to set up teams of users who can interact with the team's devices, setting different access levels for individual users.

Your Team ID can be found on your Teams page on nRFCloud.com. This ID is also known as your "tenant id" in the response of a call to the FetchAccountInfo endpoint.

Concepts#

TermDefinition
UserA person with a login account to nRFCloud.com, the portal for nRF Cloud. Each account is unique to a particular email. Although a person might create different accounts with different emails, we consider each account to be a different user here, for clarity.
AccountThe configuration settings for a user of nRF Cloud, such as their password, team associations, and team-specific permissions.
TeamContains a set of user accounts and a set of devices. A user can be a member of multiple teams, with different permissions for each team. A device is always a member of just one team.
Team MemberA user acting within a specific team. For example, a team member has a role for that team which is independent of their roles in other teams.
RoleA team member is assigned a role for that team: "admin", "editor", or "viewer". See below for more details.
Device GroupA name you can associate with a set of devices. You can also associate a team member with a device group, which limits the devices they can access. See below for more details.
PermissionsA team member's assigned device groups and role, which defines what they can do on what devices.
API KeyA unique identifier provided for a team member, allowing them to access the devices in that team using the nRF Cloud REST API, subject to their permissions for that team.

Team Creation and Invitations#

When a user creates a new account, a team will be created for them. They will be an admin of that team as the only team member so far.

The user can then invite other users to join the team, by their email addresses. The inviting user chooses a role that will be assigned to the invitee if they accept the invitation to the team, and optionally a set of device groups to assign to the invitee. An invitation will be sent to the invitee's email, with a link to accept the invite and join the team.

See "Invitations" below for more detail.

Leaving a Team#

A user may leave a team at any time.

A user may be removed from a team by a team member with an admin role.

If a user loses all associations to teams, then the next time they log in, a new team will be created for them, as if they just created their account.

Teams can have multiple team members with the admin role. There is no concept of a single "owner" of a team. When an admin invites another user to the team with the admin role, the user will have the same abilities that the inviting admin has.

If the last team member that has an admin role leaves the team, then the team will be automatically deleted. See "Deleting a Team" below.

Deleting a Team#

If a user is an admin on a team, they can delete the team. All users will be removed from the team, all associated devices will be deleted, and any outstanding invitations will not be accepted.

If a user deletes their only team, then they will be logged out. The next time they log in, a new team will be created for them, as if they just created their account.

Roles#

A team member has one role. If a user is a member of multiple teams, they have a role for each team.

The role defines what they can do within that team:

Viewer Role#

  • Can view device information
  • Can regenerate their own nRF Cloud REST API key for a team they're on

Editor Role#

  • Can do all "viewer" role actions, plus the following:
    • Can generate a device certificate and use it to provision a device
    • Can add and remove devices, and act upon them, such as:
      • Perform a scan with a Bluetooth gateway
      • Rename a device
      • Attach an image to the device as shown in the list of devices
      • Interact with a device to change its characteristic values, such as enabling sensor output or changing the light pattern.
    • Can add and remove SIM cards
    • Can add and remove Bluetooth gateways

Admin Role#

  • Can do any actions and is not restricted
  • Can do all "editor" role actions, plus the following:
    • Can invite users to a team by email address, which sends an invitation email
    • Can cancel an invitation they created before the invitee accepts
    • Can remove team members from a team
    • Can modify team information, such as the name
    • Can change a team member's role
    • Can change a team member's assigned device groups
    • Can add, change, and delete device groups assigned to a device.
    • Can update firmware on a device
    • Can delete a team
      • All associated devices and user relationships will be deleted, and any outstanding invitations will not be accepted.

nRF Cloud REST API Access by Role#

Each team member is provided an API key that grants them permissions to use the nRF Cloud REST API for devices in that team.

Device access using the nRF Cloud REST API is restricted by the API call and the team member's role:

nRF Cloud REST APIAdminEditorViewer
Account Informationโœ”โœ”โœ”
Account Certificatesโœ”
API Usage Informationโœ”โœ”โœ”
Devices (all types):
> ListDevices requestโœ”โœ”โœ”
> FetchDevice requestโœ”โœ”โœ”
> all other requests in this sectionโœ”โœ”
Devices (Gateway)โœ”โœ”
Devices (Bluetooth LE)โœ”โœ”
Devices (IP/LTE)โœ”โœ”
Device Firmware Updates (FOTA)โœ”
Bulk Operation Statusโœ”โœ”โœ”
Location Servicesโœ”โœ”โœ”
Messages:
> ListMessagesโœ”โœ”โœ”
> SendDeviceMessageโœ”โœ”
Get REST API Specification (OpenAPI/Swagger JSON)โœ”โœ”โœ”

Team manipulation must be performed interactively using the nRF Cloud UI. It is not provided by the nRF Cloud REST API.

Device Groups#

The device groups features allows you to organize and manage access to your devices. A device group is an arbitrary user-defined name (no space characters). It must be unique among device groups within a team.

You can assign a device group to a device or to a user. Users can see devices that are assigned to any of the same groups they are.

The nRFCloud.com interface allows grouping, sorting, and filtering of device lists by device groups.

FOTA#

The Firmware Update (FOTA) service, requires you to group the devices included in an update by assigning them to a device group.

Device access restriction#

If no device groups are assigned to any devices or users, then all users will be able to access all devices.

Device groups can be used alongside roles to define which users can access which devices. Roles are a general restriction while device groups are a more specific restriction.

Only a user with an admin role can assign groups to devices and users. Groups only affect non-admins (editors and viewers). Admins are never restricted.

Devices and users can have any number of groups assigned to them.

The rules of access to a device for a non-admin user depend on the groups assigned to the device and user, as shown in the table of examples below.

User's groupsDevice's groupsDevice visible to user?
nonenoneyes(1)
group-Anoneyes(1)
nonegroup-Bno(2), except for (4)
group-Agroup-Bno(3), except for (4)
group-A,group-Bgroup-B,group-Cyes(3)

Descriptively:

  1. Any user can access a device that has no groups assigned.
  2. If that user has no device groups assigned, they cannot access a device that has any device groups assigned. They can only access devices with no groups assigned.
  3. If that user has any device groups assigned, they can access a device that has any of the same device groups assigned. They cannot access a device that has device groups but none of those groups match any groups assigned to the user. They can still access devices with no groups assigned.
  4. The exception is for Bluetooth LE devices: Since they are attached to a gateway that may handle any number of Bluetooth LE devices, it's important for all users to see all devices attached to a gateway. If the user can see the gateway (using the rules above), they can always see all devices attached to it, regardless of the device groups assigned to them. Access to those gateways and Bluetooth LE devices are limited by roles and device groups.

The REST API requests ListDevices and FetchDevice will not show any of the device's device groups that the requesting user is not assigned to.

An editor user is allowed to delete devices. The exception is when the device is a member of a group that the editor is not a member of, and that group has any users assigned to it. In that case, deletion is not allowed.

You can organize devices into groups without restricting user access, by giving all users the admin role, or by adding all device groups to all editor and viewer users.

An admin can restrict a device to admin-only access by assigning it to a device group that will never be assigned to a non-admin.

Invitations#

Inviting a user to join a team is restricted to admins. To invite a user, the admin chooses "Create Invite" from the Teams page, enters the user's email address, picks the user's role, optionally assigns device groups to the user, and clicks the "Send" button.

The invited user (invitee) will receive an email stating that they've been invited, and a link to accept the invitation. The link will include an invite token that is used to look up the invite information.

The link will take the user to the nRFCloud.com login page. The invitee might not have an account on nRF Cloud yet. If they do not, they must create one before joining the team. After the user logs in, they will be prompted to join the team. They can either accept the invitation or decline it.

For users that have just created a new account:

  • Clicking Accept will join them to the team. That will be their only team.
  • Clicking Decline will cause a new team to be created for them. They will be the only team member.

For users that already have an account:

  • Clicking Accept will join them to the team. Their other teams will be unaffected.
  • Clicking Decline will log them in to their most recently used team. Their team associations will be unaffected.

An invitation expires 24 hours after being sent. The user cannot join the team by clicking the link after that time.

Invite Email#

Below is an example email inviting a user to join the team as an editor.

From:    nRF Cloud <invites@nrfcloud.com>To:    joe24310@gmail.comSubject:    Invitation to collaborate on nRF Cloud
Hello,
Lisa Thomason has invited you to join their team (Acme Engineers) on nRF Cloud.
Click the link below to sign in and join the team.
https://nrfcloud.com/?inviteToken=NThjODIzDGMtMTVmNS00YjRhLWIzOTItMTEzMVIxODFhOWNl&inviteeEmail=joe24310%40gmail.com
Note: Your invitation will expire in 24 hours
You are invited with the editor role. You are allowed to:
*   Add/remove devices and SIM cards*   View device information*   Modify device groups on devices
Sincerely,
The nRF Cloud team

Managing Your Teams#

nRF Cloud has various elements that allow you to manage your teams where you are an admin, and to view your teams where you are an editor or viewer.

The best way to explore these elements of the interface is by taking the tour while logged in. It is shown the first time you select the Teams option from the "hamburger menu" located in the upper right corner of nRFCloud.com. If you have already taken the tour and want to see it again, go to the Teams page, click the settings (gear) icon in the upper right, and choose "Take a Tour".

A Typical Teams Use Case#

Here is a fictional use case to demonstrate how the teams feature might be used.

Business Plan#

Bob plans to launch an internet connected vacuum cleaner company. In addition to selling the vacuum cleaner, Bob is planning a "vacuum cleaner service". The vacuum cleaner service will use a device with an nRF91 chip to report the status of the dirt bag and automatically order new bags when the bag is detected as full. The initial service will be just this simple "bag full feature" but Bob has ideas for future new features such as energy usage and reporting cleaning time.

Bob plans to use nRF Cloud to develop the vacuum cleaner firmware. His development team consists of 5 engineers that each will be using an nRF9160 Development Kit (DK).

In addition to the vacuums, Bob plans to offer his customers a free vacuum app on both the Android Google Play store and Apple App Store so that users can see various statistics about their vacuum habits and enable various features. Bob has hired an application development company to develop the phone applications.

Bob's company is a startup with a handful of employees with backgrounds in hardware, firmware and production, so initially he has decided to use nRF Cloud as his Internet of Things platform.

Bob is planning to test the FOTA and certificate management features of nRF Cloud during the development phase. Bob has negotiated a connectivity deal with a nationwide cellular provider which will supply the SIMs pre-activated for the vacuum cleaners.

Teams Setup#

Bob creates an account on nRFCloud.com. He then creates several Teams using the "Create Team" function. Each Team will include a set of employees of one or two companies devoted to one aspect of the product. Bob has the "admin" role on each Team.

  • Device Development - the 5 engineers (initially) developing the devices to be installed in the vacuum cleaners. At first, they will connect nRF9160 DKs to nRF Cloud. As development progresses, they will connect prototype and production vacuum cleaner devices to nRF Cloud.
  • User Application Development - the app development company's engineers who develop the phone apps.
  • Product Assembly - the technicians who program and test the PCB devices, and the factory technicians who assemble and test the PCBs in the deliverable products.
  • Production Device Support - the product maintenance and upgrade team provided by a third party company experienced in supporting IoT-based products. They handle problems shown by devices in vacuum cleaners in the field, engaging Bob's engineers when necessary.

Device Development Team#

Bob uses the nRF Cloud interface to send Invites to the tech lead and a backup person from his engineering team to become admins of the team he names "Device Development". These two people accept their invites by clicking the links in the emailed invites they receive.

The tech lead creates device groups within the team, named:

  • Development Kits
  • Prototypes
  • Release Candidates

The tech lead invites the other engineers to the team with the "editor" role, and assigns each of them to all of these device groups. As editors, they can add, remove, rename, and manipulate devices attached to their team the same way that the 2 admins can, but they cannot invite other people to join the team, remove team members, nor change anyone else's device group assignments or role.

The engineers developing the devices collaborate with the user application engineers to coordinate front and back end device usage. The device development admins invite the app developers to join the device development team in the viewer role. This role allows their apps to collect an inventory of the devices and to receive data from devices. While their apps will also allow sending messages to the devices to enable/disable their sending of data, those messages are out-of-band of the nRF Cloud system, so they do not need editor-level access to the devices. This prevents them from accidentally deleting or changing devices.

The device developers do not want the app developers to use unstable versions of the product, so the admins assign the app developers only to the device group named Release Candidates. The app developers and their apps cannot access devices in the other groups.

A device developer may flash new release-candidate firmware on a device using nRF Cloud FOTA services that currently has prototype-level firmware. After the firmware is updated, the developer (as an editor) can ask an admin to re-assign the device from the "Prototypes" device group to the "Release Candidates" device group. It can then be used by the app developers.

User Application Development Team#

Bob's company will periodically provide new release candidate and production-level devices to the app development company to use for their own app development, independently of Bob's engineers. The app company provides Bob the emails of two employees who will be the admins of the nRF Cloud team named "User Application Development" which Bob created. Bob invites them as admins of that team. After those admins join the team, Bob then removes himself from the team.

The app company's admins invite the other app developers as editors or viewers as they see fit. They create device groups to arrange their devices as they see fit.

Occasionally a device acts strangely, and they need to show one of the device developers to get their advice. At the time they set up their team, they invite one of the device developers to the team as a viewer. They also assign him to a device group that contains only the device(s) they need the device developer to see. Whenever they need to show something, the device developer switches their current team view to the User Application Development team. He can see those devices exposed by his assigned device group and collaborates with the app developers to diagnose the issue. If the device developer needs help from a co-worker, he asks one of the app developer admins to invite the co-worker to join the team. When the co-worker's access is no longer needed, the admin removes them as a team member.

Other Teams#

The Product Assembly and Production Device Support teams are set up similarly, with collaborations as needed.