API Keys

API keys provide a persistent means of authentication with the PCE and are recommended for scripting purposes.

This Public Stable API allows local users to create user API keys and use them as credentials to access the PCE.

There are two categories of API keys:

User-based API keys
These keys are based on specific owners, allowing them to make API calls to the PCE.
Service-based API keys
These API keys are based on a service instead of a specific user.

Working with API Keys

When you create an API key, you receive an api_username and secret, which function as the username and password for making API calls.

An API key is permanent and does not expire, unless it is deleted.

Important

Any tooling that parses HTTP headers should be modified to support case-insensitive header name matching, thereby retaining compatibility with future PCE releases.

Refer to RFC 7230, section 3.2, "Header Fields," which states that field names should be case-insensitive.

Use API keys to write scripts that run automatically without requiring a human user to authenticate the API call. Unless you are a read-only user, you can create multiple API keys and make API calls in your scripts.

You can also create different API keys for various functions. For example, you might use one API key to script automatic workload pairing and another API key to collect system events from Illumio.

When you create an API key, the response returns both the auth_username and the secret needed for authenticating other API calls:

API username:
"auth_username":"api_xxxxxxxxxxx29" (represented in the code examples in this document as $KEY)
API key secret: "secret":"xxxxxxx5048a6a85ce846a706e134ef1d4bf2ac1f253b84c1bf8df6b83c70d95" (represented in the code examples in this document as $TOKEN)

Get a Collection of all API Keys

You can now get a list of all API keys, both user-based and service account-based.

To query API keys regardless of their type, use this API:

GET /api/v2/orgs/:xorg_id/api_keys

Special Characters in API Calls

If a username or name in an API call contains special characters, these must be encoded for the call to succeed.

For example, for a service account name sa&1, instead of

api/v2/orgs/1/api_keys?type=service_account&name=sa&1

Enter the call as

api/v2/orgs/1/api_keys?type=service_account&name=sa%261

Query Keys by Expiration

To retrieve the API keys based on the expiration (active or expired) use these APIs:

GET /api/v2/orgs/:xorg_id/api_keys?type=service_account&state=expired

GET /api/v2/orgs/:xorg_id/api_keys?type=service_account&state=active

Create API Keys in the Web Console

You can create API keys using the Web console with the User Menu:

In the drop-down User menu, select My API Keys.
A list of configured API keys is displayed.
The message "No API Keys" is displayed if no API keys are configured.
To add a new API key, click Add.
In the Create API Key pop-up window, enter the name of the API key in the Name field. Optionally, enter a description in the Description field.
Click Save to save your API key or Cancel to close the pop-up window without saving your changes.
When the API Key Created window appears, click the > button next to "Show credentials" to display the credentials for your API key.
The following information is displayed:
- Key ID: The unique ID of the API key
- Authentication Username: The username that authenticates the API calls
- Secret: The password for the API key
Click Download Credentials to download the credentials as a text file. Ensure that you have saved the credential information before clicking Done.

After you click Done, the API Keys page displays a summary of your new API key, including the following information:

Name
Description
Key ID
Authentication Username
Created On

Note

The credential information is displayed only once. Ensure that you save it in a secure location, as it is used to access the API for your organization. You must create a new API key if you lose your credential information.

Service Account-based API Keys

Service account-based APIs enable the creation and management of API keys associated with a service account.

You can manage the expiration of service account-based API keys.

Note

When Service Accounts were introduced, the following restriction was explicitly added: a Service Account cannot be used to operate on service accounts and user-related resources.

In release 23.4.0, this restriction has been removed: a Service Account api_key can perform most operations, similar to a user api_key, except for APIs that require user context. There were no changes to the APIs to support this restriction removal.

Service accounts are always organization-based and specific to a PCE.

Users create their permissions while creating a service account, and an API key is implicitly created. Deleting a service account removes its permissions and all associated API keys.

Service-based API Key Methods

Table 1. Service-based API Key Methods

Functionality	HTTP	URI
List all service account API keys.	`GET`	[api_version][org_href]/api_keys?type=service_account
To retrieve a specific service account	`GET`	[api_version][org_href]/service_accounts/:service_account_id
To retrieve all API keys, regardless of the account	`GET`	api_keys
Create a new service account API key.	`POST`	[api_version][org_href]/service_accounts
To create a new service account API key after performing the required validation	`POST`	[api_version][org_href]/service_accounts/:service_account_id/api_keys
Update a service account.	`PUT`	[api_version][org_href]/service_accounts/:service_account_id
Delete a service account API key.	`DELETE`	[api_version][org_href]/service_accounts/:service_account_id/api_keys/:key_id
Delete a service account that includes any associated API keys.	`DELETE`	[api_version][org_href]/service_accounts/:service_account_id

The expiration time of service account-based API keys is defined by owners who can specify the default expiration time.

The key expiration time is specified with a default value in the settings, where the expiration date of an existing API key cannot be modified.

When an expired API key authenticates an API request, the request is rejected, and the audit event triggered by this failure includes the API key's Key ID and its expired status. The details also include the expiration date and the last_used_at date.

Settings

Settings for service account-based API keys specify the default expiration period for service account keys and the retention period for expired keys.

The Public Experimental APIs that manage API key settings are based on the role of the organization administrator (this_org_admin)) and are as follows:

Support for viewing api_key settings for an organization.
GET /api/v2/orgs/:xorg_id/settings
This API now includes the new property num_assets_requiring_ransomware_protection, which defines several assets that need ransomware protection for this organization.
Support for updating api_key settings for an organization.
PUT /api/v2/orgs/:xorg_id/setting
API key expiration is now set between -1 and 2147483647 seconds, and expired key retention is a minimum of 0 seconds.

The settings_put.schema.json was changed to include the new property num_assets_requiring_ransomware_protection. The number of assets that require ransomware protection in a specific organization ranges from one to 9999999.

The new property ven_maintenance_token identifies if the tampering protection for the VEN and endpoints is enabled. The default is not enabled.

User-based API Keys

This Public Stable API allows you to manage API keys and make API calls to the PCE.

Working with User-based API Keys

Table 2. User API Key Methods

Functionality	HTTP	URI
Get a collection of API keys	`GET`	[api_version][user_href]/api_keys
Get an individual API key	`GET`	[api_version][api_key_href]
Create an API key	`POST`	[api_version][user_href]/api_keys
Update an API key	`PUT`	[api_version][api_key_href]
Delete an API key	`DELETE`	[api_version][api_key_href]

List User-based API Keys

When you GET an individual API key or a collection of API keys, the response only returns those created by the user who authenticated with the PCE for the session.

This API gets one API key or a collection of API keys created by a specific user. To get a single API key, you need to know the API key’s URI, which is returned as an HREF path when you create an API key, and the HREF of the user who created the key.

You can query the user API keys as follows:

GET /api/v2/orgs/:xorg_id/api_keys?type=user

You can also query the user-based API keys based on their expiration:

GET /api/v2/orgs/:xorg_id/api_keys?type=user&state=active

GET /api/v2/orgs/:xorg_id/api_keys?type=user&state=expired

GET [api_version][user_href]/api_keys

Create User-based API Keys

This API creates a unique API key and returns an API key ID and secret. You can use these to obtain, update, or delete the key and make other API calls.

To create an API key, you must authenticate using a session token or another API key. To obtain a session token, use the Users API and authenticate with the PCE. You will receive your user ID, user HREF, and a session token that you can use when you call this API to create an API key.

Important

If you use an API key, safely store the key and the secret. Anyone with access to both will have access to the API for your organization.

Important

Due to security concerns, external users are unable to create an API Key, even if their roles permit it.

Update User-based API Keys

This API enables you to update the name or description of an API key.

To make this call, you need the API key URI, which is returned as an HREF path when you create a User-Based API Key.

