User API

The User API is used to manage users and user profiles.

LIST

Required role: Read
Required privilege: Users.READ on one or more domains containing a User

Lists all users. There are three categories of users. Active users have access to login. Pending users have not been assigned domainName and roleName. Unconfirmed users have signed up but not visited the link in the confirmation email and set a new password. To retrieve all users regardless of category use the all category.

API Endpoint: [GET]: /users

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • attributes
    • ...: The attributes you want to get.
  • freeText: A string to filter results on.
  • category: Filter for the category of the user. Possible values are all, active, pending, unconfirmed. Defaults to active.
  • page: Page to list, i.e. pagination support.
  • size: Number of users to retrieve per page. If not set all users are returned.
  • sortProp: Name of attribute to sort by, defaults to userName

There are no required attributes but by including comma separated attributes you specify which attributes to get. You can choose from the following attributes. (userName | firstName | lastName | email | phone | locale | company | address | zip | country | roleName | domainName | data | roles | termsAgreed | dateTermsAgreed | termsVersion | createdAt | enabled | id)

Example attributes

attributes=userName,firstName

Response

A list of users where each item in the list have the following properties.

  • users: The list of users in the chosen category (active by default)

    • ...: The attributes you want to get.

  • totalPages: Number of pages available, support for pagination. If size was not set this will return 1.

  • page: The actual page returned. Will be set to 1 if neither size nor page

  • metadata

    • count: Includes the keys all, active, pending and unconfirmed where the values tell how many users are returned per category

CREATE

Required role: ReadWrite
Required privilege: Users.CREATE on the specified domainName

Creates a new user.

API Endpoint: [POST]: /users

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • userName: The user name of the user. Maximum length: 128 characters. required
  • firstName: The first name of the user. required
  • lastName: The last name of the user. required
  • email: The e-mail address of the user. required
  • locale: The locale of the user. This is an ISO639‑1 language code in lowercase and an ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or sv-SE. When not specified, it will default to en-US.
  • phone: The phone number of the user, needs to start with a country code (eg. +46) and cannot contain any whitespace or delimiters
  • company: The company that the user works at.
  • address: The address of the user.
  • zip: The zip code of the user.
  • city: The city of the user.
  • country: The country of the user.
  • roleName: The name of the role that the user has. ( Read | ReadWrite).
  • domainName: The name of the domain that the user should be assigned to. required
  • notes1: Additional notes field.
  • notes2: Additional notes field.
  • notes3: Additional notes field.

Example payload

{
  "userName": "demo",
  "firstName": "First",
  "lastName": "Last",
  "email": "noreply@telenorconnexion.com",
  "locale": "en-US",
  "phone": "+4631123456",
  "company": "Demo AB",
  "address": "Street 1",
  "zip": "12345",
  "city": "BigCity",
  "country": "Sweden",
  "roleName": "ReadWrite",
  "domainName": "root"
}

Response

  • userName: The user name of the user.
  • firstName: The first name of the user.
  • lastName: The last name of the user.
  • email: The e-mail address of the user.
  • locale: The locale of the user. Default en-US.
  • phone: The phone number of the user. optional
  • company: The company that the user works at. optional
  • address: The address of the user. optional
  • zip: The zip code of the user. optional
  • city: The city of the user. optional
  • country: The country of the user. optional
  • roleName: The name of the role that the user has. ( Read | ReadWrite )
  • roles: The roles that are assigned to the user. optional
  • domainName: The name of the domain that the user is assigned to.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domainName Returned if the user tries to add a user to a domain that the user is not authorized to see.
PROPERTY_REQUIRED userName Returned if no userName was provided.
PROPERTY_REQUIRED domainName Returned if no domain name was provided.
USER_USERNAME_EXISTS userName Returned if the user name that was provided is used by another user in the system.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.

GET

Required role: Read
Required privilege: Users.READ on the domainName of the specified User

Gets information about a user.

