Policies API

Use the Policies API to manage policies on apps (view applied policies, apply policies, remove policies).

You can also create and manage preset configurations, which are sets of preconfigured policy options that are stored for later use when applying policies to apps.

Before using this API, you should review the Policies API Guide, which provides a detailed overview about how to use the API and the concepts involved.

Resources

GET /v2/policies/

List All Policies

Requires user context. Authenticate as a valid Apperian user.

Returns a list of all policies, including their preset configurations (if applicable).

A configuration is the set of options that should be defined in order for the policy to work as expected. Not all policies have these options.

A preset configuration is one that has been created previously with POST policies/<policy>/configurations/ and stored for later retrieval when applying the policy to an app.

Administrators can define the configuration for a policy when applying the policy to a specific app. It is not necessary to use one of the preset configurations.

URLs

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

URL Parameters

None

Header Parameter

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

Form Parameters

None

Data Parameters

None

Example Request

curl -X GET https://na01ws.apperian.com/v2/policies/ --header "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"

Example Response

This example only includes two policies for the sake of brevity, but the true response will include every policy in your organization.

{
    "policies": [
        {
            "display_name": "App Usage",
            "created": "2018-02-01T03:52:18.281815+00:00",
            "auth_optional": true,
            "display_description": "Tracks whenever users opens the app, foregrounds the app, or returns to
                the app from the lock screen.",
            "is_dynamic": true,
            "supports_ios": true,
            "configurable_fields": null,
            "supports_android": true,
            "configurations": [],
            "id": "XWJKqWeLM5-tp8N09-gTEw",
            "policy_id": "com.apperian.app-usage"
        },
        {
            "display_name": "Enterprise SSO",
            "created": "2018-01-02T14:23:52.620695+00:00",
            "auth_optional": false,
            "display_description": "Restricts access to the app using the same authentication method configured
                for the Admin Portal.",
            "is_dynamic": true,
            "supports_ios": true,
            "configurable_fields": null,
            "supports_android": true,
            "configurations": [],
            "id": "Ynm4meEuG4HOIOu7zwtC3A",
            "policy_id": "com.apperian.enterprise-sso"
        }
    ]
}
GET /v2/policies/(policy)/

List Data for a Policy

Requires user context. Authenticate as a valid Apperian user.

Returns data about a specific policy, including the policy’s preset configurations.

URLs

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

URL Parameters

policy

(Required) Unique ID (id) or reverse domain name ID (policy_id) for the policy, as found in the response of GET /policies/. For example: "id": "Xv_hgo4lqNZ5LHqFpN_yfg" or "policy_id": "com.apperian.app-usage"

DATA TYPE: string

Header Parameter

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

Form Parameters

None

Data Parameters

None

Example Request

curl -X GET https://na01ws.apperian.com/v2/policies/com.apperian.open-webpage-url/
     --header "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"

Example Response

This example displays data for the Open Webpage policy which includes a preset configurations.

{
    "policy": {
        "display_name": "Open Web Page",
        "created": "2018-01-02T14:23:52.620695+00:00",
        "auth_optional": false,
        "display_description": "Opens a browser window to a specified web page after a user opens the app a set
            number of times.",
        "is_dynamic": true,
        "supports_ios": true,
        "configurable_fields": {
            "open_webpage_frequency": {
                "label": "Frequency",
                "type": "text",
                "default": "1",
                "validation": {
                    "type": "number",
                    "required": true,
                    "min": 1
                }
            },
            "open_webpage_url": {
                "label": "Web Page URL",
                "type": "text",
                "default": "",
                "validation": {
                    "type": "url",
                    "required": true
                }
            }
        },
        "supports_android": true,
        "policy_id": "com.apperian.open-webpage-url",
        "id": "A4jwZ8qBV5bf53AeA6lrNA",
        "configurations": [
            {
                "name": null,
                "auth_required": true,
                "enabled_by_default": false,
                "is_a_preset": true,
                "created_time": "2019-02-20T20:45:48.213809+00:00",
                "configuration": {
                    "open_webpage_url": "https://www.google.com",
                    "open_webpage_frequency": "1"
                },
                "id": "lLofenekch0htSr82ojb4w",
                "policy_id": "com.apperian.open-webpage-url"
            }
        ]
    }
}
GET /v2/applications/(application)/policies/

List Policies Applied to an App

Requires administrator privileges. Authenticate as an Apperian administrator.

