Sending Requests for Affiliated (Child) Organizations

An affiliated organization is an organization created through the Admin Portal (not the Apperian registration page) by the administrator of another organization—a “parent” organization. If you are a large company, for example, you can create an affiliated organization for each of your business units or subsidiaries.

Once an affiliated organization is created, it is like any organization created through the registration page; it will have its own set of users, groups, App Catalogs, applications, and settings. The difference is that an affiliated organization can be managed by both its own administrators and the administrators of the parent organization. While an administrator of a parent organization can manage any of its affiliated organizations, an administrator at an affiliated organization cannot manage its parent organization.

When you authenticate through the Apperian API as an administrator of a parent organization, you can send API requests to perform functions in any of your affiliated organizations without having to re-authenticate. To specify which organization you want to manage with a particular request, include org/org_id after v1 in the URL of the request. For example, the following request lists all users in the organization with an org_id of Xv_hgo4lqNZ5LHqFpN_yfl. 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.

GET /v1/org/Xv_hgo4lqNZ5LHqFpN_yfl/users

Note

org_id can be either a direct descendant (child) or indirect descendant (grandchild) of the parent organization.

Optionally, you can specify org/org_id when you want to perform a function in the parent organization, but this is not required. If org/org_id is not included in the request, Apperian processes the request for the organization of the authenticated user.

To return a list of org_ids for all your affiliated organizations, use the Organizations API.

For more information on the Affiliated Organizations feature, see Managing Affiliated Organizations.

Example

Authenticate as Administrator of Parent Organization

Before you can send a request to perform a function in one of your affiliated organizations, you need to retrieve a valid authentication token for an administrator in the parent organization. The following cURL command authenticates an administrator of the parent organization. Note that it is not necessary to include org/org_id when you send a request for the parent organization, but you can if desired.

Request

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

Response

{
  "organization": {
    "psk": 101,
    "app_installation_path": "Enterprise Apps",
    "name": "Example Company"
  },
  "token": "2TyfJMVaRd2D7QrMFYjc_A",
  "user": {
    "status": "enabled",
    "psk": 99286,
    "first_name": "Robert",
    "last_name": "James",
    "modified_date": "2016-03-17T19:25:15+00:00",
    "email": "admin@example.com",
    "disabled": false,
    "mobile_phone": "123-098-0987",
    "role": 5,
    "created_date": "2013-04-24T16:40:35+00:00",
    "until_date": "9999-12-31T23:59:59.999999",
    "id": "admin@example.com",
    "last_login_from_catalog": "2016-03-07T11:37:20.096122"
  }
}

Add a User to An Affiliated Organization

This cURL command adds a new user to an affiliated organization that has an org_id of Xv_hgo4lqNZ5LHqFpN_yfl.

Request

curl -X POST https://na01ws.apperian.com/v1/org/Xv_hgo4lqNZ5LHqFpN_yfl/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}'

Successful Response

{
  "user_psk": 103029
}

If the specified org_id is not a valid ID for an organization that is affiliated with the authenticated user’s organization (or is not the ID of the parent organization), Apperian returns the following error.

Error Response

{
  "error": {
    "code": 10,
    "message": "Organization Xv_hgo4lqNZ5LHqFpN_yfl is unknown to this user.",
    "guid": "37a0d173-0d69-415a-a52e-6eeb783ed083",
    "error_details": null
  }
}