Skip to main content

REST APIs for 24.2.20 and 24.2.10

RBAC User Operations

This Public Stable API creates, updates, re-invites local users, and converts user status (a local user to an external user or an external user to a local user). This API is intended only for local users managed by the PCE, not users managed by an external identity provider (IdP).

API Methods

Functionality

HTTP

URI

Get a collection of users.

GET

[api_version]/users

GET an individual user.

GET

[user_href]

Get all the organizations the user has accessed after logging in (this endpoint is Public Experimental)

GET

[api_version][user_href]/orgs

Create a local user and send an e-mail invitation.

POST

[api_version]/users

Convert an external user to a local user

POST

[user_href]local_profile

Delete a local user and convert to an external user

DELETE

[user_href]local_profile

Re-invite a local user.

PUT

[user_href]local_profile/reinvite

For authenticated users: change your password by sending a request to the agent service.

PUT

[user_href]local_profile/password

Get RBAC Users

These methods gets a coll ction of users or individual users in the organization.

By default, the maximum number of users returned from a GET collection is 500. To get more than 500 users, use Asynchronous GET Collections.

URI to Get a Collection of Local Users

GET [api_version]/users

URI to Get an Individual User

GET [user_href]
Create a Local User

This method creates local users whom the PCE manages.

URI to Create a Local User

POST [api_version]/users
User Profiles

Change a user's status by converting a local user to an external user or an external user to a local user.

Convert Local to External User

This method converts a local user to an external user by deleting the local user account profile.

Use the user HREF, obtained from the response when a user logs into the PCE using the Login API or from the GET collection response.

For example: /users/14

Convert External User to Local User

This method converts externally managed users to local users managed by the PCE.

Re-invite a Local User

If you have already created a local user, but that user has not logged in yet for the first time, you can use this method to resend the email invitation. Once they receive the invitation, they can log into the PCE and complete their PCE user account registration.

RBAC User Operations Reference

This topic covers parameters, properties, and examples for RBAC user operations.

Parameters

Parameter

Description

Type

Required

type

Indicates that the user created is a local user managed by the PCE.

String

No

id

User ID

Integer

Yes

Properties

Property

Description

Type

Required

href

User URI

String

Yes

username

Identify a local user by an e-mail address, which must meet these requirements:

String (email)

Yes

last_login_on

This is populated automatically after a login.

String

Yes

last_login_ip_address

This is populated automatically after a login.

String

Yes

login_count

Number of times this user logged in

Integer

Yes

full_name

User's full name

String

Yes

time_zone

Time Zone IANA Region Name

String

Yes

type

User's type, i.e., user authenticated locally or remotely via SAML.

String

Yes

updated_at

Timestamp when this user was last updated

String

Yes

created_at

Timestamp when this user was first created

String

Yes

current_password

The current password that you want to change

String

Yes

new_password

New password to set

String

Yes

Examples
Convert Local to External User

URI to Convert a Local User to an External User

DELETE [user_href]/local_profile

Example

DELETE https://pce.my-company.com:8443/api/v2/users/14/local_profile

Convert Local User to External User

curl -i -X >DELETE https://pce.my-company.com:8443/api/v2/users/14/local_profile -H "Accept: application/json" -u $KEY:$TOKEN
Convert External User to Local User

URI to Convert an External User to a Local User

POST [user_href]/local_profile

Example

POST https://pce.my-company.com:8443/api/v2/users/14/local_profile
Re-invite a Local User

URI to Re-invite a Local User

PUT [user_href]/local_profile/reinvite

Example

PUT https://pce.my-company.com:8443/api/v2/users/14/local_profile/reinvite

Curl Command Get Collection of Local Users

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

Response

[
    {
        "href": "/users/99",
        "type": "local",
        "effective_groups": [],
        "id": 99,
        "username": "[email protected]",
        "full_name": "Joe User",
        "time_zone": "America/Los_Angeles",
        "locked": false,
        "login_count": 1,
        "last_login_ip_address": "192.x.x.x",
        "last_login_on": "2016-03-11T08:19:17.587Z",
        "local_profile": { "pending_invitation": false },
        "created_at": "2016-03-08T20:58:05.882Z",
        "updated_at": "2016-03-11T08:19:17.588Z"
    }
.....................................................................
    {
        "href": "/users/56",
        "type": "local",
        "effective_groups": [],
        "id": 56,
        "username": "[email protected]",
        "full_name": "Jeff User",
        "time_zone": "America/New_York",
        "locked": false,
        "login_count": 21,
        "last_login_ip_address": "192.x.x.x",
        "last_login_on": "2017-05-26T14:22:37.643Z",
        "local_profile": { "pending_invitation": true },
        "created_at": "2016-05-02T07:16:21.725Z",
        "updated_at": "2017-05-26T14:23:04.625Z"
    }
]

Pending Invitation

Users with "pending_invitation": "true" in the response have not yet accepted the invitation to log in and create an account.

{
    "href": "/users/56",
    "type": "local",
    "effecve_groups": [],
    "id": 56,
    "username": "[email protected]",
    "full_name": "Jeff User",
    "time_zone": "America/New_York",
    "locked": false,
    "login_count": 21,
    "last_login_ip_address": "192.x.x.x",
    "last_login_on": "2017-05-26T14:22:37.643Z",
    "local_profile": { "pending_invitation": true },
    "created_at": "2016-05-02T07:16:21.725Z",
    "updated_at": "2017-05-26T14:23:04.625Z"
}

Request body to create a local user

{
  "username": "[email protected]",
  "display_name": "Joe User ",
  "type": "local"
}

Curl Command to Create a Local User

curl -i -X POST https://pce.my-company.com:8443/api/v2/users -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"username": "[email protected]","display_name": "Joe User","type": "user"}'

Curl Command Convert External User to Local User

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

Curl Command to Re-invite a Local User

curl -i -X PUT https://pce.my-company.com:8443/api/v2/users/14/local_profile/reinvite -H "Content-Type: application/json" -u $KEY:$TOKEN
See also: