API Keys
API keys provide a persistent means of authenticating with the PCE and are recommended for script writing.
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 and owners, so that they can 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 when deleted).
Important
Any tooling that parses the HTTP headers should be changed to allow case-insensitive header name matching to retain 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