Pairing Profiles and Pairing Keys

The Public Experiment API for pairing profiles gets, creates, updates, and deletes pairing profiles.

The Public Stable API for pairing keys creates a pairing key to use for pairing workloads.

About Pairing Profiles and Keys

Pairing profiles apply specific properties to workloads as they pair with the PCE, such as labels and the workload policy state.

When you configure a pairing profile, the pairing script contains a unique pairing key at the end of the script (activation-code) that identifies the VEN securely so it can authenticate with the PCE. You can configure a pairing key for one-time use or more, and you can also set time and use limits.

The Pairing Key API can generate a new pairing key from a specified pairing profile.

Pairing Profile Methods

Functionality	HTTP	URI
Get a collection of pairing profiles	`GET`	`[api_version][org_href]/pairing_profiles`
Create an individual pairing profile	`POST`	`[api_version][org_href]/pairing_profiles`
Update an individual pairing profile	`PUT`	`[api_version][pairing_profile_href]`
Delete an individual pairing profile	`DELETE`	`[api_version][pairing_profile_href]`

Get Pairing Profiles

This method allows you to get a collection of all pairing profiles in your organization or just an individual pairing profile.

By default, the maximum number returned on a GET collection of pairing profiles is 500. For more than 500 pairing profiles, use an Asynchronous GET Collection.

URI to Get a Collection of Pairing Profiles

GET [api_version][org_href]/pairing_profiles

Curl Command to Get Collection of Pairing Profiles

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/1/pairing_profiles -H 'Accept: application/json' -u $KEY:'TOKEN'

Query Parameters

The following optional query parameters can restrict the results of the query when getting a collection of pairing profiles.

Parameter	Description	Type
`labels[]`	Return only pairing profiles that have all of these labels specified as part of the pairing profile. Labels are structured in JSON as a list of lists of label HREFs.	Array
`name`	Name of the pairing profiles to return. Supports partial matches.	String
`description`	Description of the pairing profiles to return. Supports partial matches.	String
`max_results`	The maximum number of results you want to return when using the GET method. The maximum limit for returned pairing profiles is 500. For more than 500 pairing profiles, use an Asynchronous GET Collection.	Integer
`external_data_set`	The data source from which the resource originates. For example, if the pairing profile information is stored in an external database.	String
`external_data_reference`	A unique identifier within the external data source. For example, if the pairing profile information is stored in an external database.	String

Examples of query parameters for filtering pairing profiles:

Filter by Name:

/api/v2/orgs/1/pairing_profiles?name=prod_app

Filter ny Description:

/api/v2/orgs/1/pairing_profiles?description=”some description string”

Filter by software rlease:

/api/v2/orgs/1/pairing_profiles?agent_software_release=”xx.x.x”

(where the release starts with 17.2.0)

Response Body

{
    "href": "/orgs/1/pairing_profiles/24",
    "name": "AutoScale App",
    "description": "PP_Description",
    "total_use_count": 0,
    "enabled": true,
    "is_default": false,
    "created_at": "2016-06-08T23:13:29.019Z",
    "updated_at": "2016-06-08T23:18:36.150Z",
    "created_by": {
      "href": "/users/1"
    },
    "updated_by": {
      "href": "/users/1"
    },
    "mode": "enforced",
    "key_lifespan": "unlimited",
    "allowed_uses_per_key": 1,
    "last_pairing_at": null,
    "labels": [],
    "env_label_lock": false,
    "loc_label_lock": false,
    "role_label_lock": false,
    "app_label_lock": false,
    "mode_lock": false,
    "log_traffic": true,
    "log_traffic_lock": false,
    "visibility_level": "flow_summary",
    "visibility_level_lock": false
  },
  {
    "href": "/orgs/1/pairing_profiles/27",
    "name": "Security Key Pack",
    "description": "",
    "total_use_count": 1,
    "enabled": true,
    "is_default": false,
    "created_at": "2016-06-30T18:12:22.141Z",
    "updated_at": "2016-06-30T18:13:50.668Z",
    "created_by": {
      "href": "/users/1"
    },
    "updated_by": {
      "href": "/users/57"
    },
    "mode": "illuminated",
    "key_lifespan": "unlimited",
    "allowed_uses_per_key": "unlimited",
    "last_pairing_at": "2016-06-30T18:13:50.668Z",
    "labels": [
      {
        "href": "/orgs/1/labels/153"
      },
      {
        "href": "/orgs/1/labels/154"
      },
      {
        "href": "/orgs/1/labels/155"
      },
      {
        "href": "/orgs/1/labels/156"
      }
    ],
    "env_label_lock": true,
    "loc_label_lock": true,
    "role_label_lock": true,
    "app_label_lock": true,
    "mode_lock": true,
    "log_traffic": false,
    "log_traffic_lock": true,
    "visibility_level": "flow_summary",
    "visibility_level_lock": true
  },