Returns a list of all policies applied to the requested application and their configuration options. The status parameter in the response indicates the current status of the policy layer and can include the following codes:

  • -1 - ERROR - This indicates that an error has occurred while applying the policy layer.
  • 0 - NO POLICIES - No policies are applied to the app.
  • 1 - POLICIES AND SIGNED - Policies are applied to the app and it is signed. The app is ready to be deployed to
    users.
  • 2 - APPLYING POLICIES - Policies are currently being applied to the app.
  • 3 - POLICIES NOT SIGNED - Policies have been applied to the app and it needs to be signed before deploying to
    users.
  • 4 - POLICIES PREVIOUSLY APPLIED - A previous version of this app had policies applied, but the app has since
    updated to a new version which has not yet been configured with policies.

Note

If the status is 2 - APPLYING POLICIES and you either try to apply policies again or remove policies, you’ll receive a 409 Conflict HTTP response. You should wait until the process is finished before making another request.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/applications/<application>/policies/
Europe https://eu01ws.apperian.eu/v2/applications/<application>/policies/

URL Parameters

application
(Required) Unique ID for the app. DATA TYPE: string

Header Parameter

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/applications/Da7X7EENA0D82j5vA9T5KQ/policies/
    --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

Example Response

{
  "status": {
      "code": 3,
      "description": "POLICIES NOT SIGNED"
  },
  "previous_version_configurations": [],
  "configurations": [
      {
          "policy_id": "com.apperian.app-usage",
          "configuration": null,
          "id": "imsPWFpAYVSIY_FnMvi1fA",
          "auth_required": true
      },
      {
          "policy_id": "com.apperian.open-webpage-url",
          "configuration": {
              "open_webpage_url": "http://www.google.com",
              "open_webpage_frequency": "1"
          },
          "id": "a_uSgM-OGrtfmL9sL8DjaQ",
          "auth_required": true
      }
  ]
}
POST /v2/applications/(application)/policies/

Apply Policies to an App

Requires administrator privileges. Authenticate as an Apperian administrator.

Applies the provided policy configurations to an app, creating a policy layer in the process if necessary. If any policies are currently applied to the app, they will be removed and replaced with the provided policies.

If the app requires modification to add or reapply the policy layer (for example, if static policies are applied or if there’s been an update to the policy layer), the HTTP response code is 202 Accepted. This code also indicates that the app needs to be re-signed.

If the app requires no modification because the policy layer is already applied, the HTTP response code is 202 OK. This code indicates that the app does not need to be re-signed.

Note

Because the applications/<application>/policies/ resource is asynchronous, you can make a GET request to view the policy status for an app at any time, including immediately after you send the POST request.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/applications/<application>/policies/
Europe https://eu01ws.apperian.eu/v2/applications/<application>/policies/

URL Parameters

application
(Required) Unique ID for the app. DATA TYPE: string

Header Parameter

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Content-Type
(Required) Use application/json to identify that the data is being sent in JSON format.

Form Parameters

None

Data Parameters

configurations

(Required) A list of policy configurations to apply to this application. If the list is empty, this request does nothing and returns a 200 OK HTTP response code.

Each item in the list is a JSON object with (at a minimum) the policy_id of the policy being applied, and some other options. If the policy requires (or allows) configuration options, those should be included.

All other attributes within a configurations object, as returned by GET /policies/ or GET /policies/configurations/<configuration>/, are permissible, but will be ignored. This provides the consumer with the convenience of being able to retrieve a preset configuration programmatically and then add it to the configuration list without modification.

The following attributes are processed, all others are ignored:

  • policy_id: (String) The reverse domain name identifier for the policy being applied.
Example: com.apperian.access-control
  • configuration: (JSON Object) If applicable, the configuration parameters for this policy, which are found within the higher-level configurations object. For instance, the App Expiration policy requires an access date range. Some policies do not need a configuration, because they have no options to modify.

Example:

