BlackBerry Spark Communications Services Guide

User Management

Your users are represented within BlackBerry Spark Communications Services by an identity. These identities represent users within the BlackBerry Infrastructure only. Each identity's primary identifier is called a regId. Your application can associate your existing user accounts or social networks with these identities using the regId.

Architecture Overview - User Management


Your application associates its users to Spark Communications Services identities through a process known as registration. The first time your application client endpoint registers a user with the SDK, a Spark Communications Services identity is created for the user. This new identity is assigned a regId that uniquely identifies it within the BlackBerry Infrastructure. The regId assigned to an identity will not change when your application registers another endpoint for the same user.

Identity Mapping

Spark Communications Services maintains the mapping between its regIds and your application's users. The SDK provides APIs that let your application query this mapping on Android, iOS, and JavaScript. The Support libraries include helper classes built on these APIs that simplify these queries for you even further.

Maintaining Your Own Identity Mappings

In addition to the regId, the SDK also returns a registration token to your application. When your application is maintaining its own user account identity mapping, this registration token must be used to verify the mapping between the application user and regId. The registration token is a JWT token signed by the BlackBerry Infrastructure that can be validated with the public key available at one of the JWKS URLs listed below. A trusted part of your application infrastructure must verify the registration token and use the information it contains to create a trusted association.

Environment JWKS URL

Typically, your application would store these account associations behind a cloud service accessible to all your application endpoints, and the cloud server that has the access rights to create those association records would verify the registration token. Verifying the registration token in an application client endpoint is not recommended, since you would need to have complete trust in the integrity of the client before using its result.

The registration token body contains the following claims.

JWT Claim Description
sub The user ID from the application's identity provider.
domain Your application's domain ID.
iss The token issuer. This will be BBM.

The regId of the Spark Communications Services identity associated with the user ID.

exp The token expiry time.
iat The token issuing time.

Contact Discovery and Management

Applications have their own ways of discovering and managing contacts and relationships. For example, a technical support application may want to allow communication between its customers and a predefined list of technical support agents, whereas a chat application may have a list of favorite contacts or integrate with a corporate address book.

To facilitate the different needs your application may have, Spark Communications Services does not manage your user identities. Your application finds contacts or other user relationships in ways that make sense to you.

For example, to start a chat with a user, your application first locates the target user in its user account records. Within that record, your application obtains the associated regId identifier that was securely recorded for that target user when they first registered their account with the SDK. Your application then asks the SDK to start a chat with that regId. User Management Database

Example User Management Integrations

The Support libraries that come with the SDK contain code that you can use to to help your application use two popular APIs.