Users API

Use the Users API to authenticate with the EASE server and receive a unique token (X-TOKEN) that you will need to include in the HTTPS requests you send to EASE web services during an API session. Also use the Users API to perform the following user management tasks:

  • Add a user to your EASE organization
  • List details about a specified user
  • List details about the authenticated user
  • Update standard attributes, such as password and email address
  • Update custom metadata (if you are using custom user metadata in your organization)
  • Resend an EASE invitation to a user via email
  • Enable/disable a user
  • Delete a user

To add a user to groups, use the Groups API interface.

Resources

POST /v1/users/authenticate/

Authenticate User

Attention

There is a newer version of this resource available: GET /v2/users/authenticate/. This v1 version will be deprecated in 2018; please modify your code to use the latest V2 version. If you have any questions, contact support@apperian.com.

Use this resource to establish a connection between your client application and the EASE server. In your request, you specify the user ID and password for a valid EASE user. EASE responds with a unique token that you can then provide in the HTTPS header (as X-TOKEN: {token}) of one or more subsequent requests during the API session. The token authenticates a specific user, so you will need to provide different tokens based on who you need to authenticate during the transaction. Within an API session, if you need to connect as the same user for multiple requests, you can use the same token.

To call some API resources, you need to provide an authentication token for a user who has been assigned the “Administrator’ role. This documentation indicates when administrator permissions are required.

Note

Single Sign-On (SSO) authentication to EASE is not supported through the API.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/authenticate/
Europe https://eu01ws.apperian.eu/v1/users/authenticate/

URL Parameters

None

Header Parameters

Content-Type
(Required) Specifies the content type of the body of data sent with the request. Set to: application/json

Data Parameters

user_id
(Required) User ID for a valid EASE user in your organization’s EASE account. Based on this user ID, EASE identifies your organization in the EASE database and retrieves and updates data for that organization. If you are performing a transaction that requires administrator permissions, you will need to provide a user_id for an EASE user who is assigned the “Administrator” role.
password
(Required) User’s password. This is the same password that the user would enter when logging in to the EASE Portal or App Catalog.

Example Request

The following cURL command authenticates the admin@example.com user.

curl -X POST https://na01ws.apperian.com/v1/users/authenticate/ --header "Content-Type: application/json" --data '{"user_id": "admin@example.com", "password": "admin123"}'

Example Response

The response returns a unique authentication token. It also returns data about the user and the user’s organization.

{
  "organization": {
     "psk": 1062,
     "name": "Example Company"
  },
  "token": "sxfvnMM5QdW2jl6x6i0JNg",
  "ttl_in_seconds": 599,
  "user": {
     "psk": 21768,
     "first_name": "Frank",
     "last_name": "Wilson",
     "email": "admin@example.com",
     "mobile_phone": "978-457-6334",
     "role": 5,
     "created_date": "2012-05-02T19:31:33.858168+00:00",
     "until_date": "9999-12-31T23:59:59.999999",
     "id": "admin@example.com",
     "last_login_from_catalog": "2013-05-17T20:35:52.089094"
   }
 }
POST /v2/users/authenticate/

Authenticate User

Use this resource to establish a connection between your client application and the EASE server. In your request, you specify the user ID and password for a valid EASE user. EASE responds with a unique token that you can then provide in the HTTPS header (as X-TOKEN: {token}) of one or more subsequent requests during the API session. The token authenticates a specific user, so you will need to provide different tokens based on who you need to authenticate during the transaction. Within an API session, if you need to connect as the same user for multiple requests, you can use the same token.

To call some API resources, you need to provide an authentication token for a user who has been assigned the “Administrator’ role. This documentation indicates when administrator permissions are required.

Note

Single Sign-On (SSO) authentication to EASE is not supported through the API.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/users/authenticate/
Europe https://eu01ws.apperian.eu/v2/users/authenticate/

URL Parameters

None

Header Parameters

Content-Type
(Required) Specifies the content type of the body of data sent with the request. Set to: application/json

Data Parameters

