Skip to main content

REST APIs for 23.5

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