Cloudflare KV icon

Cloudflare KV

Store and retrieve data from Cloudflare Workers KV.
Join our community

Actions9

Overview

This node integrates with Cloudflare Workers KV, a globally distributed key-value storage system. It allows users to set key-value pairs within a specified namespace, optionally including expiration times and metadata. This is useful for scenarios such as caching data, storing configuration settings, or managing session information in a scalable way.

For example, you can use this node to store user preferences under a specific key, with an optional expiration time so that the data automatically expires after a certain period. Another practical use case is saving temporary tokens or flags that should be removed after some time.

Properties

Name Meaning
Namespace ID The identifier of the KV namespace where the key-value pair will be stored.
Key The key under which the value will be saved.
Value The string value to store associated with the key.
Expiration Absolute expiration time as a UNIX timestamp (seconds since epoch). Must be greater than current time. Mutually exclusive with Expiration TTL. Optional.
Expiration TTL Time to live in seconds from now (relative expiration time). Mutually exclusive with Expiration. Optional.
Metadata Arbitrary JSON object containing metadata to store alongside the key-value pair.

Output

The output JSON contains confirmation of the operation with the following structure:

{
  "success": true,
  "key": "the-key-set",
  "value": "the-value-stored",
  "expiration": 1735689600,        // optional, if set
  "expirationTtl": 60,             // optional, if set
  "metadata": {                    // optional, if provided
    "any": "json"
  }
}

This confirms that the key-value pair was successfully stored, along with any expiration or metadata details.

Dependencies

  • Requires a valid API authentication token for Cloudflare's API.
  • Needs the account ID associated with the Cloudflare account.
  • The node uses HTTP requests to interact with Cloudflare's KV REST API endpoints.
  • Properly configured credentials must be set up in n8n to authenticate these requests.

Troubleshooting

  • Common issues:

    • Using both Expiration and Expiration TTL simultaneously will cause errors; only one should be set.
    • Providing an expiration timestamp that is not greater than the current time will result in failure.
    • Incorrect or missing namespace ID will cause the request to fail.
    • Invalid API token or insufficient permissions will lead to authorization errors.

  • Error messages:

    • "Key not found": Occurs when trying to get or delete a key that does not exist.
    • HTTP 401 or 403 errors: Indicate authentication or permission problems; verify API token and account permissions.
    • Validation errors related to expiration fields: Ensure expiration timestamps are valid and mutually exclusive.

To resolve errors, double-check input parameters, ensure correct namespace IDs, and verify API credentials.

Links and References

Discussion