"configuration": {
   "access_date_range": {
       "start": "11/16/2017",
       "end": "11/21/2017"
   }
  • auth_required: (Boolean) Whether authentication is required for this policy.
  • enabled_by_default: (Boolean) When set to “true”, the policy will be enabled by default when applying the policy to an app. This corresponds to the ‘Enabled by Default’ checkbox on the Policies page in the Admin Portal.

Here are some examples of valid configurations data parameters for applying the Open Webpage and App Usage policies:

  1. Including the entire higher-level configurations object:
{"configurations": [
    { "name": "Configuration1",
      "auth_required": true,
      "enabled_by_default": true,
      "created_time": "2017-11-29T22:05:59.986464+00:00",
      "configuration": {
          "open_webpage_frequency": "4",
          "open_webpage_url": "http://www.google.com"
      },
      "id": "h5hgeFbQQUYdoMpbLHCFeA",
      "policy_id": "com.apperian.open-webpage-url"
    },
    {"policy_id": "com.apperian.app-usage"}
    ]
  }
  1. Including only the configuration object:
{"configurations": [
  {"policy_id": "com.apperian.open-webpage-url",
   "configuration": {
          "open_webpage_frequency": "4",
          "open_webpage_url": "http://www.google.com"
      }},
  {"policy_id": "com.apperian.app-usage"}
  ]
}

Example Request

curl -X POST https://na01ws.apperian.com/v2/applications/Da7X7EENA0D82j5vA9T5KQ/policies
    --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg" --header "Content-Type: application/json"
    --data '{"configurations":[
    {"policy_id":"com.apperian.app-usage"},
    {"policy_id":"com.apperian.collect-crash-reports"},
    {"policy_id":"com.apperian.access-control",
    "configuration":{"access_date_range":{"start":"2017-11-16","end":"2017-11-21"}}}]}'

Example Response

{
    "configurations": [
        {
            "id": "Jp_06DHKo7HOKODCBRo8og",
            "policy_id": "com.apperian.app-usage"
        },
        {
            "id": "XiZYWXB6XXL4w2zR_7btvQ",
            "policy_id": "com.apperian.collect-crash-reports",
            "auth_required": true
        },
        {
            "configuration": {
                "access_date_range": {
                    "start": "11/16/2017",
                    "end": "11/21/2017"
                }
            },
            "id": "sPJ8cxZKnAVMMR4EzwWMfA",
            "policy_id": "com.apperian.access-control"
        }
    ]
}
DELETE /v2/applications/(application)/policies/

Remove Policies from an App

Requires administrator privileges. Authenticate as an Apperian administrator.

Removes the policy layer and all policies applied to an app. This endpoint has no return value unless there is an error.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/applications/<application>/policies/
Europe https://eu01ws.apperian.eu/v2/applications/<application>/policies/

URL Parameters

application

(Required) Unique ID for the app.

DATA TYPE: string

Header Parameter

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

Form Parameters

None

Data Parameters

None

Example Request

curl -X DELETE https://na01ws.apperian.com/v2/applications/Da7X7EENA0D82j5vA9T5KQ/policies
    --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

An empty HTTP 204 response on success.

POST /v2/policies/(policy)/configurations/

Create a Preset Policy Configuration

Requires user context. Authenticate as a valid Apperian user.

Create a preset configuration for a specific policy. Preset configurations are a specific set of preconfigured policy options that are stored for later retrieval when applying policies to apps.

You can create multiple preset configurations for each policy, which is not a feature currently available in the Admin Portal.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/policies/<policy>/configurations/
Europe https://eu01ws.apperian.eu/v2/policies/<policy>/configurations/

URL Parameters

policy

(Required) Unique ID (id) or reverse domain name ID (policy_id) for the policy, as found in the response of GET /policies/. For example: "id": "Xv_hgo4lqNZ5LHqFpN_yfg" or "policy_id": "com.apperian.open-webpage-url"

DATA TYPE: string

Header Parameter

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Content-Type
(Required) Use application/json to identify that the data is being sent in JSON format.

Form Parameters

None

Data Parameters

enabled_by_default
When set to “true”, the policy will be enabled by default when applying the policy to an app. This corresponds to the ‘Enabled by Default’ checkbox on the Policies page in the Admin Portal.
name
You can give the configuration a name to differentiate it from other configurations.
configuration

Defines options for the policy. The available options are in the configuration object which is found within the higher-level configurations object in the response of GET /policies/ or GET /policies/configurations/(configuration_id)/.

When passing this in the request, copy the entire configuration object from the response and modify the options as necessary. For example, from the App Expiration policy:

"configuration": {
                "open_webpage_url": "https://www.google.com",
                "open_webpage_frequency": "1"
            },

Example Request

curl -X GET https://na01ws.apperian.com/v2/policies/com.apperian.open-webpage-url/configurations/
     --header  "Content-Type: application/json" --header  "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"
     --data  '{"enabled_by_default": true,
               "name": "Configuration2",
               "configuration": {
                    "open_webpage_url": "https://www.google.com",
                    "open_webpage_frequency": "1"
                }}'

Example Response

{
    "configuration": {
        "name": "Configuration2",
        "enabled_by_default": true,
        "configuration": {
                    "open_webpage_url": "https://www.google.com",
                    "open_webpage_frequency": "1"
        },
        "id": "JLokdoL69ELhGzB0ZypQDg",
        "policy_id": "com.apperian.open-webpage-url"
    }
}
GET /v2/policies/configurations/(configuration)/

