Pairing Profiles and Pairing Keys

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

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 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 Asynchronous GET Collection.

Create a Pairing Profile

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

URI to Create a Pairing Profile

POST [api_version][org_href]/pairing_profiles

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]

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]

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

You need a pairing profile HREF to pass as a parameter to create a pairing key. 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

Pairing Profiles and Pairing Keys Reference

This topic contains properties and examples for pairing profiles and keys.

GET a collection of Pairing Profiles

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'

Parameters for Pairing Profiles

Parameter	Description	Type
`org_id`	Organization ID
`agent_software_release`	The agent software release for pairing profiles.
`description`	The long description of the pairing profile.	String
`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
`external_data_reference`	External data reference identifier	String Null
`name`	The short, friendly name of the pairing profile. Supports partial matches.	String
`labels[]`	Return only pairing profiles with all these labels specified in the pairing profile. Labels are structured in JSON as a list of lists of label HREFs.	Array
`ven_type`	Specifies the pairing profile by the VEN type: server, endpoint, or specified_during_activation	String

Properties for Pairing Profiles

All properties are required:

Property	Description	Type
`name`	The short, friendly name of the Pairing Profile	String
`description`	The long description of the pairing profile. Supports partial matches.	String
`mode`	Reference to the common schema `legacy_workload_modes.schema.json`	String
`enabled`	The enabled flag of the pairing profile	Boolean
`total_use_count`	The number of times the Pairing Profile has been used	Integer
`allowed_uses_per_key`	The number of times the pairing profile can be used. Minimum: 1	String
`key_lifespan`	The number of seconds pairing profile keys will be valid. Minimum: 1	Integer (min 1)
`last_pairing_at`	Timestamp when this pairing profile was last used for pairing a workload	String NULL
`created_at`	Timestamp when this pairing profile was first created	String date-time
`updated_at`	Timestamp when this pairing profile was last updated	String date-time
`created_by`	The user who originally created this pairing profile Reference by common schema `href_object.schema.json`	Object String
`updated_by`	The user who last updated this pairing_profile Reference by common schema `href_object.schema.json`
`last_pairing_key_generated_at`	Timestamp of when the last pairing key was generated Null Referenced by the common shema `href_object.schema.json`	String, Null date/time
`last_pairing_key_generated_by`	The user who generated the last pairing key
`is_default`	Flag indicating this is the default auto-created Pairing Profile.	Boolean
`labels`	Reference to `labels.schema.json`
`env_label_lock`	A flag that controls whether env label can be overridden from the pairing script	Boolean
`loc_label_lock`	A flag that controls whether loc label can be overridden from the pairing script	Boolean
`app_label_lock`	A flag that controls whether app label can be overridden from the pairing script	Boolean
`enforcement_mode_lock`	A flag that controls whether enforcement mode can be overridden from the pairing script	Boolean
`mode_lock`	DEPRECATED AND REPLACED \| (USE /`enforcement_mode_lock` INSTEAD) A flag that controls whether mode can be overridden from the pairing script.	Boolean
`log_traffic`	DEPRECATED AND REMOVED. Alerting status	Boolean
`log_traffic_lock`	DEPRECATED AND REMOVED. A flag that controls whether log_traffic can be overridden from the pairing script	Boolean
`visibility_level_lock`	A flag that controls whether visibility_level can be overridden from the pairing script	Boolean
`status_lock`	A flag that controls whether status can be overridden from the pairing script	Boolean
`external_data_set`	External data set identifier	String, Null
`external_data_reference`	External data reference identifier	String, Null
`agent_software_release`	Agent software release associated with this paring profile	String, Null
`ven_type`	Referenced to `common/pairing_profile_ven_type.schema.json`

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

The 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"]
}

Example Request Body for a Pairing Profile

{
  "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}'

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}'

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'

Request Body for a Pairing Key

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 24.2.20 and 24.2.10