There are separate CMA pages for the two types of API keys:
- API Keys - for personal use of individual admins
- Service Keys - for shared use between different service principals
Cato lets you generate API keys in the Cato Management Application (CMA) that are used to authenticate API calls to the Cato API server. Enter the API key for an API client, code, scripts, Terraform, SIEM integration, MCP, and more to securely interact with Cato services.
These are the types of API keys:
- Admin API Keys are personal keys tied to your admin account, which you use for your own API workflows. You can only create admin API keys for yourself. For more information, see below Admin API Keys.
- Service API Keys are shared keys used by system processes, automation, or third-party integrations. These keys are not tied to an individual admin login and are best suited for operational use cases. For more information, see below Service Principal API Keys.
Cato provides granular support for two levels of API calls:
-
Query APIs - Perform read-only API calls to retrieve data for your account
Viewer permissions let you only run query API calls. This applies whether the permissions are assigned through a role or limited to specific CMA pages.
-
Configuration APIs - Perform write API calls to make configuration changes to your account
Edit permissions let you only run configuration or query API calls. This applies whether the permissions are assigned through a role or limited to specific CMA pages.
To authenticate requests to the Cato API, include an HTTP header named x-api-key in your API client. Set the value of this header to your Cato API key using the format: x-api-key: <api-key>. For example: x-api-key: abcdef12345. This header authorizes your request and grants access to the relevant Cato API endpoints based on the permissions associated with your key.
A service principal admin is a special type of CMA admin created specifically for API-based workflows. To securely support system integrations and automation processes, create service principal admins for your account. This allows you to generate API keys that are decoupled from personal login credentials and can't be used to access the CMA.
The service principal admin credentials are used exclusively for API authentication with a corresponding service API key. This setup enhances security and enforces the separation of duties for automated operations.
Note: A new CMA admin with the name Automation Service Principal (Editor) is automatically created as part of adding the Service Principal API key to existing accounts.
To create a service principal admin:
- From the navigation menu, click Account > Administrators.
-
Click New.
The Create Administrator panel opens.
- Select Create New, and Create as Service Principal.
- Enter the General settings for the admin.
-
Select the Role and any specific sites and users that will define the permissions for this admin. To learn about roles, see Managing Admin Roles Using RBAC.
These permissions will be applied to the Service Principal API key.
- Click Apply. The admin is added to the Administrators page, and the service principal admin is automatically activated.
The API Keys and Service API Keys pages let you generate and revoke API keys. The Name for the API key is only used to identify each key and isn't used as part of the authentication process.
For additional security, you can restrict the source IPs or IP range (CIDR) for API and Service API keys.
Note: Make sure that you copy the API key value from the pop-up window. Once you close the pop-up window, you can't access the key value again.
When you need to support your own automation workflows as an individual admin, create an admin API Key that is tied to your CMA admin credentials. You can only create admin API keys for your own use, not for other admins, and only via the CMA.
When an admin is deleted, the associated API key is automatically deactivated. If an admin is disabled, the key is marked as Disabled, and API calls using it will return an error.
RBAC Permissions for Admin API Keys
- Each admin API key inherits the RBAC permissions and roles of the admin who created it. The permissions update dynamically if the admin’s RBAC roles change, including permissions for specific sites, user groups, groups, etc...
- Admins with the Viewer role can see all the API key information (not the actual key value)
- Admins with an Editor RBAC role that includes the API Keys page can see the API keys in the account and also revoke (delete) them
To generate an admin API key:
- In the navigation menu, click Resources > Admin API Keys.
- Click New. The Create API Key panel opens.
- Enter a Key Name.
- To apply view-only permissions for this key, select Downgrade to View.
-
(Optional) For additional security, in Allow access from IPs, select Specific IP list, and define the IP addresses or IP range that are allowed to use this API key.
The default setting is to allow this API key for Any IP address.
-
(Optional) Select a date that the API key Expires at.
For API keys with Edit permissions, we recommend setting a date that the API key will Expire at.
- Click Apply. The API key is added to the page, and a pop-up window containing the value for the new API key is displayed.
-
Click the button to copy the API Key that is generated by the CMA and save it to a secure location.
Once you close this window, you can't access the value for the API key.
- Click OK to close the pop-up window.
When you need to support shared operational or integration workflows, create a service API Key from the Service API Keys page. These keys are designed for use by automation services and scripts that do not require access to the CMA. They are connected to the service principal admin who created the key.
Service API Keys can be used across systems and teams, enabling scalable integration with external tools and services. These types of keys aren't tied to a CMA admin and are intended for backend operations or continuous delivery pipelines.
RBAC Permissions for Service API Keys
- Only admins with the Editor role can create or manage service principal API keys
- Each service API Key inherits the RBAC permissions and roles of the service principal admin associated with the key. If the RBAC permissions for the admin change, then the service principal API key is automatically updated with the new permissions.
To generate a service API key:
- In the navigation menu, click Resources > Service API Keys.
- Click New. The Create API Key panel opens.
- Select the Service Principal who is associated with this key.
- Enter a Key Name.
- To apply view-only permissions for this key, select Downgrade to View.
-
(Optional) For additional security, in Allow access from IPs, select Specific IP list, and define the IP addresses or IP range that are allowed to use this API key.
The default setting is to allow this API key for Any IP address.
-
(Optional) Select a date that the API key Expires at.
For API keys with Edit permissions, we recommend setting a date that the API key will Expire at.
- Click Apply. The API key is added to the page, and a pop-up window containing the value for the new API key is displayed.
-
Click the button to copy the API Key that is generated by the CMA and save it to a secure location.
Once you close this window, you can't access the value for the API key.
- Click OK to close the pop-up window.
You can revoke the API key and remove it from the CMA. Once revoked, the key can't be used to authenticate to the API server.
8 comments
Added information about API keys for the Cato Configuration API.
It would be better if we could configure IPs using specific Subnet in “Allow access from IPs”
Is it not possible at this time to add a range / subnet of IP's to whitelist for those cloud applications?
nazmul.hossain and Rafael Escobar excellent suggestions. Currently you can only define single IPs, but I let Product Management know about the recommended enhancement. Thanks!
Would it be possible to update the content on this page? There is a dependency of “make sure to select ‘Enable integration’ in the Events Integration tab”, and the first image under Managing API Keys, shows a field Enable CATO Events API which I believe there is no longer available and can lead to confusion.
Also a second there to ask the “Allow access from IPs” using a subnet and that the configuration can be editable since that can change, and requires to generate a new Key if one of the IPs changes or we need to add a new IP.
José Luis Fernandes Esteves - Thank you for letting us know that this article was out of date, I updated it and it now shows the correct information.
Regarding ‘Allow access from IPs’, an excellent suggestion! I forwarded it to Product Management, and I also suggest that you open an RFE.
When I create an Admin account, I don't have the option to create a service account. I've got new or existing.
Does something else need enabling, or is this a licensing restriction?
Thanks, Simon
The article mentions that Service API Keys are connected to the admin who created them, but later says they are not tied to a CMA admin. These statements appear contradictory.
Please clarify on this.
Please sign in to leave a comment.