Configure API Protection policies using reserved tags

The API Protection reserved tags described in this article provide additional context about API endpoints and tagged requests during policy evaluation.

Three API Protection policies evaluate these tags: API-level authorization, Auth token protection, and Sensitive data exposure.

Reserved tag names and purposes are predefined and can’t be customized.

Reserved tags by policy

API-level authorization evaluates the following reserved tags for endpoint access requirements and requester roles:

Reserved tag	Description	Assign to
API Admin Access	Marks API paths as intended for Admin traffic	Confirmed API paths
API Privileged Access	Marks API paths as intended for Privileged or Admin traffic	Confirmed API paths
Indicate API Admin User	Marks matching requests as Admin traffic	Matching requests
Indicate API Privileged User	Marks matching requests as Privileged traffic	Matching requests

Auth token protection evaluates the following reserved tag for additional OAuth token paths:

Reserved tag	Description	Assign to
Auth Endpoint	Marks additional OAuth token paths as authentication endpoints	Confirmed API paths

Sensitive data exposure evaluates the following reserved exception tags for supported PII types:

Reserved tag	Description	Assign to
Ignore CCN Detection	Prevents the policy from blocking a response based on detected credit card numbers when the tag is present	Confirmed API paths
Ignore SSN Detection	Prevents the policy from blocking a response based on detected Social Security numbers when the tag is present	Confirmed API paths
Ignore Email Address Detection	Prevents the policy from blocking a response based on detected email addresses when the tag is present	Confirmed API paths
Ignore Phone Number Detection	Prevents the policy from blocking a response based on detected phone numbers when the tag is present	Confirmed API paths

Assign endpoint-related tags to confirmed API paths in the Gcore Customer Portal on the API Discovery page, or through the Gcore API.

Apply requester-role tags to matching requests with Custom or Advanced Rules on the Customer Portal Custom Rules page, or through the Gcore API Custom Rules or Advanced Rules endpoints.

API-level authorization in API Protection

API-level authorization adds a traffic-filtering layer for designated API endpoints based on requester-role signals. Access-level tags (API Admin Access, API Privileged Access) define what each endpoint requires, while requester-role tags (Indicate API Admin User, Indicate API Privileged User) mark matching requests. The policy blocks a request when the requester-role signal doesn’t meet the endpoint’s access requirement.

Use API-level authorization only as an additional traffic-filtering layer.

Do not use the policy as a replacement for authentication and authorization controls enforced by the protected application or API.

Access-level tags on API paths

Configure the API paths that API-level authorization evaluates on the Customer Portal API Discovery page.

For each relevant API path:

1. Add the path to the API Baseline if it isn’t already listed.

2. Mark the path as Confirmed.

3. Assign no more than one reserved tag according to the requester roles permitted to access the path:

   • For paths available only to Admin requesters, assign API Admin Access.

   • For paths available only to Privileged and Admin requesters, assign API Privileged Access.

   • For paths that shouldn’t be restricted by API-level authorization, don’t assign either tag.

For easier maintenance, organize paths that share an access requirement into a corresponding API group.

API groups are organizational only. They don’t define endpoint access requirements or replace reserved tags.

The policy evaluates only confirmed API paths.

Requester-role tags in Custom Rules

Apply Indicate API Admin User or Indicate API Privileged User to matching requests through Custom or Advanced Rules on the Customer Portal Custom Rules page. The use case below shows an additional traffic-filtering layer based on a client-provided role header and a shared office IP address.

Subscription-service traffic filtering example

An online subscription service provides a mobile application backed by an API protected by Gcore WAAP.

To follow this use case, configure three confirmed API paths as shown below. Replace the example paths with the corresponding paths from the protected API.

API path	Intended users	Reserved tag
/api/account	All users	None
/api/premium-reports	Paid users and Administrators	API Privileged Access
/api/admin/users	Administrators	API Admin Access

The mobile application adds an X-User-Role header to every request sent after sign-in:

• Standard users (non-paying)

  • Intended access: General API paths.
  • Request header: X-User-Role: standard.
  • Requester-role reserved tag: None.

• Paid users

  • Intended access: General and Privileged API paths.
  • Request header: X-User-Role: privileged.
  • Requester-role reserved tag: Indicate API Privileged User.

• Administrators

  • Intended access: General, Privileged, and Admin API paths.
  • Request header: X-User-Role: admin.
  • Requester-role reserved tag: Indicate API Admin User.
  • Network condition: Requests originate from the service’s shared static office IP address.

X-User-Role is client-provided and can be modified or forged. The office IP address identifies a network, not an individual administrator.

The following procedures create one Custom Rule for Paid users and another for Administrators.

Use these rules only as an additional traffic-filtering layer. The protected application or API must independently authenticate requesters and authorize every request.

Custom Rule for paid-user requests

This rule applies Indicate API Privileged User when the role header matches.

