Web Security Cloud - API Documentation

API docs by Redocly

API Key Management (1.0.0)

Download OpenAPI specification:

License: MIT

Token Management Public API

This API enables customers to generate a bearer access token to call the Custom Categories API.

Authentication
Requests to the Token Management API require an API token (api-key-string) to be passed in the header. To generate this API token, go to the Platform Services > Admin in the Web Security Cloud and click the Generate API Token.
Now that the api-key-string has been generated, a bearer access token can be created using the Generate bearer access token endpoint.

Generate bearer access token

Generate a bearer access token that can be used for authorization purpose.

Token Validity: The generated bearer access token is valid for 59 minutes after creation.

header Parameters
X-API-KEY
required
string
Example: api-key-string

In this header you will have to pass your api key

Responses

Response samples

Content type
application/json
{
  • "token": "token-string"
}

command

Indicates that the operation is a command and modifies the state of the system

query

Indicates that the operation is a query and just queries the system with no state change

Custom Category API

This API enables customers to manage Custom Categories via API endpoints instead of the portal.

Audience
This API guide is intended for:

- Developers who integrate and manage Custom Categories via API endpoints instead of using the portal.
- Software Engineers responsible for implementing API-based automation within their organization.
- System Administrators who configure and maintain API access for managing Custom Categories.

Authentication
All requests to the Custom Category API require authentication using bearer access tokens. Clients must include a valid bearer access token in the Authorization header of each request.

Example Header:
Authorization: Bearer YOUR_BEARER_ACCESS_TOKEN

To obtain a bearer access token, see the Token Management Public API.

Get all custom categories

API path to retrieve all custom categories for the account.

Authorizations:
custom-authorizer
query Parameters
cursor
string

Cursor for pagination

Responses

Request samples 

import requests

def get_categories(
  url:str, headers, next_page_cursor: str = ""
) -> object:
    """Get all categories."""
    querystring = {"cursor": next_page_cursor}
    response = requests.request(
        "GET",
        url,
        data="",
        headers=headers,
        params=querystring,
    )
    print(response.text)
    return response

token = ""            # Insert bearer access token here
next_page_cursor = "" # Insert nextPageCursor value from previous response here (OPTIONAL: Leave empty string)

host = "https://ws-custom-categories.api.forcepoint.io"
api_version = "1.0.0"
headers = {"Authorization": f"Bearer {token}"}
url = f"{host}/v{api_version}"

get_categories(url, headers, next_page_cursor)

Response samples

Content type
application/json
{
  • "totalResults": 0,
  • "nextPageCursor": "string",
  • "categories": [
    ]
}

Create a new category

API path to create a new custom category for the account.

Authorizations:
custom-authorizer
Request Body schema: application/json
required
name
required
string
description
string
sites
Array of strings <= 30000 items

List of website URLs and IP addresses

policyName
string

Policy level custom category created via API will appear in the UI after the Enable custom categories per policy toggle on Web › Custom Categories page is turned on

comment
string

Comment field appears in "Get Transaction Status" response, not in Cloud Web portal

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "sites": [
    ],
  • "policyName": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Get category and site counts and limits

API path to retrieve the number of sites, number of custom categories, site limits and custom category limits for the account.

Authorizations:
custom-authorizer

Responses

Request samples 

import requests

def get_limits(url:str, headers:object) -> object:
    """Get number of sites, number of custom categories, site limits and custom category limits."""
    response = requests.request(
        "GET",
        url,
        data="",
        headers=headers,
    )
    print(response.text)
    return response

token = ""            # Insert bearer access token here

host = "https://ws-custom-categories.api.forcepoint.io"
api_version = "1.0.0"
headers = {"Authorization": f"Bearer {token}"}
url = f"{host}/v{api_version}/limits"

get_limits(url, headers)

Response samples

Content type
application/json
{
  • "customCategoryCount": 1,
  • "customCategoryUrlCount": 1,
  • "customCategoryLimit": 1,
  • "customCategoryUrlLimit": 1
}

Get category by ID

API path to retrieve the details of a specific custom category by providing its ID.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

query Parameters
cursor
string

Cursor for pagination

Responses

Request samples 

import requests

def get_category_by_id(
  url:str, headers, next_page_cursor: str = ""
) -> object:
    """Get category by id."""
    querystring = {"cursor": next_page_cursor}
    response = requests.request(
        "GET",
        url,
        data="",
        headers=headers,
        params=querystring,
    )
    print(response.text)
    return response

token = ""            # Insert bearer access token here
category_id = 0       # Insert category id here
next_page_cursor = "" # Insert nextPageCursor value from previous response here (OPTIONAL: Leave empty string)

host = "https://ws-custom-categories.api.forcepoint.io"
api_version = "1.0.0"
headers = {"Authorization": f"Bearer {token}"}
url = f"{host}/v{api_version}/{category_id}"

get_category_by_id(url, headers, next_page_cursor)

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "no name",
  • "description": "string",
  • "sites": [
    ],
  • "policyName": "string"
}

Update an existing category

API path to update an existing custom category for the account. This API path will replace all the category information with the category details given in the request body.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

Request Body schema: application/json
required

Category details

name
required
string
description
string
sites
required
Array of strings <= 30000 items

List of website urls and IP addresses

comment
string

Comment field appears in "Get Transaction Status" response, not in Cloud Web portal

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "sites": [
    ],
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Add or Remove category sites

API path to add or remove sites from a custom category. This API path is only for adding or removing sites. To replace all the sites for a category the Update an existing category (PUT) API path must be used.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

query Parameters
action
required
string
Enum: "add" "remove"

Action identifying whether sites are being added or removed

Request Body schema: application/json
required

Site details

sites
required
Array of strings <= 30000 items

List of website urls and IP addresses

comment
string

Comment field appears in "Get Transaction Status" response, not in Cloud Web portal

Responses

Request samples

Content type
application/json
{
  • "sites": [
    ],
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Delete a category

API path to delete a custom category for the account.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

Responses

Request samples 

import requests

def delete_category(url:str, headers: object) -> object:
  """Method to delete a Custom Category."""
  response = requests.request("DELETE", url, headers=headers)
  print(response.text)
  return response

token = ""            # Insert bearer access token here
category_id = 0       # Insert category id here

host = "https://ws-custom-categories.api.forcepoint.io"
api_version = "1.0.0"
headers = {"Authorization": f"Bearer {token}"}
url = f"{host}/v{api_version}/{category_id}"

delete_category(url, headers)

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Get transaction status

API path to retrieve the transaction status for a transaction ID.

Authorizations:
custom-authorizer
path Parameters
transactionId
required
string

ID of transaction to return

Responses

Request samples 

import requests

def get_transaction_status(url: str, headers) -> object:
  """Get transaction status."""
  response = requests.request(
      "GET", url, data="", headers=headers,
  )
  print(response.text)
  return response

token = ""          # Insert bearer access token here
transaction_id = "" # Insert transactionId here

host = "https://ws-custom-categories.api.forcepoint.io"
api_version = "1.0.0"
url = f"{host}/v{api_version}/transaction/{transaction_id}"
headers = {"Authorization": f"Bearer {token}"}

get_transaction_status(url, headers)

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}