Custom Entities for Bot Protection

A Custom Entity in Bot Protection allows you to define your own field extraction logic. While Traceable provides standard fields, such as user agent, device, and OS, you define a custom entity whenever you need to aggregate on a field not included in the standard set. It allows you to unify data across different APIs or request formats, ensuring consistent visibility for security and analytics. It works similarly to User Attribution by extracting and standardizing values from API traffic for use across policies and analytics. These custom entities are used directly within Bot and Abuse Protection policies to define how traffic is classified, evaluated, and acted upon, using both standard and custom-extracted attributes. For more information, see Bot and Abuse Protection Policies.

What will you learn in this topic?

By the end of this topic, you will be able to:

• Understand the role of entities in Traceable.

• Identify when to use custom entities beyond standard attributes.

• Define entities to extract application-specific data from requests.

Before you begin

Before you proceed to create a custom Entity, make a note of the following:

• Make sure you have the Settings RBAC permissions under Module Level Access → API Protection to create the rules. For more information, see Team and roles - RBAC.

Understand entities

Custom entities help you standardize and extract application-specific data that is not available through default attributes. This improves how Traceable aggregates and applies policies across APIs, especially when the same data appears in different formats, locations, or request structures. The following table explains when to use custom entities, why they are needed, and how you can leverage them effectively:

Create a custom entity

To create a custom entity, navigate to Settings → Entities → Custom. Under the Custom tab, click +Create Entity.

In the Create Entity slide-out panel, complete the following steps:

1. Rule name — A name that describes what this rule detects, for example, user_defined_entity.

2. Entity kind — The data type of the value you are extracting. The type you select determines which transformation functions Traceable can apply to it, for example, String, Integer, or Email Address.

3. Identifier — A reference label for this entity, for example, payment.

4. Environments — The environment or environments where Traceable applies this entity, for example, All Environments.

5. Target — The scope of API traffic from which Traceable uses this entity. The following table describes the available targets:

   Target	Description
   All Endpoints	Apply the rule to all endpoints within the selected environments.
   API Endpoints	Apply the rule to specific API endpoints. This allows granular control at the endpoint level.
   Services	Apply the rule to one or more specific services. You can search or filter services based on your requirements.

6. Request Filter (Optional) — The filtering request attributes to help you extract your required data. Click + Add Condition to add a filter. The following table shows the available fields:

   Component	Description (with examples)
   Attribute Scope	Defines the data source within the HTTP transaction. Example — Request Header, such as Authorization.
   Key	Specifies the exact field inside the selected scope to evaluate. Example — user identifier, content type.
   Operator	Defines how comparison is performed. Example — Equals, Not Equals, Greater Than
   Value	The value used for evaluation against the key. Example — success, administrator, application JSON type.

7. Location — Defines where Traceable should look within API traffic to extract the entity value and how it should identify the field using match rules, such as Regex, Prefix, or Contains. The following table describes the fields used to configure the extraction location and matching logic for a custom entity:

   Field	Description	Available Options
   Source	The attribute location where Traceable extracts the value from the API traffic.	Request Header — Matches values from HTTP request headers sent by the client. Response Header — Matches values from HTTP response headers sent by the client. Request Body — Matches values from the API request payload. Response Body — Matches values from the API response payload. Request Cookie — Matches values stored in cookies sent with the request. Response Cookie — Matches values stored in cookies sent with the response.
   Match operator	Defines how Traceable matches the specified key.	Matches Exactly — The key must match character-for-character. Use this for stable, well-known field names. Matches Regex — The key matches a regular expression pattern. Use this when field names are dynamic or follow a naming convention. Prefix — The key must start with the specified value. Contains — The key must contain the specified value anywhere within it.
   Key	The field name or path Traceable extracts from the selected source.	The field name to extract, for example, email ID. For deeply nested structures, use JSON path notation to access embedded fields without requiring an additional transformation step, for example, Email ID, sample@email.com.

8. Transformations (Optional) — Applies a sequence of processing steps to the extracted value to refine and decode it into the required format for consistent use across policies and analytics. It allows you to extract specific portions of raw data through a sequence of processing steps, ensuring the final value is in the format required for your use case. To add a transformation, click + Add Transformation. By default, Traceable transforms the entity into its corresponding entity kind type. For more information, see Transformation function support matrix.

9. After verifying all the fields, click Save.

Transformation function support matrix

The following table lists the entity kind and supported transformation functions in detail:

Actions

You can perform the following actions on the created custom entities by clicking the ellipse icon ():

• Active — Enable or disable the entity using the toggle in the Active column, according to your requirements.

• Edit — Edit an existing entity.

• Create Attribute — Create a child attribute from an existing entity to extract more granular or actionable values using transformation functions. This helps you derive additional context from already extracted data without creating a new entity from scratch. You can use child attributes to refine values, apply further transformations, create filters and detections, or build additional derived entities on top of existing attributes, using the following attributes:

  • Attribute Name — A name for your attribute, for example, custom_attribute_1.

  • Entity Kind — The type of entity that you wish to configure for this attribute. The functions available for transformations depend on the entity kind you select, for example, String.

  • Transformations — A sequence of steps to modify your span attribute to extract actionable data, according to your requirements.

    

• Delete — Delete the custom entity.

  Note

  A deleted entity cannot be restored.

After creating custom entities, you can use them in Bot Protection policies to build more granular aggregation logic, improve detection accuracy, and enforce application-specific protections. For more information, see Bot and Abuse Protection Policies.