REST API Users

This Public Stable API allows you to log your User into the PCE, enabling you to obtain a session token to access other 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 as 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 the 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 In to the PCE

URI to Log In User

GET [api_version]/users/login

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 retrieves specific information about a user, including the time the user logs into the Illumio PCE, the IP address from which the user logs in, the user's name, and the password.

URI to Get User Information

GET [user_href]

Create a New User

This API creates a new local user.

URI to Create a New User

POST [api_version][users]

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 are not available for use.

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: The password was changed, but the e-mail notification failed.

Required Permissions for API Users

To use the REST APIs, you must be an authorized Illumio user with credentials to log into the PCE.

User Permissions and the API

Authentication to the PCE is based on three user roles that allow users to perform specific API operations:

Organization owner: All GET, POST, PUT, and DELETE APIs
Administrator: Most GET, POST, PUT, and DELETE APIs
Read-only: GET only

The PCE also has two other kinds of roles:

Unscoped: Not bound by label scopes
Scoped: Bound by label scopes

Unscoped Roles

API Role Name	UI Role Name	Granted Access
`owner`	Global Organization Owner	Perform all actions: Add, edit, or delete any resource, organization setting, or user account.
`admin`	Global Administrator	He performs all actions except that he cannot change organization settings and cannot perform user management tasks.
`read_only`	Global Read Only	View any resource or organization setting. Cannot perform any operations.
`global_object_provisioner`	Global Policy Object Provisioner	Provision rules containing IP lists, services, label groups, and manage security settings. Cannot provision rulesets, virtual services, or virtual servers, or add, modify, or delete existing policy items.

Scoped Roles

API Role Name	UI Role Name	Granted Access
`ruleset_manager`	Full Ruleset Manager	Add, edit, and delete all rulesets within the specified scope. You can add, edit, and delete rules when the Source matches the specified scope. The rule Destination can match any scope.
`limited_ruleset_manager`	Limited Ruleset Manager	Add, edit, and delete all rulesets within the specified scope. Add, edit, and delete rules when the Source and Destination match the specified scope. Ruleset Managers with limited privileges cannot manage rules that use IP lists, user groups, label groups, or iptables rules as destinations, or rules that allow internet connectivity.
`ruleset_provisioner`	Ruleset Provisioner	Provision rulesets within a specified scope. This role cannot provision virtual servers, virtual services, SecureConnect gateways, security settings, IP lists, services, or label groups.

API Role Name

UI Role Name

Granted Access

ruleset_manager

Full Ruleset Manager

Add, edit, and delete all rulesets within the specified scope.

You can add, edit, and delete rules when the Source matches the specified scope. The rule Destination can match any scope.

limited_ruleset_manager

Limited Ruleset Manager

Add, edit, and delete all rulesets within the specified scope.

Add, edit, and delete rules when the Source and Destination match the specified scope.

Ruleset Managers with limited privileges cannot manage rules that use IP lists, user groups, label groups, or iptables rules as destinations, or rules that allow internet connectivity.

ruleset_provisioner

Ruleset Provisioner

Provision rulesets within a specified scope. This role cannot provision virtual servers, virtual services, SecureConnect gateways, security settings, IP lists, services, or label groups.

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

Illumio REST APIs 25.4

REST API Users

Users API Methods

Log In to the PCE

Log Out and Destroy Credentials

Note

Get User Information

Create a New User

Change the User Password

Required Permissions for API Users

User Permissions and the API

Unscoped Roles

Scoped Roles

REST API Users Reference

Properties

Update User Information

Log Out a User

Search results