Documentation | Support

Go to the table of contents Go to the previous page Go to the next page View or print as PDF
Introduction > Management API object types
Management API object types
Management API Guide | Forcepoint Web Security | v8.5.x
There are 3 object types recognized by the Management API:
*
Categories
*
URLs
*
IP addresses
Categories
When you start using the Management API, the first step is to create an API-managed category and obtain its unique category ID.
*
The category must be identified by name or ID when adding URLs and IP addresses.
*
You can add URLs and IP addresses only to API-managed categories. An attempt to use another category (that is, a Forcepoint URL Database category or custom category created via the Forcepoint Security Manager) is considered an error, which causes the request to fail.
API-managed categories may include the following attributes:
*
Name (required): When creating an API-managed category, you must give it a unique, alphanumeric name.
*
The name cannot contain any of the following characters:
* < > { } ~ ! $ % & @ # . " | \ & + = ? / ; : ,
*
The category name and ID must be unique within the deployment. An API-managed category cannot be given the same name as an existing Forcepoint-defined or custom category.
*
The category name appears in the Forcepoint Security Manager and in reports.
*
You may specify either the category name or ID (see below) to add, delete, modify, or view URLs and IP addresses.
*
ID (required): When you create an API-managed category, it is automatically assigned a unique ID.
*
The ID is a number with a value of 1899 or higher.
*
After committing a transaction, use the list categories command to find each new API-managed category's unique ID (see List API-managed categories or all categories).
*
Description (optional): The category description, if any, appears both in the Security Manager and in the response to the API call used to view the category. It may contain alphanumeric characters, periods, and commas. It cannot include any of the following characters:
* < > { } ~ ! $ % & @ # " | \ & + = ? / ; :
*
Level (optional): When you add an API-managed category, you can also define a parent category.
*
If the parent category does not exist, it is added along with the child category.
*
If not otherwise defined, the parent category is assigned the default value of 0 (Miscellaneous).
Up to two levels of subcategory may be added under Miscellaneous. For example:
Miscellaneous
First_Level_Child_Category
Second_Level_Child_Category
The Miscellaneous category is a Forcepoint-defined category that cannot be changed.
If administrators attempt to add URLs or IP addresses to anything other than an API-managed category, a 400 (bad request) error is returned. This indicates that the category name or ID is invalid because it:
*
Does not exist
*
Belongs to a Forcepoint-defined category
*
Belongs to a custom category defined via the Security Manager
URLs
URLs in the system are defined according to RFC 3986.
*
Only the hostname field (part of the authority) is required.
*
Other parts are optional, but can be used to define a stricter match.
*
CGI parameters (anything after the "?" in a URL) are automatically removed from the URL before it is saved in the Management API local database.
*
If no protocol is specified, the Management API automatically adds all 3 of the following to its database: http://, https://, and ftp://.
Use Punycode to add URLs containing non-ASCII characters to API-managed categories.
URLs can be added to more than one API-managed category with multiple calls to the add methods (see Add URLs and IP addresses to an API-managed category). When the URL is matched, all categories for the URL are returned for use in policy enforcement.
IP addresses
IP addresses and ranges are as specified by RFC-791 (IPv4) and RFC 4291 (IPv6).
IP addresses and ranges can be added as an element under an API-managed category. The destination IP address for a URL request is checked against the IP addresses and ranges added via the API. If the IP address is matched, the category containing that IP address is added to the list of categories detected by the product.
IP addresses and ranges can be added to more than one API-managed category with multiple calls to the add methods (see Add URLs and IP addresses to an API-managed category). When an IP address is matched, all categories for the IP address are returned for use in policy enforcement.
 

Go to the table of contents Go to the previous page Go to the next page View or print as PDF
Introduction > Management API object types
Copyright 2022 Forcepoint. All rights reserved.