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

Pairing Profiles and Pairing Keys Reference

GET a collection of Pairing Profiles

Parameters for Pairing Profiles

Properties for Pairing Profiles

Examples of query parameters for filtering pairing profiles

Search results