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

Key expiry

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.

Key lifetime

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:

1. At the API level
2. 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:

"session_lifetime": 86400

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 tyk.conf file.

Summary of key lifetime precedence

The table below shows the key lifetime assigned for the different permutations of force_global_session_lifetime and session_lifetime_respects_key_expiration configuration parameters.