user_id
(Required) User ID for a valid EASE user in your organization’s EASE account. Based on this user ID, EASE identifies your organization in the EASE database and retrieves and updates data for that organization. If you are performing a transaction that requires administrator permissions, you will need to provide a user_id for an EASE user who is assigned the “Administrator” role.
password
(Required) User’s password. This is the same password that the user would enter when logging in to the EASE Portal or App Catalog.
remember_me
(Optional)
  • true specifies that the session token will use the Remember Me expiration timeout for the organization.
  • false specifies that the session token will use the default session expiration defined for the organization. With the EASE App Catalog, this is set when the user selects a Remember Me option on the Login page.

Example Request

The following cURL command authenticates the admin@example.com user.

curl -X POST https://na01ws.apperian.com/v2/users/authenticate/ --header "Content-Type: application/json" --data '{"user_id": "admin@example.com", "password": "admin123", "remember_me": false}'

Example Response

The response returns a unique authentication token. It also returns data about the user and the user’s organization.

{
  "organization": {
     "id": "zDSrz_B5N_FjYAHlHBosnQ",
     "name": "Example Company"
  },
  "token": "sxfvnMM5QdW2jl6x6i0JNg",
  "ttl_in_seconds": 599,
  "user": {
     "id": "SZseOMCdYC2ZLmnaHqM4Hw",
     "first_name": "Frank",
     "last_name": "Wilson",
     "email": "admin@example.com",
     "mobile_phone": "978-457-6334",
     "role": 5,
     "created_date": "2012-05-02T19:31:33.858168+00:00",
     "until_date": "9999-12-31T23:59:59.999999",
     "user_id": "admin@example.com",
     "last_login_from_catalog": "2013-05-17T20:35:52.089094"
   }
 }
POST /v1/users/

Add User

Requires administrator privileges. Authenticate as an EASE administrator.

Adds a new user to the EASE organization of the authenticated user. A successful response provides a unique key (user_psk) for the user. You will need the user’s user_psk when you add the user to a group, or perform other transactions specific to the user.

After being added, a user does not belong to any user groups. Unlike when you add a user through the EASE Portal, the user is not added to the All Users group by default. To add a user to one or more groups, send a request to the groups/users resource. The ability to access applications in the App Catalog is tied to groups, so users will not be able to access any applications until you add them to one or more groups.

Specify Custom Metadata for a User

In addition to the standard application metadata (such as First Name, Last Name, User ID, and Email Address), you can specify custom metadata that is unique and meaningful to your business. For example, you can store information about a user’s job title, office location, and project teams.

You can view a user’s custom metadata in the EASE Portal only if you define a Custom Metadata Template for your organization on the Settings page. For instructions, see Define a Custom Metadata Template. Note that defining a Custom Metadata Template enables you to add/edit/view custom metadata in the EASE Portal, but it is not required to send/receive custom metadata through the API.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/
Europe https://eu01ws.apperian.eu/v1/users/

URL Parameters

None

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.
Content-Type
(Required) Specifies the content type of the body of data sent with the request. Set to: application/json

Data Parameters

user_id

(Required) A unique identifier for the user. This is the ID that the user will enter to log in to EASE (the App Catalog or the EASE Portal). A valid ID must be 200 characters or less, and cannot include spaces. Valid characters include:

  • a-z
  • A-Z
  • 0-9
  • ~!$%^&*_=+.@,

You can specify the user’s email address as the user ID. Note, however, that if the user ID and email address are different, it is the user ID that the user will need to enter when logging in to EASE.

Note

User ID must be unique across all organizations within EASE, not just your organization. If you specify an ID that is already in use, EASE will return an error.

Once a user is created, you cannot change the user ID. All other user fields can be changed via the EASE Portal by editing the user.

password
(Required) A password for the user. The value must be at least five characters, with no spaces. The user can reset this password at a later time.
first_name
(Required) The user’s first name.
last_name
(Required) The user’s last name.
email

(Required for Administrator role; Optional for User role) The user’s email address, if available. Email must be unique across all organizations within EASE. If you specify an email that is already in use, EASE will return an error. It is valid to enter the user’s email address for both the user_id and email parameters.

By default, when you provide a user’s email address, EASE will automatically send an email invitation to the user. If you do not want EASE to send an invitation, include the send_invite parameter set to false. You can send your own invitations to users after they have been added. For instructions, see Apperian Documentation Center.

role

(Optional; defaults to 1 for User) The type of user:

  • 1 specifies the User role. Users with the User role can use the EASE Portal only for modifying their account profile and listing the apps available to them. Typically, the User role is assigned to users who will log in to EASE through the App Catalog only, not the EASE Portal.
  • 5 specifies the Administrator role. Users with the Administrator role can use the EASE Portal to perform all administration functions and can connect with EASE through the API.
phone
(Optional) An all-digit phone number for the user. For example: 9782221234
send_invite

(Optional) Pass this parameter with a value of false if you do not want EASE to automatically send an email invitation to the user when the user is added.

If you do not include this parameter in the request, it defaults to true and EASE sends an email invitation to the user as long as you include the email parameter with a valid email address.

custom_metadata

(Required if sending custom metadata) An array of name-value pairs for the custom metadata field that will be stored in the EASE database. If you are matching a data object defined in a custom metadata template for your organization, be sure to enter the ID (not the label) of the JSON data object exactly as it is defined in the template. For example:

title: "Senior Software Engineer"

Separate each metadata field with a comma and enclose all the metadata fields with brackets. For example:

"custom_metadata": {
     "title":"Senior Software Engineer",
     "description":"Full-stack software developer",
     "projects":"Mercury,Apollo"
 }

Example Request

curl -X POST https://eu01ws.apperian.eu/v1/users --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json" --data '{"user_id":"exco8027", "password":"abc123", "first_name":"Michael", "last_name":"Harrison", "email":"mharrison@example.com", "role":1}'

This example includes custom metadata:

curl -X POST https://eu01ws.apperian.eu/v1/users --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json" --data '{"user_id":"exco8027", "password":"abc123", "first_name":"Michael", "last_name":"Harrison", "email":"mharrison@example.com", "role":1, "custom_metadata": {"title":"Senior Software Engineer", "description":"Full-stack software developer", "projects":"Mercury,Apollo"}}'

Example Response

A successful response provides the user_psk that EASE assigned to the user.

  {

"user_psk": 103029

  }
GET /v1/users/(user_psk)

List User Details

Requires administrator privileges. Authenticate as an EASE administrator.

Attention

There is a newer version of this resource available: `GET /v2/users/<user_id>/ <https://apidocs.apperian.com/production/users.html#get–v2-users-(user_id)`_. This v1 version will be deprecated in 2018; please modify your code to use the latest V2 version. If you have any questions, contact support@apperian.com.

Returns information stored in the database about a user, such as user ID, email, phone number, and the date when the user was created. You may want to call this resource to review details after adding a user or before updating a user’s attributes in the database.

The response also includes the date when the user will be disabled (until_date). This date is set to a maximum date in the future (9999-12-31T23:59:59.999999) unless the user is scheduled to be automatically disabled due to noncompliance. If until_date is less than the current datetime, then the user is disabled. A user is disabled for noncompliance if all the devices on which the user is running the App Catalog are noncompliant. A device is noncompliant if a mandatory update is not installed within the specified grace period. For more information on mandatory update compliance, see Managing Application Updates.

When you request this resource, you need to provide the user_psk value assigned by EASE when you added the user.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/<user_psk>
Europe https://eu01ws.apperian.eu/v1/users/<user_psk>

URL Parameters

user_psk
(Required) Unique ID assigned to the user by EASE. DATA TYPE: integer

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.

Data Parameters

None

Example Request

In the following example, 103030 specifies the user_psk value for the user whose details will be retrieved from the database.

curl -X GET https://eu01ws.apperian.eu/v1/users/103030 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
    "user": {
       "psk": 2198,
       "first_name": "Michael",
       "last_name": "Harrison",
       "email": "mharrison@example.com",
       "mobile_phone": "978-457-6334",
       "role": 5,
       "created_date": "2012-05-02T19:31:33.858168+00:00",
       "until_date": "9999-12-31T23:59:59.999999",
       "password": "39ce57611eb666ade632cb265065b4b4d0692ecc",
       "id": "mharrison@example.com",
       "disabled_reason": null,
       "last_login_from_catalog": "2013-05-17T20:35:52.089094"
     }

 }
GET /v2/users/(user_id)

List User Details

Requires administrator privileges. Authenticate as an EASE administrator.

Returns information stored in the database about a user, such as user ID, email, phone number, and the date when the user was created. You may want to call this resource to review details after adding a user or before updating a user’s attributes in the database.

