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'

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. Supports partial matches.	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 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
`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`	Number of seconds pairing profile keys will be valid for. 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`	User who originally created this pairing profile Reference by common schema `href_object.schema.json`	Object String
`updated_by`	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 Refenced 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`	The flag that controls whether env label can be overridden from the pairing script	Boolean
`loc_label_lock`	The flag that controls whether loc label can be overridden from the pairing script	Boolean
`app_label_lock`	The flag that controls whether app label can be overridden from pairing script	Boolean
`enforcement_mode_lock`	The flag that controls whether enforcement mode can be overridden from pairing script	Boolean
`mode_lock`	DEPRECATED AND REPLACED \| (USE /e`nforcement_mode_lock` INSTEAD) 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. The flag that controls whether log_traffic can be overridden from pairing script	Boolean
`visibility_level_lock`	The flag that controls whether visibility_level can be overridden from pairing script	Boolean
`status_lock`	The flag that controls whether status can be overridden from 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"]
}

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 23.5