PUT [api_version][api_key_href

Delete User-based API Keys

To delete an API key, you need the unique API key ID, which is returned as an HREF path property when you create a new API key or get a single or a collection of API keys.

DELETE [api_version][api_key_href]

API Keys Reference

This topic covers parameters, properties, and examples for API keys.

Parameters

Parameter	Description	Type
`user_id`	The user ID in the form of an HREF (e.g., '`users/6`') of the user who created the API key.	String
`api_key_id`	This is the actual API key ID. It is used only for DELETE.	String
`org_id`	Organization ID	Integer
`max_results`	The maximum number of api keys to return.	Integer
`username`	The username of the user to filter by	String
`name`	(POST, PUT, GET) The key name - just a label to be used	String
`role`	Role URI (JSON-encoded string) to filter on	String
`state`	State of api keys - active or expired	String
`type`	Type of principal - User or Service Account	String

Some parameters have been renamed or deprecated to allow differentiation between the type userand service_account:

Query parameter nameis retained for the type service_account
Query parameter nameis changed to username for the type user
Query parameter service_account_name was deprecated and consolidated to name
Query parameter api_key_name was deprecated and removed as not needed

Properties

Property	Description	Type
`key_id`	This is the actual API key ID. Use this query parameter only for a GET instance call.	String
`auth_username`	Username required for authentication	String
`created_at`	Timestamp when this key was first created (RFC 3339)	String
`name`	The key name is just a label to be used.	String
`href`	URI of the key	date/time

Examples

Curl Command to Get a Key

The API key is identified in the form of an HREF path property:

"/users/11/api_keys/a034248fbcdd60b4"

curl -i -X GET https://pce.my-company.com:8443/api/v2/users/11/api_keys/a034248fbcdd60b4 -H "Accept: application/json" -u $KEY:$TOKEN

Get a Collection of Keys

To use an API key, store the key and secret safely. Anyone with access to both has access to your organization's API.

Due to security concerns, external users are not allowed to create an API Key even if their roles allow it.

curl -i -X GET https://pce.my-company.com:8443/api/v2/users/11/api_keys -H "Accept: application/json" -u $KEY:$TOKEN

Response Body

An API key is represented by its HREF path, as shown here:

/users/29/api_keys/1e9bb1787883639d5

For example:

[
  {
    "href": "/users/29/api_keys/1e9bb1787883639d5",
    "key_id": "1e9bb1787883639d5",
    "auth_username": "api_1e9bb1787883639d5",
    "created_at": "2020-01-27T01:30:22.274Z",
    "name": "my_api_key",
    "description": "my_scripting_key"
  },
  {
    "href": "/users/29/api_keys/1793df73a99255f7e",
    "key_id": "1793df73a99255f7e",
    "auth_username": "api_1793df73a99255f7e",
    "created_at": "2016-03-14T16:20:43.603Z",
    "name": "MyKey",
    "description": "My Special Key"
  }
]

Get All Labels with a Key

If you use an API key to get a collection of labels in an organization, and your API key uses these credentials:

api_xxxxxxx64fcee809 is the API key
xxxxxxx09137412532289d6ecd10bc89c6b1f608c9a85482e7a573 is the secret (API key password)

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/labels -H "Accept: application/json" -u api_xxxxxxx64fcee809:'xxxxxxx09137412532289d6ecd10bc89c6b1f608c9a85482e7a573'

This document represents session and persistent (API key) credentials as the constants $KEY:$TOKEN (without spaces).

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/labels -H "Accept: application/json" -u $KEY:$TOKEN

Examples to Create API Keys

URI

POST [api_version][user_href]/api_keys

An example user HREF looks like this:

/users/99

{
     "name": "my_api_key",
     "description": "my_scripting_key"
}

To create a user-based API key

In this curl command, the user authentication (-u) uses the session credentials returned from calling the Login API to log in a user. The API key is passed as a JSON object formatted inside double quotes in the command:

curl -i -X POST https://pce.my-company.com:8443/api/v2/users/14/api_keys -H "Content-Type:application/json" -u user_14:'xxxxxxx563199f92af7b705ddca2685'-d "{ "name":"my_api_key","description":"my_scripting_key" }"

Response Body

This example shows the response from creating an API key, which you can use for making other API calls. These values do not expire. The auth_username functions as the username, and the secret functions as the password when making other API calls:

{
     key_id: "xxxxxxx6654188229"
     secret: "xxxxxxxxxxxa6a85ce846a706e134ef1d4bf
              2ac1f253b84c1bf8df6b83c70d95"
     auth_username: api_xxxxxxx6654188229
}

These values can now be used to authenticate with the API as follows:

Username: api_xxxxxxx29api_xxxxxxx6654188229
Password: xxxxxxxxxxxa6a85ce846a706e134ef1d4bf2ac1f253b84c1bf8df6b83c70d95

Parameters for Service-based API Keys

Parameter	Description	Type	Required
`org_id`	Organization ID.(GET, POST, PUT, DELETE)	Integer	Yes
`max_results`	Maximum number of service accounts to return (GET)	Integer	No
`name`	Name of service account to filter by	String	No(GET) Yes(POST)
`role`	Role URI (JSON-encoded string) to filter on(GET)	String	No
`service_account_id`	Service account UUID (GET account info, DELETE, PUT, POST)	String	Yes
`api_key_id`	API Key ID (DELETE)	String	Yes

Properties for Service-based API Keys

Property	Description	Type	Required
`name`	Service account name	String	Yes
`href`			Yes
`created at`	Timestamp when this service account was first created (RFC 3339)	date/time	Yes
`updated_at`	Timestamp when this service account was last updated	date/time	Yes
`created_by`	The user who created this service account Required: href	Object	Yes
`updated_by`	The user who last updated this service account	String	Yes
`permissions`	List of permissions: required: `role`, `scope`	Array	Yes
`role`	Reference to `common/orgs_roles.schema.json`
`scope`	Reference to `org_scope.schema.json`
`api_keys`	List of associated api_keys Reference to `api_keys_get.schema.json`		Yes
`api_key`	required: "expires_in_seconds" "type": "integer", "minimum": -1, "maximum": 2147483647	Object
`access_restriction`	Access restriction assigned to the keys created under this service_account	Object, Null	No
`href`	URI of service_account	String
`api_keys`	List of associated api_keys Reference to `api_keys_get.schema.json`	Array	No
`expires_in_seconds`	Validity of the api_key, in seconds "type": "integer", "minimum": -1, "maximum": 2147483647	String	No
`last_login_on`	Timestamp when this key was last used	date/time
`account`	required: "href": Associated identity "type": Type of the account "name": Name of the account		Yes Yes Yes
`service_account_id`	API Key ID (DELETE)	String	No
`api_key_id`	API Key ID (DELETE)	String	Yes

Parameters for api_keys_get (all API keys)

Parameter	Description	Type	Required
`key_id`	Key ID	String	Yes
`auth_username`	Username required for authentication	String	Yes
`name`	The key name is just a label to be used	String	Yes
`role`	Role URI (JSON-encoded string) to filter on(GET)	String	No
`service_account_id`	Service account UUID (GET account info, DELETE, PUT, POST)	String	No
`api_key_id`	API Key ID (DELETE)	String	No

Response Properties for api_keys_get (all API keys)

Property	Description	Type	Required
`key_id`	Key ID	String	Yes
`auth_username`	Username required for authentication	String	Yes
`created at`	Timestamp when this service account was first created (RFC 3339)	date/time	Yes
`name`	Service account name	String	Yes Yes
`href`	URI of the key	String	Yes
`state`	State of the api_key	String	No
`expires_in_seconds`	Validity of the api_key, in seconds	String	No
`created_by`	The user who created this api key	String	No
`last_login_on`	Timestamp when this key was last used Examle: "last_login_on": "2023-04-22T03:54:25Z"	date/time
`account`	required: "href": Associated identity "type": Type of the account "name": Name of the account		Yes Yes Yes
`access_restriction`	Access restriction assigned to the keys created under this service_account	Object, Null
`permissions`	List of permissions: required: `role`, `scope`	Array	Yes
`role`	Reference to `common/orgs_roles.schema.json`
`scope`	Reference to `org_scope.schema.json`

Create a new Service Account API Key

Request

{
	"name": "key3",
	"description": "testing key 3",
	"access_restriction": {
		"href": "/orgs/1/access_restrictions/2"
		},
	"permissions": [
		{
		"role": { "href": "/orgs/1/roles/ruleset_manager"},
		"scope": [
		{
			"label": {
			"href": "/orgs/1/labels/9",
			"key": "env",
			"value": "Development"
		}
	}
	]
},
{
		"role": { "href": "/orgs/1/roles/owner" },
		"scope":  []
	}
],
	"api_key": {
	"expires_in_seconds": 86400
	}
}

Response

{
	"name": "service_account1",
	"description": "testing service_account",
	"href": "/orgs/1/service_accounts/33ed7e04-9b25-
                 4c9a-a031-a6b1bd437807",
	"access_restriction": {
		"href": "/orgs/1/access_restrictions/2"
		},
	"permissions": [
		{
		"href": "/orgs/1/permissions/84e5541f-3349-
                        41c9-8fdb-9756faf96baa",
		"role": {"href": "/orgs/1/roles/ruleset_manager"
			},
		"scope": [
			{
			"label": {
			"href": "/orgs/1/labels/9"
		}
	}
	]
},
{
		"role": {
			"href": "/orgs/1/roles/owner"
		},
		"scope": []
		}
	],
	"api_key": {
		"auth_username": "api_135c247aa6e3b654e",
	"secret": "ab80cc497f7556e0cd72703c5229d814322c
                  301d14d2d8d8c7060d516990097b"
	}
}

REST APIs 25.2.10

API Keys

Working with API Keys

Important

Get a Collection of all API Keys

Special Characters in API Calls

Query Keys by Expiration

Create API Keys in the Web Console

Note

Service Account-based API Keys

Note

Service-based API Key Methods

Settings

User-based API Keys

Working with User-based API Keys

List User-based API Keys

Create User-based API Keys

Important

Important

Update User-based API Keys

Delete User-based API Keys

API Keys Reference

Parameters

Properties

Examples

Examples to Create API Keys

Parameters for Service-based API Keys

Properties for Service-based API Keys

Parameters for api_keys_get (all API keys)

Response Properties for api_keys_get (all API keys)

Create a new Service Account API Key

Search results