Hardlinking of users


For end users that are customers of a specific Business Unit, we want to make sure we trust their phone number. That trust is established by the BU explicitly linking to a user with that phone number.

The benefits of establishing this trust is:

  • As we can be fairly certain the original owner of the phone is still in possession of it, we can allow a wider set of authentication methods that makes service access and profile maintenance smoother.
  • By being informed about the users relationship to the BU, we can avoid a new user getting ownership of a previous account when the number churns.

You already are encouraged to link to a specific user. This is done by creating an 'account' entity on a specific user in the global backend. This link will enable you to get user events such as changing password and other information.

To indicate that the link is establishing the trust of a particular phone number, the optional parameter msisdn on the account entity is included.

An API request to add a link from Business Unit TheBU on the user 6005040030201 for the phone number 1234567 would look as follows:

POST /id/users/6005040030201/accounts HTTP/1.0
Content-Type: application/json

    "type": "TheBU",
    "userid": "BU specific identifier",
    "msisdn": "1234567"

The response to a successful hardlink will be 201 CREATED. The request may fail with 409 CONFLICT if the msisdn is already hardlinked on another user.

When to do hardlinking

Hardlinking should be done by the BU in two circumstances:

  • When creating a new user with an API call (POST to /id/users)
  • When discovering a user through a UserAnnounce event

On creation

If the user is created by the BU, they have full control over the lifecycle of the user. Assuming that a BU will only create users for its own customers, this is an ideal time to establish trust by hardlinking the user.

On UserAnnounce

When a user is created somewhere in the global ecosystem, for instance by registering at a service, a BU may optionally receive an event on the queue due to the msisdn-prefix of the user. This will be an event of type UserAnnounce, and it will contain both the msisdn and the userid of the user.

Hardlinking on UserAnnounce

When to remove hardlinking

The BU hardlink should be removed when the BU can no longer claim the stability of the phone. There are two primary cases where this happens:

  • The phone number is reused. If the BU through their integration removes a phone record on the User, they should also remove the BU hardlink for that number. Removing the phone indicates that the user is no longer a customer of the BU for that particular phone. This also frees up the BU to reuse the phone number in hardlinking to another user in case of number reuse.
  • The user churns. If the user stops being a direct customer of the BU, the hardlink should be removed, even if the number is preserved and ported to another operator. This indicates that even though the user still has the number in question, and for instance can use it as a login name, the BU does not claim that the person controlling it is the same as before. Removing the hardlink will disallow the user to perform simple login with a PIN round-trip, or easy login that is based on trusting the phone number.