This documentation supports releases of BMC Helix Portal up to December 31, 2021. To view the latest version, select the version from the Product version menu.

User endpoints in the REST API

The following section provides a list of supported endpoints for users and details about running these endpoints. For more information about users, see User-access. 

Before you run an endpoint, you must authenticate yourself. For more information, see Access-and-authentication-for-the-REST-API.

GET /ims/api/v1/userinfo
Get details about the logged-on user
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/userinfo
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Successful response
{
  "user_id": "559311632847350",
  "first_name": "Stuart",
  "last_name": "McGill",
  "full_name": "Stuart McGill",
  "principal_id": "administrator",
  "email": "Stuart@bmc.com",
  "user_status": "ENABLE",
  "type": "PERSON",
  "auth_type": "IMS_AUTH",
  "tenant_id": "1903033870",
  "tenant_name": "csbmc",
  "trial_expiry_time": "2020-10-21T11:48:09.836578",
  "roles": [
    "407740385418284",
    "826790797684840",
    "637441862780368"
 ],
  "groups": [
    "961971749430087"
 ],
  "permissions": [
    "*"
 ]
}
GET /ims/api/v1/users
Get all users under a tenant

You need list permissions to be able to run this API endpoint.

Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/users?page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=asc&userTypes={usertypes}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "records": [
    {
     "user_id": "811597463253119",
     "principal_id": "ma",
     "tenant_id": "1324710355",
     "email": "mike@gmail.com",
     "first_name": "Mike",
     "last_name": "Adams",
     "full_name": "Mike Adams",
     "status": "ENABLE",
     "type": "PERSON",
     "auth_type": "IMS_AUTH",
     "created_date_time": "2020-09-30T07:09:29.988165"
    },
    {
     "user_id": "238076465729611",
     "principal_id": "HaRoEgdK",
     "tenant_id": "1324710355",
     "email": "harvey@gmail.com",
     "first_name": "Harvey",
     "last_name": "Ross",
     "full_name": "Harvey Ross",
     "status": "ENABLE",
     "type": "PERSON",
     "auth_type": "IMS_AUTH",
     "created_date_time": "2020-10-05T17:48:01.389266"
    },
    {
     "user_id": "135817356805491",
     "principal_id": "X4DT1TV81PF7SRCQQUJU0U14EI1FO7",
     "tenant_id": "1903033870",
     "first_name": "1903033870@1602071325210",
     "full_name": "1903033870@1602071325210",
     "status": "ENABLE",
     "type": "API",
     "auth_type": "IMS_AUTH",
     "created_date_time": "2020-10-07T11:48:45.231176"
    }
  ],
 "_metadata": {
   "page": 0,
   "records_per_page": 1000,
   "page_count": 1,
   "total_count": 3
  }
}
Unsuccessful response
{
 "timestamp": "2020-10-07T18:39:26.757790Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "Invalid user type value provided:: XYA"
}
POST /ims/api/v1/users
Create a user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "auth_type": "string",
 "email": "string",
 "first_name": "string",
 "full_name": "string",
 "last_name": "string",
 "principal_id": "string"
}
Example request body
{
  "auth_type": "IMS_AUTH",
  "email": "patrickja@gmail.com",
  "first_name": "Patrick",
  "full_name": "Patrick James",
  "last_name": "James",
  "principal_id": "pjames"
}
Parameters
Successful response
{
 "user_id": "484195167480201"
}
Unsuccessful response

Scenario 1: You try to create a user with the same details as that of an existing user.

{
 "timestamp": "2020-10-07T19:08:09.822112Z",
 "code": 500,
 "message": "INTERNAL_SERVER_ERROR",
 "error": "RSSO Service error - User already exists."
}

Scenario 2: You try to create a user without one or more of the mandatory parameters.

{
 "timestamp": "2020-10-07T19:09:55.751212Z",
 "code": 2300,
 "message": "Users First Name and Last Name are required",
 "error": "BAD_REQUEST"
}
DELETE /ims/api/v1/users/{id}
Delete a user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T19:18:27.449791Z",
 "code": 1100,
 "message": "User not found.",
 "error": "Failed to find user by id [980110334580797]"
}
GET /ims/api/v1/users/{id}
Get details of a specific user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
  "user_id": "980110334580776",
  "principal_id": "Pcumminss",
  "tenant_id": "1324710355",
  "email": "patca@autostaging.com",
  "first_name": "Pat",
  "last_name": "Cummins",
  "status": "ENABLE",
  "type": "PERSON",
  "auth_type": "IMS_AUTH",
  "created_date_time": "2020-10-07T19:11:23.871605"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T19:32:17.492948Z",
 "code": 1100,
 "message": "User not found.",
 "error": "Failed to find user by id [980110334580777]"
}
PATCH /ims/api/v1/users/{id}
Update general details of a user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "email": "string",
 "first_name": "string",
 "full_name": "string",
 "last_name": "string"
}
Example request body
{
  "email": "Pete_Adams@bmc.com",
  "first_name": "Pete",
  "full_name": "Pete Adams",
  "last_name": "Pete Adams"
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T19:49:04.118761Z",
 "code": 401,
 "message": "Unauthorized",
 "error": "Unauthorized to perform this operations."
}
POST /ims/api/v1/users/search
Search for users
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users/search
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/users/search?page={pageNumber}&size={records}&orderBy=created_date_time&sortOrder=asc
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "filters": [
   {
     "field": "string",
     "values": [
       "string"
      ]
   }
  ]
}
Example Request body
{
 "filters": [
   {
     "field": "first_name",
     "values": [
       "Mike", "Sheldon"
      ]
   },
   {
     "field": "type",
     "values": [
       "PERSON",
       "EXTERNAL_PERSON",
       "API"
      ]
   }
  ]
}
Parameters
Successful response
{
  "records": [
    {
      "user_id": "927064703261803",
      "principal_id": "Test",
      "tenant_id": "718542488",
      "email": "test@gmail.com",
      "first_name": "Test",
      "last_name": "auto",
      "full_name": "Test auto",
      "status": "ENABLE",
      "type": "PERSON",
      "auth_type": "IMS_AUTH",
      "created_date_time": "2020-10-14T09:47:11.449072"
    }
 ],
  "_metadata": {
    "page": 0,
    "records_per_page": 1000,
    "page_count": 1,
    "total_count": 1
  }
}
Unsuccessful response
{
   "records": [],
   "_metadata": {
       "page": 0,
       "records_per_page": 1000,
       "page_count": 0,
       "total_count": 0
   }
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*