×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

   

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.
BMC Helix Portal 21.3 Performing role-based access control with REST API

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

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 from which you want to retrieve users.

Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter.

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
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}
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}
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}
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
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 from which you want to retrieve users.

Note that the page number starts from 0 (default). Use this parameter in conjunction with the size parameter.

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 an 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 an 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
Last modified by Sulekha Gulati on Oct 22, 2021
development reference rest_api using_api authorization

Comments

Log in or register to comment.

Access key endpoints in the REST API
User group endpoints in the REST API
© Copyright 2020-2021 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.