Authentication

Every request sent through the Apperian API must include a valid access token. An access token is a unique string that identifies a user and grants access based on their permissions.

There are two types of tokens used to access the Apperian API:

  • API Tokens
  • User Tokens

API Tokens

API Tokens are the primary method used to access the Apperian API, and are especially useful for repetitive and automated tasks. API Token sessions never expire, which means they can be used indefinitely.

You can obtain API Tokens for any user in the system, though you should typically only create tokens for users with the Administrator role. One user can have multiple API tokens if necessary.

Apperian recommends using API Tokens to access all endpoints except for those in the Catalog API, Downloads and Installs API, and Reviews API. The endpoints in those APIs require User Tokens, which are discussed in the next section.

You can create and manage API Tokens in the Admin Portal or via the API (see the API reference later on this page).

User Tokens

User Tokens are used primarily for end user access through the Catalog API, Downloads and Installs API, and Reviews API. They provide information relating to the user and the user’s device, which is important if you build your own enterprise app catalog, or integrate the ability for users to access and install apps into another system, such as a corporate portal.

You can obtain a User Token by sending a POST request to /catalog/authenticate/. In your request, you’ll specify the user ID and password for a valid user. Apperian responds with a unique User Token for that user.

Note

It is possible to obtain tokens via /users/authenticate/ and use them for accessing the non-end user APIs, but the reasons for doing so are rare, and the API Token method is preferred.

Using the Tokens

Regardless of which method you use to create the token, you will then provide it in the HTTPS header of each request during the API session, like this:

curl -X GET https://na01ws.apperian.com/v2/applications/ --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Note

This example, like the majority of Apperian endpoints, uses the X-TOKEN parameter. However, a few endpoints use a parameter called token. Refer to the documentation for a specific endpoint when determining which parameter to use.

A token identifies a specific user, so you may need to provide different tokens based on who you need to act on behalf of during the transaction.

To call most API endpoints, you need to provide a token for a user who has been assigned the Administrator role. With other endpoints (Catalog, Downloads and Installs, Reviews), you need to provide a token that authenticates the specific end user (any non-Administrator role) for whom you want to perform a task.

In this guide, each endpoint is flagged with an Authentication box under the endpoint header; it indicates whether the endpoint requires user and device context (use a User Token from /catalog/authenticate) or just user context (use an API Token), and whether you can authenticate as any user or need to authenticate as an administrator.

Token Session Expiration

API Tokens never expire, and can be used indefinitely.

User Tokens expire based on whether the authentication uses Remember Me:

  • With Remember Me, the token will expire based on the Remember Me expiration timeout for the organization, which is set to 1 week by default.
  • Without Remember Me, the token will expire based on the default session expiration defined for the organization, which is set to 10 minutes by default.

You can use the Session API to manually extend the session of a User Token.

Authentication for Affiliated Organizations

If you manage affiliated organizations, you can authenticate as an administrator of the parent organization and then send API requests to perform functions in any of your affiliated organizations—without having to re-authenticate. For instructions on doing this, see Sending Requests for Affiliated (Child) Organizations. Note that you should avoid sharing an administrator account when you manage affiliated organizations, and should therefore create a separate administrator user account to use only with API requests.

API Token Reference

POST /v2/organizations/(organization)/api_tokens

Create API Token

Requires user context. Authenticate as a valid Apperian user.

Creates an API token for the specified user, which can then be used for authentication during automation tasks and other API integrations. Tokens can be created for any user in the system, but you should typically only create tokens for users with the Administrator role. One user can have multiple tokens. Tokens never expire.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/organizations/<organization>/api_tokens
Europe https://eu01ws.apperian.eu/v2/organizations/<organization>/api_tokens

URL Parameters

None

Header Parameters

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

Data Parameters

user
(Required) The user’s identifier.

Example Request

curl -X POST https://na01ws.apperian.com/v2/organizations/<organization>/api_tokens \
     --header "X-TOKEN: ZXqoeaqSR9i8UUWyowDzbQ" --data '{"user": "oBu8rt8HuAqqfJMP8Y-udw"}'

Example Response

{
    "session": {
          "token": "yIVgJFfBQri9A_5eEWKI9A",
          "id": "r08uzMU7-KjX94iDYuY7og"
    }
    "user": {
          "modified_date": "2017-06-12T07:18:25+00:00",
          "first_name": "Michael",
          "last_name": "Harrison",
          "custom_metadata": null,
          "user_id": "oBu8rt8HuAqqfJMP8Y-udw",
          "mobile_phone": "0123456791",
          "role": 5,
          "created_date": "2017-06-12T07:18:25+00:00",
          "until_date": "9999-12-31T23:59:59.999999",
          "disabled_reason": null,
          "email": "mharrison@example.com",
          "last_login_from_catalog": null
    }
}
GET /v2/organizations/(organization)/api_tokens

List API Tokens

Requires user context. Authenticate as a valid Apperian user.

Returns a list of all API tokens in the system and their associated users.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/organizations/<organization>/api_tokens
Europe https://eu01ws.apperian.eu/v2/organizations/<organization>/api_tokens

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

curl -X GET https://na01ws.apperian.com/v2/organizations/<organization>/api_tokens \
     --header "X-TOKEN: ZXqoeaqSR9i8UUWyowDzbQ"

Example Response

{
  "api_tokens": [
      {
          "id": "8VWMdvnNfC7dRp2jctZeDQ"
          "user": {
              "modified_date": "2017-06-12T07:18:25+00:00",
              "first_name": "Michael",
              "last_name": "Harrison",
              "user_id": "mharrison",
              "custom_metadata": null,
              "id": "oBu8rt8HuAqqfJMP8Y-udw",
              "mobile_phone": "0123456791",
              "role": 5,
              "created_date": "2017-06-12T07:18:25+00:00",
              "until_date": "9999-12-31T23:59:59.999999",
              "disabled_reason": null,
              "email": "mharrison@example.com",
              "last_login_from_catalog": null
          },
          "token": "ZIpr-3i-QqCMtf9iIlkIgQ",
          "prune": "2047-06-30T11:37:03.111411+00:00"
      },
      {
          "id": "-eSmcAXQT6gD92aqEz6Urg"
          "user": {
              "modified_date": "2017-06-12T07:18:25+00:00",
              "first_name": "Frank",
              "last_name": "Wilson",
              "user_id": "fwilson",
              "email": "admin@example.com",
              "custom_metadata": null,
              "id": "oBu8rt8HuAqqfJMP8Y-udw",
              "email": "admin@example.com",
              "mobile_phone": "978-457-6334",
              "role": 5,
              "created_date": "2017-06-12T07:18:25+00:00",
              "until_date": "9999-12-31T23:59:59.999999",
              "disabled_reason": null,
              "last_login_from_catalog": null
          },
          "api_token": "qCM-QqCMtfZIpr9iIlkIgQ",
          "prune": "2047-06-30T11:37:03.111411+00:00"
      }
    ]
}
DELETE /v2/organizations/api_tokens/(api_token)

Delete API Token

Requires user context. Authenticate as a valid Apperian administrator.

Deletes the specified API token.

URLs

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

curl -X DELETE https://na01ws.apperian.com/v2/organizations/api_tokens/8VWMdvnNfC7dRp2jctZeDQ \
     --header "X-TOKEN: ZXqoeaqSR9i8UUWyowDzbQ"

Example Response

{
  "deleted": true
}