Skip to main content

REST APIs for 24.2.20 and 24.2.10

REST API Users Reference

This topic covers properties, parameters, and examples for REST API users

Properties

Property

Description

Type

href

URI of the user.

String

username

Username used for authentication.

String

last_login_on

When the user logged on.

String

last_login_ip_address

The IP address of the system where the user has logged into the PCE.

String

login_count

The number of times the user has logged in.

Integer

full_name

Full name of a user as listed in the PCE web console.

String

time_zone

Userʼs timezone IANA Region name.

String

locked

Indicates if a user account is locked or not. True = locked.

Boolean

effective_groups

A list of group names to which the user belongs.

String

local profile

Local user profile

Object

updated_at

Date when user account information was last updated in the system.

String

created_at

Date when the user account was created in the system.

String

type

Indicates if the PCE authenticates the user account.

(local) or by a third party SAML-based identity management system (external)

String

one_time_password

The time-based one-time password for two-factor authentication. This password is required in addition to username and password for authentication.

String

Request Example

GET https://pce.my-company.com:8443/api/v2/users/5

Get a Userʼs Information

curl -i -X GET https://pce.my-company.com:8443/api/v2/users/14 -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

In this response, the user is represented in the system by an HREF path property ("href": "/users/14”), which can be used when you want to update the user information.

{
    "href": "/users/14",
    "type": "local",
    "effective_groups": [],
    "id": 14,
    "username": "[email protected]",
    "full_name": "Ralph W. Emerson",
    "time_zone": "America/Los_Angeles",
    "locked": false,
    "login_count": 75,
    "last_login_ip_address": "xxx.37.96.18",
    "last_login_on": "2020-08-17T15:42:25.732Z",
    "local_profile": {
        "pending_invitation": false
    },
    "created_at": "2019-10-26T05:24:08.735Z",
    "updated_at": "2019-08-17T15:55:40.130Z"
}

Request Body for REST API users

Property

Description

Type

Required

full_name

Userʼs full name.

String

No

username

username is an e-mail address such as [email protected]

String

Yes

type

User's type, such as user authenticated as local.

String

Yes

time_zone

The userʼs timezone IANA region name.

String

No

Create a User

curl -i -X POST https://pce.my-company.com:8443/api/v2/users/users

Possible Responses

When you execute the command to update a user, you can receive one of these three messages:

  • 204 success: A new local user was created successfully.

  • 406: Validation error such as invalid.

  • 501: The user has been created, but the invitation email failed. The new user cannot register or sign up. If you receive this message, you need to create another local user.

Resend Invitation for a Local User

To resend the invitation to a new local user after an e-mail notification failure, use the following URI:

PUT /users/:user_id/local_profile/reinvite
Update User Information

This API updates an Illumio API userʼs account information.

URI to Update User's Information

PUT [api_version][user_href]

Request Body

The request body is an empty JSON object.

{}

If you attempt to use a PUT with that URL without a payload, the 406 error shows No payload provided for PUT request.

Property

Description

Type

Optional

full_name

Userʼs full name

String

Yes

time_zone

The userʼs time zone IANA region name

String

Yes

Log Out a User

Use PUT to log out a user:

    "logout": {
		   "http_method": "PUT",
		   "path": "/users/:id/logout",
		   "summary": "Logout a specific user and destroy the access token",

Curl Command to log out a User

curl -i -X PUT https://pce.my-company.com:8443/api/v2/users/12345678/logout -H "Content-Type: application/json" -u $KEY:$TOKEN

where "12345678" is the user ID.

URI to Change the User's Password

PUT [api_version]/login_users/[user_href]/password

Request Body

Property

Description

Type

Required

password

User's new password must meet these requirements:

  • Have a minimum of 8 characters

  • Have at least 1 capital letter

  • Have at least 1 lowercase letter

  • Have at least 1 number

  • Not match previously used passwords

String

Yes

Example Request Body

{
     "password":"'new_password'"
}

Change the User's Password

curl -u 'username'@'company'.com:'existing_password' -X PUT https://'company'.com:8443/api/v2/login_users/me/password -H "Content-type: application/json" -d '{"password":"'new_password'"}' -i
See also: