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 - 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 of 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`	User who originally created this service account Required: href	Object	Yes
`updated_by`	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 - 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`	User who originally 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 for 24.2.20 and 24.2.10