Skip to main content

REST APIs for 22.2

REST API Users

This Public Stable API allows you to log your User into the PCE so you can get a session token to access other Illumio Core REST API calls. This API is your starting point for interacting with the PCE using the REST API.

Users API Methods

Functionality

HTTP

URI

Authenticate to the Illumio Login Service and obtain

a single-use authentication token.

POST

[api_version]/login_users/authenticate

Create a new user.

POST

[api_version][users]

Log in a user and obtain a session token.

GET

[api_version]/users/login

Log out a user and destroy the session token.

PUT

[api_version][user_href]/logout

Get a userʼs information.

GET

[api_version][user_href]

Update userʼs information.

PUT

[api_version][user_href]

Change a user's password (a local, non-SSO user).

PUT

[api_version]/login_users/[user_href]/password

Log Into the PCE

URI to Log In User

GET [api_version]/users/login

For step-by-step instructions about how to authenticate to the PCE and use GET /users/login in conjunction with other methods, see Authentication and API User Permissions.

Log Out and Destroy Credentials

This API logs users out of the PCE and destroys the temporary session credentials used to log them in.

Note

This PUT /logout call is not used with persistent API credentials.

URI to Log Out a User

PUT [user_href]/logout

Request Body

The request body is an empty JSON object.

{}

Log Out a User

curl -i -X PUT https://pce.my-company.com:8443/api/v2/authentication_services/password_policy -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"require_type_symbol": true, "expire_time_days": 90}
Get User Information

This API gets specific information about a user, such as when a user logged into the Illumio PCE, the IP address from where the user logged in, the user's name, and password.

URI to Get User Information

GET [user_href]

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 user account is authenticated by the PCE

(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”) that 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"
}
Create a New User

This API creates a new local user.

URI to Create a New User

POST [api_version][users]

Request Body

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 errorsuch as invalid.

  • 501: The user is created, but the invitation e-mail 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.

Change the User Password

This API method allows currently authenticated users to change their login password.

  • The call must be made by the user currently authenticated in the session; even an administrator cannot change another user's password.

  • An API key is not used with this API.

  • The user's login name (typically the user's e-mail address) and login password are used for authentication.

  • The user's five most recent passwords cannot be used.

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

Possible Responses

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

  • 204 success: The password was changed successfully.

  • 406: Validation error such as invalid.

  • 501: Password is changed, but e-mail notification failed.

See also: