Users API¶

Use the Users API to authenticate with the Apperian server and receive a unique token (X-TOKEN) that you will need to include in the HTTPS requests you send to Apperian web services during an API session.

Also use the Users API to perform the following user management tasks:

Add a user to your Apperian 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 Apperian invitation to a user via email
Enable/disable a user
Delete one or more users

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

Resources¶

POST /v2/users/authenticate/¶

Authenticate User

Use this resource to establish a connection between your client application and the Apperian server. In your request, you specify the user ID and password for a valid Apperian user. Apperian responds with a unique User 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.

For more information, see Authentication.

Note

Single Sign-On (SSO) authentication to Apperian 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 Apperian user in your organization’s account. Based on this user ID, Apperian identifies your organization in the Apperian 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 Apperian 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 Admin 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 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 Apperian administrator.

Adds a new user to the Apperian 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.

Unless groups are specified in the request, a new user does not belong to any groups. To add a user to one or more groups, either provide the groups data parameter or 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 Admin 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 Admin 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) API token or User token (POST /users/authenticate). For more information, see Authentication.
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 Apperian (the App Catalog or the Admin 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 Apperian.

Note

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

Once a user is created, you cannot change the user ID. All other user fields can be changed via the Admin 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 Apperian. If you specify an email that is already in use, Apperian 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, Apperian will automatically send an email invitation to the user. If you do not want Apperian 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 Send Your Own User Invitations.

role

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

1 - User
5 - Administrator (Only role with permission to connect to Apperian through the API.)
6 - App Manager
7 - User Manager
8 - Developer
9 - Limited User Manager

For more information about the permissions granted to each role, see Roles.

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 Apperian 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 Apperian 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 Apperian 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"
 }

groups

(Optional) An array of group ids. For each id provided, the new user will be added to the corresponding group.

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 Apperian assigned to the user.

{
  "user_psk": 103029
}

GET /v2/users/(user)/¶

List User Details

Requires administrator privileges. Authenticate as an Apperian 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).

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

URLs

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

URL Parameters

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

Header Parameters

X-TOKEN: (Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

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",
       "status": "enabled",
       "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",
       "user_id": "mharrison@example.com",
       "disabled": false,
       "disabled_reason": null,
       "last_login_from_catalog": "2013-05-17T20:35:52.089094",
       "modified_date": "2012-05-02T19:31:33.858168+00:00",
       "custom_metadata": {
            "title": "Sales Account Rep",
            "location": "Boston",
            "projects": "Mercury,Apollo",
            "description": "Sell stuff"
       }
     }

 }

DELETE /v1/users/(user)¶

Delete User

Requires administrator privileges. Authenticate as an Apperian administrator.

Deletes a user from your Apperian organization. A deleted user can no longer access the App Catalog or the Admin 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 Admin 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>
Europe	https://eu01ws.apperian.eu/v1/users/<user>

URL Parameters

user: (Required) Unique ID assigned to the user by Apperian. DATA TYPE: string

Header Parameters

X-TOKEN: (Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

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
}

DELETE /v2/users/¶

Delete Users

Requires administrator privileges. Authenticate as an Apperian administrator.

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

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

URLs

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

URL Parameters

None

Header Parameters

X-TOKEN: (Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

Data Parameters

user_ids: (Required) An array of user IDs corresponding to the user_id value.

Example Request

curl -X DELETE https://na01ws.apperian.com/v2/users/
     --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"
     --data '{"user_ids": ["msmith", "jcabrera", "yhorie"]}'

Example Response

This example response shows that two of the three user_ids were deleted successfully (msmith and jcabrera), while the third user_id (yhorie) was somehow invalid. An invalid user_id might mean that it was spelled wrong or the user otherwise doesn’t exist.

{
  "deleted_user_ids": [
    "msmith",
    "jcabrera"
  ],
  "invalid_user_ids": [
    "yhorie"
  ]
}

PUT /v1/users/(user)¶

Update User

Requires administrator privileges. Authenticate as an Apperian administrator.

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

Update Standard and Custom Metadata

You can update the following standard metadata attributes for a user in your Apperian 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 Admin 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 Admin Portal, but it is not required to send/receive custom metadata through the API.

Resend an Apperian Invitation

When you add a user to Apperian (either through the API or the Admin Portal), you can choose to 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 Admin 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 Admin 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).

Both the GET /users and GET /users/<user> 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 Admin Portal).

1 Indicates that the user was disabled after too many failed login attempts.

Manage Group Membership

You can optionally change the user’s group membership assignment by providing the groups data parameter. The list of groups provided will be the user’s new list of groups. In other words, this resource will not only add the user to the groups specified, but also remove the user from any groups not specified.

Note

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

URLs

Environment URL

North America https://na01ws.apperian.com/v1/users/<user>

Europe https://eu01ws.apperian.eu/v1/users/<user>

URL Parameters

user

(Required) Unique ID assigned to the user by Apperian. DATA TYPE: string

Header Parameters

X-TOKEN

(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

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, Apperian 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 Apperian. If you specify an email that is already in use, Apperian 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 - User

5 - Administrator (Only role with permission to connect to Apperian through the API.)

6 - App Manager

7 - User Manager

8 - Developer

9 - Limited User Manager

For more information about the permissions granted to each role, see `Roles https://docs.digital.ai/bundle/app-management/page/Roles_10403643900.html>`_.

phone

An all-digit phone number for the user. For example: 9782221234

send_invite

Pass this parameter with a value of true to instruct Apperian 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 Apperian 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 Admin 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.

groups

An array of group ids. For each id provided, the user will be added to the corresponding group. This list of groups will replace the user’s existing group memberships.

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 Apperian 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 /v2/users/¶

List Users

Requires administrator privileges. Authenticate as an Apperian 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) User token returned by POST /catalog/authenticate. For more information, see Authentication.

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 /v2/users/info¶

List Information About the Authenticated User

Requires user context. Authenticate as a valid Apperian user.

Returns the following information about the authenticated user:

id (unique value assigned by Apperian when the user was added to the organization)
First name
Last name
ID (Apperian User ID)
Created date (date when the user was added to Apperian)
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 Apperian)
org_id (unique value assigned to the user’s Apperian organization)
org_name (organization name as it appears in Apperian)

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) API token or User token (POST /users/authenticate). For more information, see Authentication.

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"
     }
}

0	Indicates that the user was disabled by an administrator (either using this API resource or using the Admin Portal).
1	Indicates that the user was disabled after too many failed login attempts.