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

NameLocated inDescriptionMandatorySchema
pagequery

Page number of the User access > User management page displayed on the console from where you want to retrieve details.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Column on which you want to sort.

Valid values: 

  • user_id
  • principal_id
  • email
  • first_name
  • last_name
  • full_name
  • status
  • type
  • auth_type
  • (Default) created_date_time
nostring
sortOrderquery

Sort order of the details to be retrieved.

Valid values:

  • (Default) asc
  • desc
nostring
userTypesquery

Type of users for which you want to retrieve details.

You can get details of only console users (value: PERSON), only API users (value: API), only external IdP users (value: EXTERNAL_PERSON) or all type of users (value: PERSON,API,EXTERNAL_PERSON).

Valid values:

  •  (default) PERSON
  • API
  • EXTERNAL_PERSON
noarray of string

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

NameLocated inDescriptionMandatorySchema
auth_typebody

Indication of whether the user must be a local user (value: IMS_AUTH) or an external IdP user (value: EXTERNAL_AUTH).

yesstring
emailbody

Email address of the user.

yesstring
first_namebody

First name of the user.

yesstring
full_namebody

Full name of the user.

This value is the combination of the first name and the last name.

yesstring
last_namebody

Last name of the user.

nostring
principal_idbody

Login ID of user.

This value will be used to access the product.

yesstring

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

NameLocated inDescriptionMandatorySchema
idpath

ID of the user that you want to delete.

yesstring

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

NameLocated inDescriptionMandatorySchema
idpath

ID of the user for which you want to retrieve details.

yesstring

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

NameLocated inDescriptionMandatorySchema
idpathID of the user that you want to update.yesstring
emailbodyEmail address of the user that you want to update.nostring
first_namebodyFirst name of the user that you want to update.nostring
full_namebodyFull name of the user that you want to update.nostring
last_namebodyLast name of the user that you want to update.nostring

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

NameLocated inDescriptionMandatorySchema
pagequery

Page number of the User access > User management page displayed on the console from where you want to retrieve details.

nointeger
sizequery

Total number of records that you want to retrieve from a page.

Default: 1000 records

nointeger
orderByquery

Column on which you want to sort.

Valid values: 

  • user_id
  • principal_id
  • email
  • first_name
  • last_name
  • full_name
  • status
  • type
  • auth_type
  • (Default) created_date_time
nostring
sortOrderquery

Sort order of the details to be retrieved.

Valid values:

  • (Default) asc
  • desc
nostring
fieldbody

Field by which you want to search users.

At one time, you can search by one of the following fields:

  • first_name: First name of a user.
  • last_name: Last name of a user.
  • full_name: Full name of a user.
  • principal_id: Login ID of a user.
  • email: Email address of a user.
  • user_id: ID of a user,
  • type: Type of a user. The type can be one of the following:
    • PERSON: Refers to console users.
    • API: Refers to API users
    • EXTERNAL_PERSON: Refers to external users.

Note: If you want to perform a global search in all the preceding fields, provide asterisk (*) as the value.

yesstring
valuesbody

Value with which you want to search the users.

You can pass a comma-separated list of multiple values for all the valid fields except when you use asterisk (*) as the field.

If you specify the type field, you can provide one or more of the valid values supported.

yesArray[string]

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
    }
}

Was this page helpful? Yes No Submitting... Thank you

Comments