Pairing Profiles and Pairing Keys

The Public Stable 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`
Get the specified pairing profile	`GET`	`[api_version][org_href]/pairing_profile_href`
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

Parameter	Description	Type	Required
`org_id`	Organization		Yes
`agent_software_release`	The agent software release for pairing profiles.		No
`description`	The long description of the pairing profile. Supports partial matches.	String	Yes
`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 NULL	No
`external_data_reference`	External data reference identifier	String Null	No
`name`	The short friendly name of the pairing profile. Supports partial matches.	String	No for GET
`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	No
`pairing_profile_id`	A specific profile, for POST when creating a Pairing key) pairing profile ID	Integer	Yes

The properties returned for pairing profiles are as follows:

Response Properties

Property	Description	Type	Required
`description`	The long description of the pairing profile. Supports partial matches.	String	Yes
`enabled`	The enabled flag of the pairing profile	Boolean	Yes
`mode`	DEPRECATED AND REPLACED (Use `enforcement_mode` instead)	String	Yes
`href`	URI of the pairing profile	String	Yes
`name`	The short friendly name of the pairing profile. Supports partial matches.	String	Yes
`enforcement_mode`	Reference to `common/workload_enforcement_mode.schema.json`		No
`enforcement_mode_lock`	Flag that controls whether enforcement mode can be overridden from pairing script	Boolean	No
`agent_software_release`	Agent Software Release associated with this Pairing Profile	Strin, NULL
`visibility_level`	Visibility level of the workload (DEPRECATED VALUE: '`flow_full_detail'`)	String	Yes
`visibility_level_lock`	Flag that controls whether visibility_level can be overridden from pairing script	Boolean	Yes
`total_use_count`	The number of times the pairing profile has been used	Integer	Yes
`allowed_uses_per_key`	The number of times the pairing profile can be used.	Integer (min 1) String	Yes
`key_lifespan`	Number of seconds pairing profile keys will be valid for.	Integer (min 1) String	Yes
`last_pairing_at`	Timestamp when this pairing profile was last used for pairing a workload	String NULL	Yes
`created_at`	Timestamp when this pairing profile was first created	String date-time	Yes
`updated_at`	Timestamp when this pairing profile was last updated	String date-time	Yes
`created_by`	User who originally created this pairing profile	Object String
`updated_by` `Href`	User who last updated this pairing_profile	Object String
`env_label_lock`	Flag that controls whether env label can be overridden from pairing script	Boolean	Yes
`loc_label_lock`	Flag that controls whether loc label can be overridden from pairing script	Boolean	Yes
`role_label_lock`	Flag that controls whether role label can be overridden from pairing script	Boolean	Yes
`app_label_lock`	Flag that controls whether app label can be overridden from pairing script	Boolean	Yes
`mode_lock`	DEPRECATED AND REPLACED \| (USE /e`nforcement_mode_lock` INSTEAD) Flag that controls whether mode can be overridden from the pairing script.	Boolean	Yes
`log_traffic`	DEPRECATED AND REMOVED. Alerting status	Boolean	Yes
`log_traffic_lock`	DEPRECATED AND REMOVED. Flag that controls whether log_traffic can be overridden from pairing script	Boolean	Yes
`status_lock`	Flag that controls whether status can be overridden from pairing script	Boolean	No
`last_pairing_key_generated_at`	Timestamp of when the last pairing key was generated"	String, Null date/time	Yes
`last_pairing_key_generated_by`	User who generated the last pairing key	String, Null	Yes

Examples of query parameters for filtering pairing profiles:

Filter by Name:

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

Filter by Description:

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

Filter by software release:

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

Response Body

Response includes generated pairing keys

{
     "href": "/orgs/4002/pairing_profiles/4101",
     "name": "org 3 pp 1",
     "description": "org 3 pp 1",
     "total_use_count": 0,
     "enabled": true,
     "is_default": false,
     "created_at": "2022-01-21T00:44:16.863Z",
     "updated_at": "2022-01-21T00:44:16.863Z",
     "created_by": {"href"=>"/users/0"},
     "updated_by": {"href"=>"/users/0"},
     "mode": "illuminated",
     "enforcement_mode": "visibility_only",
     "key_lifespan": "unlimited",
     "allowed_uses_per_key": "unlimited",
     "last_pairing_at": nil,
     "last_pairing_key_generated_at": "2022-01-21T00:49:13.841Z",  
     "last_pairing_key_generated_by": {"href"=>"/users/6"},
     "labels": [{"href"=>"/orgs/4002/labels/4104"}],
     "env_label_lock": true,
     "loc_label_lock": true,
     "role_label_lock": true,
     "app_label_lock": true,
     "mode_lock": true,
     "enforcement_mode_lock": true,
     "log_traffic": false,
     "log_traffic_lock": true,
     "visibility_level": "flow_summary",     
      "visibility_level_lock": true,
      "agent_software_release": "Default (19.3.0)",
      "caps": ["write", "generate_pairing_key"]
}

Create a Pairing Profile

This method creates an individual pairing profile. The only required parameter for POST method is enabled, others are optional.

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"
  },
  "enforcement_mode": "visibility_only",
  "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,
  "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"},"enforcement_mode":"visibility_only","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,"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"},"enforcement_mode":"visibility_only","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,"visibility_level":"flow_summary","visibility_level_lock":true}'

Delete a Pairing Profile

To delete an individual pairing profile, specify its HREF that 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 "{}"

REST APIs for 22.5