TABLE OF CONTENTS

• Purpose
• Key Benefits
• Overview
• Problem Statement
• Impact
  • Functional Impact
  • Technical Impact
• Solution
• API Changes
• Configuration Changes
  • Webstore
  • API
• Existing APIs
• Important: Deployment Steps
• Validation Checklist
• Troubleshooting
  • Scenario 1: API Token Does Not Match Webstore
  • Scenario 2: Token Header Missing
  • Scenario 3: Incorrect Token
  • Scenario 4: Configuration Missing from Webstore

Purpose

To enhance the security of cache revalidation operations, authenticated cache revalidation has been introduced using a shared secret token.

Previously, cache revalidation endpoints could be invoked without authentication. While these endpoints were designed for internal communication between the API and Webstore, additional authentication ensures that only trusted applications can perform cache invalidation.

With this enhancement, all new cache revalidation requests are validated before execution, improving security while maintaining existing functionality.

Key Benefits

• Prevents unauthorized cache invalidation.
• Ensures secure communication between API and Webstore.
• Supports environment-specific security configuration.
• Provides a foundation for future security enhancements.

Overview

This enhancement introduces authentication for cache revalidation requests exchanged between the API and Webstore.

A shared secret is configured in both applications. During cache revalidation, the API sends the configured token, which is validated by the Webstore before the request is processed.

Only authenticated requests are allowed to perform cache revalidation. Requests with missing or invalid credentials are rejected with an HTTP 401 Unauthorized response.

This change requires only application configuration updates and does not impact existing data or business functionality.

Problem Statement

The existing cache revalidation APIs were intended solely for internal communication but did not include an authentication mechanism.

Without request validation, there was a potential risk of unauthorized cache invalidation if these endpoints became accessible outside the intended environment.

This enhancement mitigates that risk by ensuring that cache revalidation requests are accepted only from trusted applications using a shared authentication token.

Impact

Functional Impact

• Introduces authenticated cache revalidation endpoints.
• Ensures cache revalidation is performed only after successful authentication.
• Returns HTTP 401 Unauthorized for unauthorized requests.
• Existing cache functionality remains unchanged.
• Existing unauthenticated endpoints continue to be supported temporarily for backward compatibility and are planned for deprecation in a future release.

Technical Impact

• Requires a shared authentication token to be configured in both the API and Webstore applications.
• Introduces new authenticated cache revalidation endpoints.
• No database schema or data changes.
• Requires configuration updates as part of deployment.
• Minimal impact on existing integrations when the required configuration is completed.

Solution

A shared secret authentication mechanism has been implemented to secure cache revalidation requests.

The API includes the configured authentication token when invoking the cache revalidation endpoint. The Webstore validates the token before processing the request. Cache revalidation is executed only after successful authentication.

This approach provides a simple, secure, and environment-specific authentication mechanism without changing existing cache behavior.

API Changes

Configuration Changes

Webstore

Configure the following environment variable:

Example:

ZNODE_REVALIDATE_TOKEN=<instance_random_secret_key>

API

Configure the following setting:

Example:

WebstoreWebhookSecret=<instance_random_secret_key>

Existing APIs

To support backward compatibility, the existing cache revalidation APIs will continue to function in this release:

• /api/revalidate
• /api/revalidate-all

These endpoints remain fully supported for existing integrations, ensuring no immediate changes are required after upgrading.

These endpoints are deprecated and will be removed in a future release.

All new integrations should use authenticated endpoints.

Important: Deployment Steps

1. Generate or obtain the shared secret for the target environment.
2. Configure the shared secret in the Webstore application.
3. Configure the same shared secret in the API application.
4. Verify that both configuration values are identical.
5. Deploy the updated applications.
6. Restart services if required by your deployment process.
7. Validate authenticated cache revalidation.
8. Confirm that unauthorized requests are rejected with HTTP 401 Unauthorized.

Validation Checklist

Troubleshooting

Scenario 1: API Token Does Not Match Webstore

Result: HTTP 401 Unauthorized

Scenario 2: Token Header Missing

Result: HTTP 401 Unauthorized

Scenario 3: Incorrect Token

Result: HTTP 401 Unauthorized

Scenario 4: Configuration Missing from Webstore

Result: Authentication fails and cache revalidation is rejected.