The response also includes the date when the user will be disabled (until_date). This date is set to a maximum date in the future (9999-12-31T23:59:59.999999) unless the user is scheduled to be automatically disabled due to noncompliance. If until_date is less than the current datetime, then the user is disabled. A user is disabled for noncompliance if all the devices on which the user is running the App Catalog are noncompliant. A device is noncompliant if a mandatory update is not installed within the specified grace period. For more information on mandatory update compliance, see Managing Application Updates.

When you request this resource, you need to provide the user_id value assigned by EASE when you added the user.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/users/<user_id>
Europe https://eu01ws.apperian.eu/v2/users/<user_id>

URL Parameters

user_id
(Required) Unique ID assigned to the user by EASE. DATA TYPE: integer

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.

Data Parameters

None

Example Request

In the following example, 103030 specifies the user_id value for the user whose details will be retrieved from the database.

curl -X GET https://eu01ws.apperian.eu/v2/users/103030 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
    "user": {
       "id": "roKMPRGnBe91jx0oxergCQ",
       "first_name": "Michael",
       "last_name": "Harrison",
       "email": "mharrison@example.com",
       "mobile_phone": "978-457-6334",
       "role": 5,
       "created_date": "2012-05-02T19:31:33.858168+00:00",
       "until_date": "9999-12-31T23:59:59.999999",
       "password": "39ce57611eb666ade632cb265065b4b4d0692ecc",
       "user_id": "mharrison@example.com",
       "disabled_reason": null,
       "last_login_from_catalog": "2013-05-17T20:35:52.089094"
     }

 }
DELETE /v1/users/(int: user_psk)

Delete User

Requires administrator privileges. Authenticate as an EASE administrator.

Deletes a user from your EASE organization. A deleted user can no longer access the App Catalog or the EASE Portal. If a deleted user tries to log in, the user will see a message that advises the user to contact support.

If you need to grant access to the user again in the future, you should use the EASE Portal to disable instead of delete the user. For instructions, see the Apperian Documentation Center.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/<user_psk>
Europe https://eu01ws.apperian.eu/v1/users/<user_psk>

URL Parameters

user_psk
(Required) Unique ID assigned to the user by EASE. DATA TYPE: integer

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.

Data Parameters

None

Example Request

This example shows a cURL command that deletes the user with the user_psk of 9704.

curl -X DELETE https://na01ws.apperian.com/v1/users/9704 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
  "delete_user_response": true
}
PUT /v1/users/(int: user_psk)

Update User

Requires administrator privileges. Authenticate as an EASE administrator.

Use this API to update metadata for a user in your organization, to resend an EASE invitation, or to enable/disable the user. When you send a request to this resource, you will need to provide the user_psk value assigned when you added the user.

Update Standard and Custom Metadata

You can update the following standard metadata attributes for a user in your EASE organization:

  • email
  • password
  • first_name
  • last_name
  • role
  • phone

If there is custom metadata associated with the user, you can update custom metadata object by sending the “custom_metadata” parameter.

Note

You can only view a user’s custom metadata in the EASE Portal if you define a Custom Metadata Template for your organization on the Settings page. For instructions, see Define a Custom Metadata Template. Note that defining a Custom Metadata Template enables you to add/edit/view custom metadata in the EASE Portal, but it is not required to send/receive custom metadata through the API.

Resend an EASE Invitation

When you add a user to EASE (either through the API or the EASE Portal), you can choose to have EASE send the user an invitation through email that provides instructions for setting his/her password and downloading the App Catalog. Using this resource with the send_invite parameter set to true, you can send/resend an invitation to a user either because you did not send it when the user was first added or because you wish to resend it.

Note

Through the EASE Portal, you can customize the content of the invitation message; for instructions, see Edit the User Invitation.

Enable or Disable a User

Using this resource, you can enable or disable a user. Disabling a user temporarily prohibits the user from accessing the App Catalog or the EASE Portal. If a disabled user tries to log in, the user will see a message that advises the user to contact the administrator. The user is also blocked from running apps wrapped with any of Apperian’s base application policies (see Application Policies for a complete list).

Note

This resource performs the same function performed through the EASE Portal to manually enable/disable a user. If the Application Update Compliance policy is applied to any apps in your organization, it is possible that EASE will automatically disable users. You can use this resource (or the EASE Portal) to enable a user that EASE automatically disabled. For more information on the Application Update Compliance policy, see Application Update Compliance.

