Service Account-based API Keys
Service account-based APIs allow for the creation and management of API keys based on a service account
You can manage the expiration of service account-based API keys.
Note
When Service Accounts were introduced, the following restriction was explicitly added: a Service Account cannot be used to operate on service accounts and on user-related resources.
In release 23.4.0, this restriction has been removed: a Service Account api_key can perform most of the operations like the user api_key, except for APIs that require user context. There were no changes to the APIs to support this restriction removal.
Service accounts are always organization-based and specific to a PCE.
Users create their permissions while creating a service account, and an api_key implicitly gets created. Deleting a service account removes its permissions and all associated API keys.
Service-based API Key Methods
Functionality | HTTP | URI |
|---|---|---|
List all service account API keys. |
| [api_version][org_href]/api_keys?type=service_account |
To retrieve a specific service account |
| [api_version][org_href]/service_accounts/:service_account_id |
To retrieve all API keys, regardless of the account |
| api_keys |
Create a new service account API key. |
| [api_version][org_href]/service_accounts |
To create a new service account API key after performing the required validation |
| [api_version][org_href]/service_accounts/:service_account_id/api_keys |
Update a service account. |
| [api_version][org_href]/service_accounts/:service_account_id |
Delete a service account API key. |
| [api_version][org_href]/service_accounts/:service_account_id/api_keys/:key_id |
Delete a service account including any associated API keys. |
| [api_version][org_href]/service_accounts/:service_account_id |
The expiration time of service account-based API keys is defined by owners who can specify the default expiration time.
The key expiration time is specified with a default value specified in the settings, where the expiration date of an existing API key cannot be modified.
When an expired API key authenticates an API request, the request is rejected, and the audit event triggered by this failure includes the API key's Key ID and the expired status of the API Key. The details also include the expiration date and the last_used_at date.
Settings
Settings for service account-based API keys specify the default expiration period for service account keys and the retention period for expired keys.
The Public Experimental APIs that manage API key settings are based on the role of the organization administrator (this_org_admin) and are as follows:
Support for viewing api_key settings for an organization.
GET /api/v2/orgs/:xorg_id/settingsThis API now includes the new property num_assets_requiring_ransomware_protection, which defines several assets that need ransomware protection for this organization.
Support for updating api_key settings for an organization.
PUT /api/v2/orgs/:xorg_id/settingAPI key expiration is now set between -1 and 2147483647 seconds, and expired key retention is a minimum of 0 seconds.
The settings_put.schema.json was changed to include the new property num_assets_requiring_ransomware_protection. The number of assets that need ransomware protection in a specific organization is between one and 9999999.
The new property ven_maintenance_token identifies if the tampering protection for the VEN and endpoints is enabled. The default is not enabled.