Create a Pairing Profile

This method creates an individual pairing profile.

URI to Create a Pairing Profile

POST [api_version][org_href]/pairing_profiles

Example Request Body

{
  "href": "/orgs/2/pairing_profiles/12375",
  "name": "Limited Pairing",
  "description": "",
  "total_use_count": 0,
  "enabled": true,
  "is_default": false,
  "created_at": "2015-11-01T01:20:06.135Z",
  "updated_at": "2015-11-01T01:20:06.135Z",
  "created_by": {
    "href": "/users/18"
  },
  "updated_by": {
    "href": "/users/18"
  },
  "mode": "illuminated",
  "key_lifespan": "unlimited",
  "allowed_uses_per_key": "unlimited",
  "last_pairing_at": null,
  "labels": [
    {
      "href": "/orgs/2/labels/6"
    },
    {
      "href": "/orgs/2/labels/14"
    },
    {
      "href": "/orgs/2/labels/8"
    },
    {
      "href": "/orgs/2/labels/12"
    }
  ],
  "env_label_lock": false,
  "loc_label_lock": false,
  "role_label_lock": false,
  "app_label_lock": false,
  "mode_lock": true,
  "log_traffic": false,
  "log_traffic_lock": true,
  "visibility_level": "flow_summary",
  "visibility_level_lock": true
}

Curl Command to Create Pairing Profile

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/pairing_profiles -H "Content-Type:application/json" -u $KEY:'TOKEN'-d '{"href":"/orgs/2/pairing_profiles/12375","name":"Limited Pairing","description":"","total_use_count":0,"enabled":true,"is_default":false,"created_at":"2015-11-01T01:20:06.135Z","updated_at":"2015-11-01T01:20:06.135Z","created_by":{"href":"/users/18"},"updated_by":{"href":"/users/18"},"mode":"illuminated","key_lifespan":"unlimited","allowed_uses_per_key":"unlimited","last_pairing_at":null,"labels":[{"href":"/orgs/2/labels/6"}, "href":"/orgs/2/labels/14"},"href":"/orgs/2/labels/8"},"href":"/orgs/2/labels/12"}],"env_label_lock":false,"loc_label_lock":false,"role_label_lock":false,"app_label_lock":false,"mode_lock":true,"log_traffic":false,"log_traffic_lock":true,"visibility_level":"flow_summary","visibility_level_lock":true}'

Update a Pairing Profile

To update a pairing profile, specify its HREF, which can be obtained from getting a collection of pairing profiles.

URI to Update a Pairing Profile

PUT [api_version][pairing_profile_href]

Curl Command to Update Pairing Profile

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/pairing_profiles -H "Accept: application/json" -u $KEY:'TOKEN'-d '{"href":"/orgs/2/pairing_profiles/12375","name":"Limited Pairing","description":"","total_use_count":0,"enabled":true,"is_default":false,"created_at":"2015-11-01T01:20:06.135Z","updated_at":"2015-11-01T01:20:06.135Z","created_by":{"href":"/users/18"},"updated_by":{"href":"/users/18"},"mode":"illuminated","key_lifespan":"unlimited","allowed_uses_per_key":"one_use","last_pairing_at":null,"labels":[{"href":"/orgs/2/labels/6"},{"href":"/orgs/2/labels/14"},{"href":"/orgs/2/labels/8"},{"href":"/orgs/2/labels/12"}],"env_label_lock":false,"loc_label_lock":false,"role_label_lock":false,"app_label_lock":false,"mode_lock":false,"log_traffic":false,"log_traffic_lock":true,"visibility_level":"flow_summary","visibility_level_lock":true}'

Delete a Pairing Profile

To delete an individual pairing profile, specify its HREFthat you can obtain from a collection of pairing profiles.

URI to Delete a Pairing Profile

DELETE [api_version][pairing_profile_href]

Curl Command to Delete Pairing Profile

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/pairing_profiles/12375 -H "Accept: application/json" -u $KEY:'TOKEN'

Pairing Key API Method

Functionality	HTTP	URI
Create a pairing key	`POST`	`[api_version][org_href]/pairing_profiles[pairing_profile_href]/pairing_key`

Create a Pairing Key

To create a pairing key, you need a pairing profile HREF to pass as a parameter. You can obtain the pairing profile HREF from the Pairing Profile page in the PCE web console.

A pairing key is governed by the parameters configured in the pairing profile.

URI to Create a Pairing Key

Obtain the pairing key HREF from the response body returned by an API call to get a collection of pairing keys.

POST [api_version][pairing_key_href]/pairing_key

Request Body

The request body is an empty JSON object.

{}

Curl Command to Create Pairing Key

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/3/pairing_profiles/34/pairing_key -H 'Content-Type: application/json' -u $KEY:'TOKEN' -d "{}"