Key Expiry and Deletion
Tyk makes a clear distinction between an API authorisation key expiring and being deleted from the Redis storage.
- When a key expires, it remains in the Redis storage but is no longer valid. Consequently, it is no longer authorised to access any APIs. If a key in Redis has expired and is passed in an API request, Tyk will return
HTTP 401 Key has expired, please renew.
- When a key is deleted from Redis, Tyk no longer knows about it, so if it is passed in an API request, Tyk will return
HTTP 400 Access to this API has been disallowed.
Tyk provides separate control for the expiration and deletion of keys.
Note that where we talk about keys here, we are referring to Session Objects, also sometimes referred to as Session Tokens
Tyk’s API keys (token session objects) have an
expires field. This is a UNIX timestamp and, when this date/time is reached, the key will automatically expire; any subsequent API request made using the key will be rejected.
Tyk does not automatically delete keys when they expire. You may prefer to leave expired keys in Redis storage, so that they can be renewed (for example if a user has - inadvisedly - hard coded the key into their application). Alternatively, you may wish to delete keys to avoid cluttering up Redis storage with obsolete keys.
You have two options for configuring the lifetime of keys when using Tyk:
- At the API level
- At the Gateway level
API-level key lifetime control
You can configure Tyk to delete keys after a configurable period (lifetime) after they have been created. Simply set the
session_lifetime field in your API Definition and keys created for that API will automatically be deleted when that period (in seconds) has passed.
The default value for
session_lifetime is 0, this is interpreted as an infinite lifetime which means that keys will not be deleted from Redis.
For example, to have keys live in Redis for only 24 hours (and be deleted 24 hours after their creation) set:
There is a risk, when configuring API-level lifetime, that a key will be deleted before it has expired, as
session_lifetime is applied regardless of whether the key is active or expired. To protect against this, you can configure the session_lifetime_respects_key_expiration parameter in your
tyk.conf, so that keys that have exceeded their lifetime will not be deleted from Redis until they have expired.
This feature works nicely with JWT or OIDC authentication methods, as the keys are created in Redis the first time they are in use so you know when they will be removed. Be extra careful in the case of keys created by Tyk (Auth token or JWT with individual secrets) and set a long
session_lifetime, otherwise the user might try to use the key after it has already been removed from Redis.
Gateway-level key lifetime control
You can set a global lifetime for all keys created in the Redis by setting global_session_lifetime in the
tyk.conf file; this parameter is an integer value in seconds.
To enable this global lifetime, you must also set the force_global_session_lifetime parameter in the
Summary of key lifetime precedence
The table below shows the key lifetime assigned for the different permutations of
session_lifetime_respects_key_expiration configuration parameters.
It is important to remember that a value of
global_session_lifetime is interpreted as infinity (i.e. key will not be deleted if that control is in use) - and if a field is not set, this is treated as
If you want the key to be deleted when it expires (i.e. to use the expiry configured in
expires within the key to control deletion) then you must set a non-zero value in
session_lifetime and configure both