List Data for a Preset Policy Configuration

Requires user context. Authenticate as a valid Apperian user.

Returns data about a specific policy configuration.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/policies/configurations/<configuration>/
Europe https://eu01ws.apperian.eu/v2/policies/configurations/<configuration>/

URL Parameters

configuration

(Required) Unique configuration ID (id), as found in within a policy’s configurations object from the response of GET /policies/ or GET /policies/<policy>/. For example: "id": "h5hgeFbQQUYdoMpbLHCFeA"

DATA TYPE: string

Header Parameter

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

Form Parameters

None

Data Parameters

None

Example Request

curl -X GET https://na01ws.apperian.com/v2/policies/configurations/h5hgeFbQQUYdoMpbLHCFeA/
     --header "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"

Example Response

{
    "configuration": {
        "name": null,
        "auth_required": true,
        "enabled_by_default": false,
        "is_a_preset": true,
        "created_time": "2019-02-20T20:45:48.213809+00:00",
        "configuration": {
            "open_webpage_url": "https://www.google.com",
            "open_webpage_frequency": "1"
        },
        "id": "lLofenekch0htSr82ojb4w",
        "policy_id": "com.apperian.open-webpage-url"
    }
}
PUT /v2/policies/configurations/(configuration)/

Update a Preset Policy Configuration

Requires user context. Authenticate as a valid Apperian user.

Update the options for an existing preset configuration with new values based on data sent in the request. A preset configuration is one that has been created previously with POST policies/<policy>/configurations/ and stored for later retrieval.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/policies/configurations/<configuration>/
Europe https://eu01ws.apperian.eu/v2/policies/configurations/<configuration>/

URL Parameters

configuration

(Required) Unique configuration ID (id), as found in within a policy’s configurations object from the response of GET /policies/ or GET /policies/<policy>/. For example: "id": "h5hgeFbQQUYdoMpbLHCFeA"

DATA TYPE: string

Header Parameters

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Content-Type
(Required) Use application/json to identify that the data is being sent in JSON format.

Form Parameters

None

Data Parameters

enabled_by_default
When set to “true”, the policy will be enabled by default when applying the policy to an app. This corresponds to the ‘Enabled by Default’ checkbox on the Policies page in the Admin Portal.
name
You can give the configuration a name to differentiate it from other configurations.
configuration

Defines options for the policy. The available options are in the configuration object which is found within the higher-level configurations object in the response of GET /policies/ or GET /policies/configurations/(configuration_id)/.

When passing this in the request, copy the entire configuration object from the response and modify the options as necessary. For example, from the App Expiration policy:

"configuration": {
            "access_date_range": {
                "start": "11/16/2017",
                "end": "11/21/2017"
            },

Example Request

curl -X PUT https://na01ws.apperian.com/v2/policies/configurations/com.apperian.open-webpage-url/
     --header "Content-Type: application/json" --header  "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"
     --data  '{"enabled_by_default": true,
               "name": "Configuration1",
               "configuration": {
                    "open_webpage_url": "https://www.google.com",
                    "open_webpage_frequency": "1"
                }}'

Example Response

{
    "configuration": {
        "name": "Configuration1",
        "auth_required": true,
        "enabled_by_default": true,
        "created_time": "2017-11-29T22:05:59.986464+00:00",
        "configuration": {
                    "open_webpage_url": "https://www.google.com",
                    "open_webpage_frequency": "1"
        },
        "id": "h5hgeFbQQUYdoMpbLHCFeA",
        "policy_id": "com.apperian.open-webpage-url"
    }
}
DELETE /v2/policies/configurations/(configuration)/

Delete a Preset Policy Configuration

Requires user context. Authenticate as a valid Apperian user.

Delete a preset configuration from a policy.

URLs

Environment URL
North America https://na01ws.apperian.com/v2/policies/configurations/<configuration>/
Europe https://eu01ws.apperian.eu/v2/policies/configurations/<configuration>/

URL Parameters

configuration

(Required) Unique configuration ID (id), as found in within a policy’s configurations object from the response of GET /policies/ or GET /policies/<policy>/. For example: "id": "h5hgeFbQQUYdoMpbLHCFeA"

DATA TYPE: string

Header Parameter

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

Form Parameters

None

Data Parameters

None

Example Request

curl -X DELETE https://na01ws.apperian.com/v2/policies/configurations/cw8hGkhsKXGKvhA7OBmsbQ/
    --header  "X-TOKEN: yCczCnsNSJyW_3JyS6YwAQ"

Example Response

No response body unless there is an error.