The only required attribute is userName to know which user to get. But any of the following attributes can be included to get other attributes about the user. (firstName | lastName | email | phone | locale | company | address | zip | city | country | roleName | domainName | notes1 | notes2 | notes3 | data | roles | termsAgreed | dateTermsAgreed | termsVersion | createdAt | enabled | id).

API Endpoint: [GET]: /users/{userName}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: The user name of the user to get, set in query path. required
  • attributes: A comma-separated list of attributes you want to get.

Example attributes

attributes=userName,firstName

Response

  • userName: The user name of the user to get.
  • ...: Other attributes you want to get. optional

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN Returned if the user tries to get a user that is assigned to a domain that the user is not authorized to see.
PROPERTY_REQUIRED userName Returned if no user name was provided.
USER_NOT_FOUND userName Returned if the user cannot be found.

WHOAMI

Required role: None
Required privilege: None

Gets information about logged in user.

There are no required attributes. But any of the following attributes can be included to get other attributes about the user. (firstName | lastName | email | phone | locale | company | address | zip | city | country | roleName | domainName | notes1 | notes2 | notes3 | data | roles | termsAgreed | dateTermsAgreed | termsVersion | createdAt | enabled).

API Endpoint: [GET]: /user

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • attributes: A comma-separated list of attributes you want to get. optional

Example attributes

attributes=userName,firstName

Response

  • userName: The user name of the user to get.
  • ...: Other attributes you want to get. optional

Errors

Key Params Property Description
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.

Required role: ReadWrite
Required privilege Users.UPDATE on the home domain of the specified user

This endpoint can be used in order to revoke consent that a user has given to the terms and conditions. A user can revoke their own consent. An administrator can revoke the consent of a user.

API Endpoint: [POST]: /users/{userName}/revoke-consent

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: The user name of the user to revoke consent for. required

Response

An empty object.

Errors

Key Params Property Description
PROPERTY_REQUIRED userName Returned if no user name was provided.
USER_NOT_FOUND userName Returned if the user cannot be found.

REMOVE

Required role: ReadWrite
Required privilege: Users.DELETE on the domainName of the specified User

Removes a user.

API Endpoint: [DELETE]: /users/{userName}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: A single username, set in query path. required

Response

No response

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN Returned if the user tries to remove a user that is assigned to a domain that the user is not authorized to see.
PROPERTY_REQUIRED userName Returned if no user name was provided.
USER_NOT_FOUND userName Returned if the user cannot be found.

UPDATE

Required role: ReadWrite
Required privilege: Users.UPDATE on the domainName of the specified User Optional privilege: Users.UPDATE on the specified domainName, if updating the home domain of the specified User

Updates a user. There is a possibility to disable an active user, using the enabled attribute as shown below.

These attributes can be deleted by including them with the value null: locale | phone | company | address | zip | city | country | roleName.

API Endpoint: [PATCH]: /users/{userName}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: The user name of the user, set in query path. required

Body

  • firstName: The first name of the user.
  • lastName: The last name of the user.
  • phone: The phone number of the user.
  • locale: The locale of the user. This is an ISO639‑1 language code in lowercase and an ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or sv-SE.
  • company: company that the user works at.
  • address: The address of the user.
  • zip: The zip code of the user.
  • city: The city of the user.
  • country: The country of the user.
  • roleName: The name of the role that the user has. ( Read | ReadWrite )
  • domainName: The name of the domain that the user should be assigned to.
  • enabled: Possible values true and false.
  • notes1: Additional notes field.
  • notes2: Additional notes field.
  • notes3: Additional notes field.

Example payload

This payload would require the optional privilege Users.UPDATE on myDomain (the domain specified in the request).

{
  "firstName": "First",
  "lastName": "Last",
  "locale": "en-US",
  "phone": "+4631123456",
  "company": "Demo AB",
  "address": "Street 1",
  "zip": "12345",
  "city": "BigCity",
  "country": "Sweden",
  "roleName": "ReadWrite",
  "domainName": "myDomain"
}

