User Management V4 API
- Garrick Lam (Unlicensed)
- Naveen Hosaagrahara Srinivas (Unlicensed)
- Thomas Langenskiold
Introduction
This section describes BSS communication with User Management API
Authentication and authorisation
All BSS endpoints support API key authorization. The header named 'Authorization' with content "Apikey PUT_YOUR_KEY_HERE" must be passed with request.
In addition to API key authorization some clients can have IP white listing feature enabled, which will allow access only from specific IP's.
Both API key and IP addresses allowed list are customer specific data and you should contact support person to obtain those.
Endpoints overview
Endpoint | HTTP method | Purpose |
|---|---|---|
| /api/user/management/v4/users | GET | Get an index of users |
| /api/user/management/v4/users | POST | Create a new user |
| /api/user/management/v4/users/{user_id} | GET | Get user by id |
| /api/user/management/v4/users/{user_id} | PATCH | Update user by id |
| /api/user/management/v4/users/{user_id} | DELETE | Delete user by id |
Entities
User Resource
Up-to-date resource schema could be found on API documentation page User Management API under schemas section.
Attributes
- name: full name
- user_flags: predefined user flags for features (e.g.: LICENSE_PURCHASE_RESTRICTED)
- contact_details:
- email: email address
- telephone_number_E123: telephone in E.123 notation
- registration_information:
- registration_state: default is UNREGISTERED. Only REGISTERED state is allowed to login.
- registration_time: (read-only) user registration time in epoch timestamp
- external_id: external customer identifier for reference ("cid" in legacy endpoints)
Relationships
Each of user should have one default_user_profile created automatically during user creation.
Meta
- security
- user_password: User Management v4#/User/CreateUser supports creating user account with a given password, which can be useful e.g. for generating test accounts. It is recommended to let real users set their own password through password set/reset email.
Use cases
Use management API to fetch, create, update and delete Users
User Management API
Some notes:
- Only user with REGISTERED registration_state can login with the service. You can use UNREGISTERED state to pre-provision users before they are ready to be used, but the registration state must be changed through a PATCH request before the user can be used.
- If the user accounts are created without password, use User information v2#/Password%20Reset/requestResetPassword endpoint to send a reset user password email to the users, to set the user password before first login.
- Users can be temporarily disabled by setting registration_state to DISABLED, this prohibits the user from logging in, but their data is retained.
- Deleting a user will irrevocably delete all their data, including licenses, preferences, recordings and playback info.
Migration guide
| Purpose | Legacy user management | User Management V4 | ||
|---|---|---|---|---|
| Get user accounts | GET | /api/management/user | GET | /api/user/management/v4/users |
| Create user account | POST | /api/management/user | POST | /api/user/management/v4/users |
| Update user account | PUT | /api/management/user/{email} | PATCH | /api/user/management/v4/users/{user_id} |
| Delete user account | DELETE | /api/management/user/{email} | DELETE | /api/user/management/v4/users/{user_id} |
Note
Postman collection
Table of Contents
Child Pages