Organizations API

Use the Organizations API to return information about all the EASE organizations on which the authenticated user can operate. This information includes an org_id for each organization. An org_id is the unique identifier that EASE assigns to each organization. If you manage any affiliated (child and grandchild) organizations, you can authenticate through the API as an EASE administrator of a parent organization and send API requests to perform functions in any of the affiliated organizations without having to re-authenticate; this is done by including the org_id in the URL of the request. For more information, see Sending Requests for Affiliated (Child) Organizations.

API Tokens API tokens are unique user authentication credentials used for integrating with the Apperian API. Tokens are especially useful for automated tasks or processes, but can replace user authentication credentials (username and password) for any API call. Apperian recommends using this method of authentication to integrate with the Apperian API. 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.

Resources

GET /v1/organizations/

List Organizations

Returns information about all the organizations on which the authenticated user can operate. If the authenticated user is an EASE administrator (user with the “Administrator” role), the list includes the user’s organization, its parent organization (if there is one) and any affiliated (child and grandchild) organizations. If the user is not an administrator, the list includes the user’s organization only.

The response identifies the org_id for each listed organization. If you are working in an EASE organization that has affiliated organizations, you can include org_id in an API request to perform functions in any of your affiliated organizations without having to re-authenticate. For more information, see Sending Requests for Affiliated (Child) Organizations.

URLs

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

URL Parameters

None

Header Parameters

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

Data Parameters

None

Example Request

The following cURL request returns information about the authenticated user’s organization, the parent organization, and the two affiliated organizations (sub_orgs).

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

Example Response

{
  "parent_id": null,
  "name": "HoneyBee's Organic Honey",
  "id": "Aegm9Dfmsbb4dSxpt8lZTjA",
  "sub_orgs": [
    {
      "sub_orgs": [],
      "parent_id": "Aegm9Dfmsb34dSxpt8lZTjA",
      "name": "Honey From the West",
      "id": "XTBEV_SGPlI0oI8ozGTh0A"
    },
    {
      "sub_orgs": [],
      "parent_id": "Aegm9aDfmsb4dSxpt8lZTjA",
      "name": "Honey from the East",
      "id": "Vj9lkP0txgod4BMIyzMvxQ"
    }
  ]
}
POST /v2/organizations/(org_id)/api_tokens

Create API Token

Requires user context. Authenticate as a valid EASE 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/<org_id>/api_tokens
Europe https://eu01ws.apperian.eu/v2/organizations/<org_id>/api_tokens

URL Parameters

None

Header Parameters

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

Data Parameters

user
(Required) The user’s identifier.

Example Request

curl -X POST https://na01ws.apperian.com/v2/organizations/<org_id>/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/(org_id)/api_tokens

List API Tokens

Requires user context. Authenticate as a valid EASE 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/<org_id>/api_tokens
Europe https://eu01ws.apperian.eu/v2/organizations/<org_id>/api_tokens

URL Parameters

None

Header Parameters

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

Data Parameters

None

Example Request

curl -X GET https://na01ws.apperian.com/v2/organizations/<org_id>/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 EASE administrator.

Deletes the specified API token.

URLs

URL Parameters

None

Header Parameters

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

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
}