Response

  • userName: The user name of the user.
  • firstName: The first name of the user.
  • lastName: The last name of the user.
  • email: The e-mail address of the user.
  • locale: The locale of the user. optional
  • phone: The phone number of the user. optional
  • company: The company that the user works at. optional
  • address: The address of the user. optional
  • zip: The zip code of the user. optional
  • city: The city of the user. optional
  • country: The country of the user. optional
  • roleName: The name of the role that the user has. ( Read | ReadWrite ) optional
  • roles: The roles that are assigned to the user. optional
  • domainName: The name of the domain that the user is assigned to.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domainName Returned if the user tries to move a user to a domain that the user is not authorized to see.
PROPERTY_REQUIRED userName Returned if no user name was provided.
PROPERTY_NOT_DELETABLE Returned if a non-deletable property was sent to be deleted.
USER_NOT_FOUND userName Returned if the user cannot be found.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.

UPDATE_PROFILE

Required role: None
Required privilege: None

Updates the profile of the logged in user. Currently updating the password is not possible at this endpoint. To achieve that the user needs to invoke the FORGOT_PASSWORD and follow the email link as described above.

These attributes can be deleted by including them with the value null: locale | phone | company | address | zip | city | country.

API Endpoint: [PATCH]: /users/{userName}/profile

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: The user name of the user, set in query path. NOTE: You can only update the userdata of the currently logged in user. required

Body

  • firstName: The first name of the user.
  • lastName: The last name of the user.
  • locale: The locale of the user. This is an ISO639‑1 language code in lowercase and an ISO3166‑1 country code in uppercase, separated by a dash. For example, en-US or sv-SE.
  • phone: The phone number of the user.
  • company: The company that the user works at.
  • address: The address of the user.
  • zip: The zip code of the user.
  • city: The city of the user.
  • country: The country of the user.

Example payload

{
  "userName": "demo",
  "password": "demo",
  "firstName": "First",
  "lastName": "Last",
  "email": "noreply@telenorconnexion.com",
  "locale": "en-US",
  "phone": "+4631123456",
  "company": "Demo AB",
  "address": "Street 1",
  "zip": "12345",
  "city": "BigCity",
  "country": "Sweden",
  "roleName": "ReadWrite",
  "domainName": "root"
}

Response

  • userName: The user name of the user.
  • firstName: The first name of the user.
  • lastName: The last name of the user.
  • email: The e-mail address of the user.
  • locale: The locale of the user. optional
  • phone: The phone number of the user. optional
  • company: The company that the user works at. optional
  • address: The address of the user. optional
  • zip: The zip code of the user. optional
  • city: The city of the user. optional
  • country: The country of the user. optional
  • roleName: The name of the role that the user has. ( Read | ReadWrite)
  • domainName: The name of the domain that the user is assigned to.

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user tries to update the profile of another user.
PROPERTY_REQUIRED userName Returned if no user name was provided.
PROPERTY_NOT_DELETABLE Returned if a non-deletable property was sent to be deleted.
USER_INVALID_PASSWORD oldPassword Returned if a new password is provided but the oldPassword doesn’t match the password of the user.
USER_NOT_FOUND userName Returned if the user cannot be found.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.

UPDATE_USERDATA

Required role: ReadWrite
Required privilege: Users.UPDATE on the home domain of the calling user

Updates the customer user data of the currently logged in user

API Endpoint [PUT]: /users/{userName}/data

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: The username to update userdata for, set in query path required

Request

  • tcxn : Reserved usage for platform, do not override this property.
  • ...: Arbitrary object with data you want to store for the user. required

Example payload

{
  "<userdata>": {}
}

Response Output

  • attributes
    • tcxn: Reserved usage for platform.
    • ...: Arbitrary object with data you want to store for the user.

RESET_PASSWORD

Required role: ReadWrite
Required privilege: Users.UPDATE on the home domain of the specified user

Resets the password for the specified user which results in a link being sent by email to the user, that can visit the link to set a new password. The link is usable only once. If the link has expired, this endpoint can be invoked again. Note: Following a password reset, the user cannot login until the password has been successfully changed.

API Endpoint: [POST]: /users/{userName}/reset-password

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • userName: The username to reset set password for, set in query path required