Both the GET /users and GET /users/<user_psk> resources return a disabled field with the disabled status of the user (true or false). If the user is disabled, a disabled_reason field identifies how the user was disabled.

0
Indicates that the user was disabled by an administrator (either using this API resource or using the EASE
Portal).
1 Indicates that the user was disabled after too many failed login attempts.
2 Indicates that the user was disabled automatically by the system due to Application Update Compliance settings.

Note

To permanently delete a user, use the DELETE /users/<user_psk> resource.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/<user_psk>
Europe https://eu01ws.apperian.eu/v1/users/<user_psk>

URL Parameters

user_psk
(Required) Unique ID assigned to the user by EASE. DATA TYPE: integer

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.
Content-Type
(Required) Specifies the content type of the body of data sent with the request. Set to: application/json

Data Parameters

The request must include one or more of these parameters. If you provide a value for an attribute that is equal to the value already stored in the database, EASE will retain that value; that is, it will not update the attribute.

email
The user’s email address. Email must be unique across all organizations within EASE. If you specify an email that is already in use, EASE will return an error.
password
A password for the user. The value must be at least five characters, with no spaces. The user can reset this password at a later time.
first_name
The user’s first name.
last_name
The user’s last name.
role

The type of user:

  • 1 specifies the User role. Users with the User role can use the EASE Portal only for modifying their account profile and listing the apps available to them. Typically, the User role is assigned to users who will log in to EASE through the App Catalog only, not the EASE Portal.
  • 5 specifies the Administrator role. Users with the Administrator role can use the EASE Portal to perform all administration functions and can connect with EASE through the API.
phone
An all-digit phone number for the user. For example: 9782221234
send_invite
Pass this parameter with a value of true to instruct EASE to send an email invitation to the user. Note that the user must have a valid email address associated with his/her account; include the email parameter in the request also if you need to add/update the user’s email address. If you do not include the send_invite parameter with an update request, it defaults to false and does not send an email invitation to the user.
custom_metadata

An array of name-value pairs for the custom metadata field that will be stored in the EASE database.

If you are matching data objects defined in a custom metadata template for your organization, be sure to enter the id (not the label) of the JSON data object exactly as it is defined in the template. For example:

"title: "Senior Software Engineer"

Separate each metadata field with a comma and enclose all the metadata fields with brackets. For example:

"custom_metadata": {"title": "Senior Software Engineer", "description": "Full-stack software developer", "projects": "Mercury,Apollo"}

Note

If there are multiple custom metadata objects defined for a user, be sure to include a name-value pair for each of the objects you want to retain, even if you are updating values of only some objects. For example, if this is the current metadata stored for a user:

"custom_metadata": {"title": "Senior Software Engineer", "description": "Full-stack software developer", "projects": "Mercury,Apollo"}

And you send this:

"custom_metadata": {"projects": "Mercury,Gemini"}

The projects object will be updated for the user, but the title and description will be lost. If there is a custom metadata template defined for your organization, title and description fields will still display in the EASE Portal, but they will display either with default values (if defined) or null values.

disabled
Set to true to disable the application. Set to false to enable the application.

Example Requests and Responses

Update Standard Metadata

This request changes the password for the user.

Request

curl -X PUT https://na01ws.apperian.com/v1/users/103030 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json" --data '{"password": "changeme123" }'
Response

  {
    "update_user_success": true
  }

Update Custom Metadata

This request updates custom metadata for the user.

Request

curl -X PUT https://na01ws.apperian.com/v1/users/123 --data '{"custom_metadata": {"title": "Senior Software Engineer", "description": "Software developer", "projects": "Mercury,Apollo"}}' --header "Content-Type: application/json" --header "X-TOKEN: zH2syg3cSmip4EU5Md8a1A"
Response

{
  "update_user_success": true
}

Resend an Invitation to the User

This request resends an EASE email invitation to the user.

Request

curl -X PUT https://na01ws.apperian.com/v1/users/103030 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json" --data '{"send_invite": true }'
Response

{
  "update_user_success": true
}

Disable the User

This request disables the user.

Request

curl -X PUT https://na01ws.apperian.com/v1/users/103030 --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json" --data '{"disabled": true }'
Response

{
  "update_user_success": true
}
GET /v1/users/

