The CONNECT accounts API

The accounts are a way for a Business Unit or other 3rd party, to link to a User. This link provides various benefits to the 3rd party, and to the end-user.

When a BU links to a user, they can attach their internal user-id to provide information about the relationship between the global backend user instance and a user in their own customer database.

In addition, the BU can add an msisdn to the link, indicating that the customers phone with that phone number is controlled by the BU. This gives a level of trust to the phone, and allows the end-user to perform authentication with the phone using a PIN round-trip. It also allows us to trust that the user/owner of the phone does not change, giving access to a users content to a new person.

When establishing a link to a User, the 3rd party will be informed about certain events related to the user on the event queue. This includes information such as the user changing their real name or email etc.

When in possession of a global backend userid, the 3rd party can create a link by submitting an account object. The account object contains the following fields:

  • type: This is an identifier for which 3rd party is the external party. This will typically be the BuID of a business unit.

  • userid: This is the external user id of the user in the database of the external party. This should be sufficient context for the external party to point to a user in their own system.

  • msisdn: If the 3rd party is a BU and the CONNECT user has a phone subscription with that BU, this field is used to indicate which phone number the BU has provided to the user.

Accounts 

Account collection resource 

The account collection contains all the user’s linked accounts.

Create a new account
/id/users/{connectId}/accounts

Add a new account to the CONNECT user identified by connectId.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

  • Request
  • Headers
    Content-Type: application/json
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
    Body
    {
  "type": "BUID",
  "userid": "BU local ID",
  "msisdn": "phone hardlink if any"
}
  • Response  201

  • The account has been created.

    Headers
    Content-Type: application/json
    Body
    {
  "type": "BUID",
  "userid": "BU local ID",
  "msisdn": "phone hardlink if any"
}
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404

  • The user you are trying to add an account to, does not exist.

    Headers
    Content-Type: text/html
  • Response  409

  • An attempt was made to create an account that already exists. This is due to either the {type,userid} tuple having been used before, or the msisdn already being set for another user.

    Headers
    Content-Type: application/json
Get all accounts
/id/users/{connectId}/accounts

Retrieve a list of all accounts stored on the CONNECT user.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.account.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200

  • The response contains an array of accounts named account.

    Headers
    Content-Type: application/json
    Body
    {
  "account": [
    {
      "id": "5986168930941542400",
      "generation": 5986168930941542000,
      "href": "https://api.telenor.io/id/users/5529855082117468160/accounts/5986168930941542400",
      "link": [
        {
          "rel": "self",
          "href": "https://api.telenor.io/id/users/5529855082117468160/accounts/5986168930941542400",
          "type": null,
          "idref": null
        },
        {
          "rel": "user",
          "href": "https://api.telenor.io/id/users/5529855082117468160",
          "type": null,
          "idref": null
        }
      ],
      "type": "TNN",
      "userid": "tnn_mobile_000031748151",
      "secret": "$2a$04$Lm.rDrdpdUMTIS0ht0gGBeGqJ2UG4JrBFd4.07WDgr1N0kW6jo3US",
      "password": null,
      "msisdn": null
    }
  ]
}
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404

  • The CONNECT ID can’t be found.

    Headers
    Content-Type: text/html

Account resource 

Retrieve account
/id/users/{connectId}/accounts/{accountId}

Retrieve a single account.

Supports both Bearer and Basic authentication schemes. Requires OAuth scope value “id.user.account.read” when using Bearer scheme.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    accountId
    string (required) 

    The ID of the account.

  • Request
  • Headers
    Accept: application/json
    Authorization: Bearer <access token>
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": "234534534534",
  "type": "BU ID",
  "userid": "External BU ID",
  "msisdn": "15551234"
}
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Bearer realm="telenordigital", error="invalid_token", errorDescription="The access token is expired, revoked, malformed or otherwise invalid"
  • Response  404

  • The CONNECT ID or account can’t be found.

    Headers
    Content-Type: text/html
Remove account
/id/users/{connectId}/accounts/{accountId}

Remove the account on the CONNECT user. This should be used when a claim to a user being a customer is not longer valid.

  • Parameters
  • connectId
    string (required) 

    The CONNECT ID of the user.

    accountId
    string (required) 

    The ID of the account.

  • Request
  • Headers
    Accept: application/json
    Authorization: Basic <Base64 encoding of username:password>
  • Response  204

  • The account has been removed from the CONNECT user. Note that you will get this response regardless if the account existed or not.

    Headers
    Content-Type: application/json
  • Response  401
  • Headers
    Content-Type: text/html
    WWW-Authenticate: Basic realm="Sylfide API"
  • Response  404

  • The CONNECT ID used in the request is unknown.

    Headers
    Content-Type: text/html

© 2017 Telenor Digital AS