Skip to main content

REST APIs for 23.5

Session Credentials

While API keys provide a persistent means of authenticating with the PCE, session credentials provide a temporary means of authenticating so you can make Illumio REST API calls.

Important

Any tooling that parses the HTTP headers should be changed to allow case-insensitive header name matching to remain compatible with future PCE releases. For more information, refer to RFC 7230, section 3.2, "Header Fields," which states that field names should be case-insensitive.

Choose a session token or an API key, depending on your programming needs.

Session Credentials and Tokens

When you create session credentials, an auth_username and session token are returned, which function as temporary usernames and passwords for making API calls.

Session credentials are used to make all Illumio REST API calls that require authentication and are composed of an auth_username and a token. They expire after not being used for 30 minutes and reset for another 30 minutes if used within the 30-minute window.

The session token expires after 10 minutes of inactivity.

When to Use a Session Token

An auth_username and session token are useful for one-time use of the API or testing the API. To write a script that performs a one-time use of the API with a session token, use the Login API to create the auth_username and session token. Use those credentials to make other API calls in the script, and then once the script has run, the session token immediately expires when the user logs out.

What Does a Session Token Look Like?

When you authenticate with the PCE using the Login API, the response returns the credentials needed to make other API calls:

  • Your username: "auth_username": user_3

  • Your session token: "session_token":"xxxxxxx563199f92af7b705ddca26854205b5233"

To use the Illumio REST API:

  1. Call login_users/authenticate using the e-mail address and password you used to create your PCE account to obtain an authentication token.

    Note

    The authorization token expires after 30 seconds, so have the next call formed and ready to paste onto the terminal window before calling login_users/authenticate.

  2. Call users/login with the authentication token to obtain temporary session credentials.

Use Login API to Create Session Credentials

Unless you're using persistent API credentials, whenever you want to access the Illumio REST API, you must authenticate with the PCE using an auth username and a session token. To create these session credentials, call GET /users/login with the authentication token previously returned by a call to POST /login_users/authenticate.

URI

GET [api_version]/users/login
API Call Using Session Credentials

Once you obtain an auth_username and session token from the PCE, you use them to make API calls.

For example, suppose you want to use this session token to get a collection of labels in an organization using the Labels API. In that case, the curl command can be written as shown below using the following authentication:

  • auth_username: user_3

  • Session Token: xxxxxxx563199f92af7b705ddca26854205b5233

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