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 Req
href URI of the pairing profile String Yes
name The short friendly name of the pairing profile.
Supports partial matches. 		String  
description The long description of the pairing profile.
Supports partial matches. 		String  
mode DEPRECATED AND REPLACED
(Use enforcement_mode instead)		 String  
enforcement_mode

Filter by mode. Has four modalities:

  •  idle: Limited visibility. VEN does not take control of the
    workload IP tables(Linux) or Windows firewall (Windows).
  • visibility_only: No traffic is blocked by policy.
  • full: Segmentation rules are enforced for all inbound and
    outbound services. Traffic not allowed by the segmentation
    rule is blocked.
  • selective: Segmentation rules are enforced only for the
    |selected inbound services when workload is within the
    scope of the Selective Enforcement rule.
    • Selective enforcement applies only to managed workloads;
    it applies neither to NEN-controlled nor to other unmanaged
    workloads.
 String  
status VEN should be in idle state when it activates 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_user_per_key

The number of times the pairing profile can be used.

Integer (min 1)

String

  
key_lifespan

Number of seconds pairing profile keys will be valid for.

Integer (min 1)

String

  
last_pairing_at Timestamp when this pairing profile was last used for pairing
a workload		 String  
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

Href:

 

User who originally created this pairing profile

Object

String

  
updated_by

Href

 

User who last updated this pairing_profile

Object

String

  
is_default Flag indicating this is default auto-created pairing profile Boolean  
       
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  
env_label_lock Flag that controls whether env label can be overridden from
the pairing script		 Boolean  
loc_label_lock

Flag that controls whether loc label can be overridden from

the pairing script

 Boolean  
role_label_lock

Flag that controls whether role label can be overridden from

the pairing script

 Boolean  
app_label_lock

Flag that controls whether app label can be overridden from

the pairing script

 Boolean  
mode_lock

DEPRECATED AND REPLACED (USE /enforcement_mode_lock INSTEAD) Flag that controls whether mode can be overridden

from the pairing script.

    
enforcement_mode_lock Flag that controls whether enforcement mode can be overridden
from pairing script		 Boolean  
visibility_level Visibility level of the workload (DEPRECATED VALUE: 'flow_full_detail') String  
visibility_level_lock

Flag that controls whether visibility_level can be overridden from

the pairing script

 Boolean  
status_lock

Flag that controls whether status can be overridden from

the pairing script

 Boolean  
external_data_set External data set identifier String
Null		  
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 External data reference identifier String
Null		  
enforcement_mode_lock Flag that controls whether enforcement mode can be overridden
from the pairing script		 Boolean  
status_lock

Flag that controls whether status can be overridden from

the pairing script

 Boolean  
agent_software_release Agent software release associated with this paring profile String
Null		  

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"
    },
    "enforcement_mode": "full",
    "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,
    "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,
    "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"
  },
  "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 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

FunctionalityHTTPURI
Create a pairing keyPOST

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