List Users

Requires administrator privileges. Authenticate as an EASE administrator.

Attention

There is a newer version of this resource available: GET /v2/users/. This v1 version will be deprecated in 2018; please modify your code to use the latest V2 version. If you have any questions, contact support@apperian.com.

Returns a list of all users in the authenticated user’s organization.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/
Europe https://eu01ws.apperian.eu/v1/users/

URL Parameters

When you send a GET request to this resource, you can specify URL parameters to search, sort, and paginate the JSON data returned in the response. For more information, see Controlling GET Responses.

Header Parameters

X-TOKEN
(Required) Session token returned by POST /catalog/authenticate.

Data Parameters

None

Example Request

curl -X GET https://eu01ws.apperian.eu/v1/users/ --header "X TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
     "users": [
       {
         "psk": 24,
         "first_name": "Michael",
         "last_name": "Harrison",
         "modified_date": "2015-07-22T23:17:33+00:00",
         "custom_metadata": {
           "title": "Sales Account Rep",
           "location": "Boston",
           "projects": "Mercury,Apollo",
           "description": "Sell stuff"
         },
         "email": "mharrison@example.com",
         "mobile_phone": "978-457-6334",
         "role": 5,
         "created_date": "2012-03-15T19:46:09.639614+00:00",
         "until_date": "9999-12-31T23:59:59.999999",
         "id": "mharrison",
         "last_login_from_catalog": "2015-07-22T23:17:33.186128"
       },
       {
         "psk": 55,
         "first_name": "Christina",
         "last_name": "Harrington",
         "modified_date": "2012-03-21T19:18:21+00:00",
         "custom_metadata": null,
         "email": "charrington@example.com",
         "mobile_phone": "123-456-7890",
         "role": 1,
         "created_date": "2012-03-21T19:05:14+00:00",
         "until_date": "9999-12-31T23:59:59.999999",
         "disabled_reason": null,
         "id": "charrington",
         "last_login_from_catalog": null
       },
       {
         "psk": 56,
         "first_name": "Alex",
         "last_name": "Bolton",
         "modified_date": "2013-11-12T14:31:24+00:00",
         "email": "abolton@example.com",
         "mobile_phone": "123-987-9876",
         "role": 1,
         "created_date": "2012-03-21T19:05:59+00:00",
         "until_date": "9999-12-31T23:59:59.999999",
         "disabled_reason": null,
         "id": "abolton",
         "last_login_from_catalog": "2013-11-12T15:01:08.917325"
}
GET /v2/users/

List Users

Requires administrator privileges. Authenticate as an EASE administrator.

Returns a list of all users in the authenticated user’s organization.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/users/
Europe https://eu01ws.apperian.eu/v2/users/

URL Parameters

When you send a GET request to this resource, you can specify URL parameters to search, sort, and paginate the JSON data returned in the response. For more information, see Controlling GET Responses.

Header Parameters

X-TOKEN
(Required) Session token returned by POST /catalog/authenticate.

Data Parameters

None

Example Request

curl -X GET https://eu01ws.apperian.eu/v2/users/ --header "X TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
     "users": [
       {
         "id": "SZseOMCdYC2ZLmnaHqM4Hw",
         "first_name": "Michael",
         "last_name": "Harrison",
         "modified_date": "2015-07-22T23:17:33+00:00",
         "custom_metadata": {
           "title": "Sales Account Rep",
           "location": "Boston",
           "projects": "Mercury,Apollo",
           "description": "Sell stuff"
         },
         "email": "mharrison@example.com",
         "mobile_phone": "978-457-6334",
         "role": 5,
         "created_date": "2012-03-15T19:46:09.639614+00:00",
         "until_date": "9999-12-31T23:59:59.999999",
         "user_id": "mharrison",
         "last_login_from_catalog": "2015-07-22T23:17:33.186128"
       },
       {
         "id": "i1vL30rYoPYXnR1uMoU4ww",
         "first_name": "Christina",
         "last_name": "Harrington",
         "modified_date": "2012-03-21T19:18:21+00:00",
         "custom_metadata": null,
         "email": "charrington@example.com",
         "mobile_phone": "123-456-7890",
         "role": 1,
         "created_date": "2012-03-21T19:05:14+00:00",
         "until_date": "9999-12-31T23:59:59.999999",
         "disabled_reason": null,
         "user_id": "charrington",
         "last_login_from_catalog": null
       },
       {
         "id": "roKMPRGnBe91jx0oxergCQ",
         "first_name": "Alex",
         "last_name": "Bolton",
         "modified_date": "2013-11-12T14:31:24+00:00",
         "email": "abolton@example.com",
         "mobile_phone": "123-987-9876",
         "role": 1,
         "created_date": "2012-03-21T19:05:59+00:00",
         "until_date": "9999-12-31T23:59:59.999999",
         "disabled_reason": null,
         "user_id": "abolton",
         "last_login_from_catalog": "2013-11-12T15:01:08.917325"
}
GET /v1/users/info

List Information About the Authenticated User

Attention

There is a newer version of this resource available: `GET /v2/users/info/ <https://apidocs.apperian.com/production/users.html#get–v2-users-info`_. This v1 version will be deprecated in 2018; please modify your code to use the latest V2 version. If you have any questions, contact support@apperian.com.

Requires user context. Authenticate as a valid EASE user.

Returns the following information about the authenticated user:

  • user_psk (unique value assigned by EASE when the user was added to the organization)
  • First name
  • Last name
  • ID (EASE User ID)
  • Created date (date when the user was added to EASE)
  • Modified date (date when the user’s data was last modified)
  • Custom metadata (name-value pairs for any custom metadata associated with the user)
  • Email
  • Mobile phone number
  • Last login from catalog (date on which the user last logged into EASE)
  • org_psk (unique value assigned by EASE to the user’s EASE organization)
  • org_name (organization name as it appears in EASE)

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/info
Europe https://eu01ws.apperian.eu/v1/users/info

URL Parameters

None

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.

Data Parameters

None

Example Request

In the following example, 103030 specifies the user_psk value for the user whose details will be retrieved from the database.

curl -X GET https://eu01ws.apperian.eu/v1/users/info --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
     "user": {
       "org_psk": 1496,
       "last_name": "Harrison",
       "user_id": "mharrison",
       "modified_date": "2015-12-08T20:09:11+00:00",
       "custom_metadata": {
         "city": "Boston",
         "title": "Software Engineer"
       },
       "created_date": "2014-09-25",
       "first_name": "Michael",
       "org_name": "Example org",
       "email": "mharrison@example.com",
       "mobile_phone": "989-456-9876",
       "psk": "120324",
       "disabled_reason": null,
       "last_login_from_catalog": "2015-12-08T20:15:57.861233"
     }
}
GET /v2/users/info

List Information About the Authenticated User

Requires user context. Authenticate as a valid EASE user.

Returns the following information about the authenticated user:

  • id (unique value assigned by EASE when the user was added to the organization)
  • First name
  • Last name
  • ID (EASE User ID)
  • Created date (date when the user was added to EASE)
  • Modified date (date when the user’s data was last modified)
  • Custom metadata (name-value pairs for any custom metadata associated with the user)
  • Email
  • Mobile phone number
  • Last login from catalog (date on which the user last logged into EASE)
  • org_id (unique value assigned by EASE to the user’s EASE organization)
  • org_name (organization name as it appears in EASE)

URLs

Environment URL
North America https://na01ws.apperian.com/v1/users/info
Europe https://eu01ws.apperian.eu/v1/users/info

URL Parameters

None

Header Parameters

X-TOKEN
(Required) Session token returned by POST /users/authenticate.

Data Parameters

None

Example Request

In the following example, 103030 specifies the id value for the user whose details will be retrieved from the database.

curl -X GET https://eu01ws.apperian.eu/v1/users/info --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
     "user": {
       "org_id": zDSrz_B5N_FjYAHlHBosnQ,
       "last_name": "Harrison",
       "user_id": "mharrison",
       "modified_date": "2015-12-08T20:09:11+00:00",
       "custom_metadata": {
         "city": "Boston",
         "title": "Software Engineer"
       },
       "created_date": "2014-09-25",
       "first_name": "Michael",
       "org_name": "Example org",
       "email": "mharrison@example.com",
       "mobile_phone": "989-456-9876",
       "id": "SZseOMCdYC2ZLmnaHqM4Hw",
       "disabled_reason": null,
       "last_login_from_catalog": "2015-12-08T20:15:57.861233"
     }
}