1. Open the Custom Rules page

   Log in to the Customer Portal, navigate to WAAP > Custom Rules, and click Add custom rule.

2. Name the rule

   In Rule name, enter Identify paid user requests. Leave Status enabled.

3. Set the domain condition

   Under Define rule, verify the intended domain in Domains / Zones.

4. Add the Header condition

   In the first And row:

   1. Select Header.
   2. Select Equals.
   3. Enter X-User-Role: privileged.
5. Apply the reserved tag

   Under Then:

   1. Select Tag.
   2. Select Indicate API Privileged User.

   Click Save.

   

Custom Rule for administrator requests

This rule applies Indicate API Admin User when both the role header and office IP address match.

1. Open a new custom rule

   Click Add custom rule.

2. Name the rule

   In Rule name, enter Identify administrator requests. Leave Status enabled.

3. Set the domain condition

   Under Define rule, verify the intended domain in Domains / Zones.

4. Add the Header condition

   In the first And row:

   1. Select Header.
   2. Select Equals.
   3. Enter X-User-Role: admin.
5. Add the IP condition

   In the next And row:

   1. Select IP.
   2. Verify Equals is selected.
   3. Enter 203.0.113.10.
6. Apply the reserved tag

   Under Then, select Tag, then select Indicate API Admin User.

   Click Save.

   

Requester-role matching tradeoffs

API-level authorization is an additional traffic-filtering layer. The conditions in requester-role rules determine how selective this layer is:

• More conditions: Fewer requests receive the requester-role tag. This reduces unintended tag assignment but can increase false blocks on restricted API paths.
• Fewer conditions: More requests receive the requester-role tag. This reduces false blocks but increases the risk of assigning the tag to unintended traffic.

Use an Advanced Rule to define multiple valid condition combinations. This supports different legitimate traffic patterns without making the filtering unnecessarily broad.

Rule conditions control traffic filtering; they don’t authenticate or authorize requesters.

Assigning endpoint-access and requester-role reserved tags configures the policy inputs but doesn’t activate enforcement. To activate enforcement, in the Customer Portal, navigate to WAAP > API Protection and set API-level authorization to Protection mode.

Auth token protection in API Protection

Unlike API-level authorization, which filters access by requester role, Auth token protection targets authentication and authorization abuse — including brute-force attacks, invalid authentication tokens, and authorization-bypass attempts.

WAAP automatically identifies OAuth token endpoints whose paths match common patterns. Matching paths include /oauth/token, /oauth2/token, and /oauth2/v1/token.

Auth Endpoint tag on API paths

The Auth Endpoint reserved tag marks additional OAuth token paths as authentication endpoints. Configure those paths on the Customer Portal API Discovery page.

For each additional authentication endpoint:

1. Add the OAuth token path to the API Baseline if it isn’t already listed.

2. Mark the path as Confirmed.

3. Assign the Auth Endpoint reserved tag.

Assigning the Auth Endpoint reserved tag identifies the endpoint but doesn’t activate enforcement. To activate enforcement, in the Customer Portal, navigate to WAAP > API Protection and set Auth token protection to Protection mode.

Sensitive data exposure in API Protection

Sensitive data exposure detects and blocks API responses that contain personally identifiable information (PII): credit card numbers, Social Security numbers (SSNs), email addresses, and phone numbers. Exception tags on confirmed API paths turn off blocking for specific PII types on those paths.

Exception tags on API paths

When a reserved exception tag is assigned to an API path, Sensitive data exposure doesn’t block responses from that path based on the corresponding detected PII type.

Each tag applies only to its corresponding PII type. Other detected PII types remain subject to enforcement.

PII type	Reserved exception tag
Credit card numbers	Ignore CCN Detection
Social Security numbers	Ignore SSN Detection
Email addresses	Ignore Email Address Detection
Phone numbers	Ignore Phone Number Detection

Assign exception tags only to API paths where returning the corresponding PII is expected and authorized. Limit each exception to the required paths and PII types.

Configure policy exceptions on the Customer Portal API Discovery page.

For each policy exception:

1. Add the API path to the API Baseline if it isn’t already listed.

2. Mark the path as Confirmed.

3. Assign the exception tag corresponding to the PII the endpoint is expected to return.

4. Assign additional exception tags to the same path only when it is expected to return multiple supported PII types.

When a response contains multiple supported PII types, assign the corresponding exception tag for every type that is expected and authorized. If any detected type doesn’t have a corresponding exception tag, the policy blocks the entire response.

For a response containing an email address and an SSN, assign both Ignore Email Address Detection and Ignore SSN Detection. If only the email exception is assigned, the policy blocks the entire response because the detected SSN has no corresponding exception.

Assigning an exception tag configures the exception but doesn’t activate enforcement. To activate enforcement, in the Customer Portal, navigate to WAAP > API Protection and set Sensitive data exposure to Protection mode.