Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tyk.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

When a client authenticates, Tyk uses a specific identifier (the “Key”) to look up their Session in the Redis database. Depending on your authentication method, this Key might be an Auth Token, a Basic Auth username, an HMAC Key ID, or a JWT identity claim. To enhance security and protect these identifiers in the event that your Redis database is compromised, Tyk supports Key Hashing. When hashing is in use, Tyk never stores the plaintext Key in Redis. Instead, it runs the Key through a one-way hashing function and stores the resulting hash as the lookup key in Redis. When a client makes a request, Tyk extracts their identifier, hashes it on the fly, and compares it to the hash stored in Redis. The algorithm used to perform the hashing is configurable, with both cryptographic and non-cryptographic options.
Key Hashing applies universally at the storage layer. If enabled, the lookup identifier for every authentication method is hashed.

​
Enabling Key Hashing

Hashing is enabled in the Gateway and Dashboard configuration using the common setting hash_keys (or the equivalent environment variables).
This must be enabled in both the Gateway and Dashboard (if used).
Switching between hashed and non-hashed configuration means that any existing keys can no longer be used, as the Gateway and Dashboard will not be able to correctly validate them. Every existing API client will lose access immediately.

​
Hashing Algorithms

Tyk offers several hashing algorithms, allowing you to choose the right balance between performance and security for your environment. You can configure the algorithm using the hash_key_function setting in your tyk.conf (or the equivalent environment variable). The available options are:
  • murmur32 (Default): A fast, non-cryptographic hash function. It provides excellent performance and basic obfuscation, but is not cryptographically secure.
  • murmur64 and murmur128: Longer variants of the Murmur hash, providing a larger hash space to prevent collisions while maintaining high performance. These are also not cryptographically secure.
  • sha256: A cryptographically secure hashing algorithm. This provides the highest level of security but is computationally more expensive and will slightly reduce Gateway performance.
For identifiers that are not standard Tyk tokens, such as Basic Auth usernames, Tyk will always use murmur32 for the lookup hash, regardless of this setting.

​
Implications of Key Hashing

Enabling key hashing fundamentally changes how you interact with keys via the Tyk APIs and Dashboard. Because hashing is a one-way operation, Tyk cannot reverse the hash to reveal the original key. If you enable key hashing, you must design your workflows around the following constraints:

​
1. Plaintext Keys are Returned Only Once

When you create a new key via the Gateway API or the Dashboard, Tyk will return the plaintext key in the response payload exactly once. It is your responsibility to securely transmit this key to the client and store it if necessary. If the client loses the key, it cannot be recovered from Tyk; a new key must be generated.

​
2. Listing Keys Returns Hashes

By default, if key hashing is in use, then requests to the Gateway API or Dashboard API to retrieve a list of keys will be rejected - this functionality is disabled for security reasons. You must explicitly enable these endpoints by setting enable_hashed_keys_listing: true in the Gateway and Dashboard configurations respectively.

​
3. Analytics Using Hashed Keys

All analytics records, logs, and quota tracking will use the hashed version of the key. If you need to correlate analytics data with a specific client, you should use the Session’s alias or meta_data fields, rather than relying on the key itself.

​
4. Managing Keys by Hash

If you need to retrieve, update, or delete the Session relating to a specific key, you can always do so using the plaintext key (Tyk will hash it on the fly). If you want to be able to use the key’s hashed value instead, then you must set the appropriate configuration as follows:
  • Gateway API:
    • Append the ?hashed=true query parameter to your API calls when passing a hash instead of a plaintext key.
  • Dashboard:

​
Migrating Hashing Algorithms

If you decide to change your hash_key_function (for example, upgrading from murmur32 to sha256 for better security), Tyk provides a seamless migration path. It is of course not possible to convert a one-way hashed key to another hashing algorithm, but you do not need to invalidate all your existing keys. Instead, you can use the hash_key_function_fallback array in your Gateway configuration. When a request arrives, Tyk will first attempt to hash the incoming key using your current hashing algorithm (declared in hash_key_function). If the resulting hash is not found in Redis, Tyk will then try hashing the key using the algorithms listed in your fallback array. For example, given this configuration in tyk.conf: 
"hash_key_function": "sha256",
"hash_key_function_fallback": ["murmur32"]
In this scenario, all new keys will be hashed using sha256, but existing keys hashed with murmur32 will continue to work perfectly. This gives you the opportunity to gradually retire the older keys as they expire.

​
Configuration Summary

To ensure key hashing works correctly, your Gateway and Dashboard configurations must be kept in sync. Gateway (tyk.conf or equivalent environment variable)
  • hash_keys: Set to true to enable hashing.
  • hash_key_function: The algorithm for standard keys (e.g., murmur64, sha256).
  • hash_key_function_fallback: An array of legacy algorithms to support existing keys during a migration.
  • enable_hashed_keys_listing: Set to true to allow the GET /tyk/keys endpoint to return hashes.
Dashboard (tyk_analytics.conf or equivalent environment variables)
  • hash_keys: Must match the Gateway setting (true).
  • enable_hashed_keys_listing: Must match the Gateway setting (true).
  • enable_update_key_by_hash: Set to true to allow sessions to be updated using the key hash as reference.
  • enable_delete_key_by_hash: Set to true to allow sessions to be deleted using the key hash as reference.
The Dashboard calls the Gateway API to obtain the list of keys, so it is important to set enable_hashed_keys_listing: true in both components.