REST APIs for 22.5

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

If a usernameor name in an API call contains special characters, these have to be encoded for the call to be successful.

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 

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

This API gets one API key or a collection of API keys that a specific user has created. To get a single API key, you need to know the API key’s URI, which is returned in the form of an HREF path when you create an API key, as well as 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

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": "2016-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:

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

Session and persistent (API key) credentials are represented in this document as the constants $KEY:$TOKEN (with no spaces).

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

This API creates a unique API key and returns an API key ID and secret, which you can use to get, update, or delete the key, and to make other API calls.

To create an API key, you first need to authenticate either 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.

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: "xxxxxxxxxxxa6a85ce846a706e134ef1d4bf2ac1f253b84c1bf8df6b83c70d95"
     auth_username: api_xxxxxxx6654188229
}

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

This API allows you to update an API key name or description. To make this call, you need the API key URI, which is returned in the form of an HREF path when you Create a User-Based API Key.

Update a User-based API Key

PUT [api_version][api_key_href

Example Payload

{
     "name": "my_api_key1",
     "description": "my_scripting_key v2"
}

curl -i -X POST https://pce.my-company.com:8443/api/v2/users/99/api_keys/a034248fbcdd60b4 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{ "name": "my_key_1", "description": "my_scripting_key v2" }'

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

URI to Delete a User-based API Key

DELETE [api_version][api_key_href]

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

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

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

{
	"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
	}
}

{
	"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": "ab80cc497f7556e0cd72703c5229d814322c301d14d2d8d8c7060d516990097b"
	}
}