1. Home
  2. Tyk Open Source API Gateway v2.x
  3. Key Changes in Tyk v2.X

Key Changes in Tyk v2.X


Version 2.2 Brings some more features, the most obvious is websocket support, but there’s been many changes and many bug fixes that have made he overall platform more stable, performant and overall useful.

The v2.2 Changelog:

  • Fixed URL Rewriter to better handle query strings
  • Added XML transform support for requests and responses, simply set the data type to xml int he transforms section and create your template the same way you would for JSON.
  • Added request method transform: This is very simple at the moment, and only changes the type of method, it does not data massaging, to enable, add to your extended paths:
  • Out of the box, tyk will ship with HA settings enabled where possible (this means using the new non-transactional rate limiter)
  • Added a new concept called “Partitioned Policies”, with policies that are partitioned, only sections of the policy will be applied to the underlying token so that tokens can be generated with a dynamic ACL, but still subscribe to a fixed quota and rate limit level.
  • Added context variable support, this middleware will extract the path, the path parts (break on /), and try to pull all form-related data (url-form-encoded or query string params) and put them into a context variable that is available to other middleware. Currently this is only integrated with the body transform middleware as _tyk_context. To enable set "enable_context_vars": true in the API Definition. Transform sample:
  • Context variables also available in headers using $tyk_context. namespace
  • WARNING: POTENTIALLY BREAKING CHANGE: Flush interval is now in milliseconds, not seconds, before upgrading, if you are using flush interval, make sure that the value has been updated.
  • Context variables also available in URL rewriter
  • Added Websockets support (beta), websockets can now be proxied like a regular HTP request, tyk will detect the upgrade and initiate a proxy to the upstream websocket host. This can be TLS enabled and Tyk can proxy over HTTPS -> WSS upstream.
  • Websockets execute at the end of the middleware chain, so all the benefits of CB and auth middleware can be enabled (within the limits of the WebSockets protocol)

Tyk Dashboard Changes:

The dashboard has two major upgrades:

  • i18n Support: We now have language packs available to add new languages to your dashboard
  • Improved analytics speed: The new version of Dashboard and Tyk Pump makes available aggregated analytics, these are much faster than standard analytics provided by Tyk and can be deployed without making ny changes to your DB, please see the aggregate analytics support section of Tyk Pump.


Version 2.0 of Tyk we have focussed on new features, increased durability and a focus on removing even more dependencies.

Key changes to be aware of:

  1. Tyk API gateway v2.X no longer loads API Definitions from MongoDB, as part of our mission to remove dependencies this has now moved to be a service-based loader from the Dashboard
  2. Tyk API Gateway now no longer requires MongoDB for analytics, in fact, Tyk API gateway no longer handles purging analytics data at all, this is instead handled by a new service called Tyk Pump.
  3. Tyk Pump supports CSV, MongoDB and ElasticSearch, it has a simple interface-based API and can be extended to support more data sinks, Tyk Pump can write to multiple data sinks at once.

The Change Log for v2.1 of Tyk API Gateway

  • Fixed bug in contralised JWT secrets where OrgID was not set on internal token
  • Added support for key aliases, when adding a token, you can now add an alias to the token, this will appear in analytics when viewing on a per-key basis, can be helpful for degugging problem users when using a hashed key set.
  • OAuth Clients are now fully editable (you can set the clientID and secret at creation time)
  • OAuth client now support adding a matched Policy ID, if key_rules are not included when the tokens are authorized, the policy ID will be used as the baseline of the stored token – this is useful in cases where a third-party IDP provide clients and they must be matched to specific policies. THis also means you no longer nee to add key_rules to your oauth authorize callbacks, making the process more streamlined and standards-based.

JWT Matched Clients:

  • JWT Now supports a matched client: It is now possible to have a JWT contain a client ID (azp claim) and a base identity field (e.g. sub), Tyk will use the policy applied to the client on the base identity of the token, enabling matched clients in JWTs.
An example flow:
  • Developer registers a client app with your IDP
  • You create a custom API token in Tyk that matches the client ID (This custom token Must use a policy)
  • This custom token now represents this client application within Tyk – it is not the same as a registered OAuth client, this token only acts as a proxy key
  • Set up your API with the jwt_client_base_field (the claim in the JWT that representsthe client ID – typically azp) and jwt_identity_base_field (the claim that represents the users identity – e.g. sub), do not use the jwt_policy_field_name, as this will alter the flow of the validation
  • Generate a JWT that has these claims filled in, make sure the client ID in the azp field is the same as the one you have added to Tyk in step 1
  • Create a request to Tyk
What happens:
  • Tyk will validate the JWT
  • Tyk will extract the client ID fro the token, and fetch the token that you created, it will then check the policy
  • Tyk will then fetch the underlying users identity and generate a hash to represent them locally
  • Tyk will generate an internal token based on the identity and the policy from the Client ID going forward

OpenID Connect Support

  • Added OpenID Connect Token validation (OIDC ID Tokens) – this is similar to the JWT support but specific to OpenID Connect standard.

  • OpenID Connect tokens can be rate-limited per client (so the same user comming via different clients can have different rate limits): in the open ID options, set "segregate_by_client": true

Enabling OpenID Connect

Set up your API Definition

use_openid: true,
openid_options: {
providers: [
issuer: "accounts.google.com",
client_ids: {
NDA3NDA4NzE4MTkyLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29t: "571f84c430c55e4d45000002"



An array of supported providers


The name of the issuing entity, e.g. google acocunts


A map of base64(clientID):PolicyID

This map will assign a policy already stored in Tyk to a client ID, this will cause Tyk to apply this policy to the underlying ientity of the uer (i.e. generate an internal token that represents the User that holds the token).

Why Base64? We require base64 encoded client IDs to ensure cross-compatability with document stores

What happens:
  • Tyk will validate the JWT according to the OpenID Spec:

    1. Is the token a valid jwt?
    2. Is the token issued by a known OP?
    3. Is the token issued for a known client?
    4. Is the token valid at the time (‘not use before’ and ‘expire at’ claims)?
    5. Is the token signed accordingly?
  • Tyk will then check the API definition for a supported Client/Policy under the issuing IDP

  • This policy will then be used as a template for a new internal token that represents this user (so we can apply the policy across logins)

  • The internal token is generated off of the OpenID connect User ID claim

  • The request is then passed through to the rest of the Tyk validation chain

  • Tyk Dashboard will now respect internal policy IDs (id instead of _id) for a policy object allowing for fixed-policy IDs across installations.

    • To enable, add allow_explicit_policy_id: true to your configuration file under the policies section
    • To enable compatibility in the dashboard, add allow_explicit_policy_id: true to the root of your dashboard conf
  • Fixed policy bug where a policy would not corectly overwrite a token’s access rights with the correct metadata, causing it to not be editable later.
  • Black / White / Ignore / Transform and Injec lists are now matched on a lowercase version of the inbound path, so match patterns must be lowercase otherwise they will be ignored.
  • New Response middleware to force target_url replacements in return headers such as “Link”, and “Location” which tend to be set upstream by the service with incorrect values (real values)

    “response_processors”: [ { “name”: “header_transform”, “options”: { “rev_proxy_header_cleanup”: { “headers”: [“Link”, “Location”], “target_host”: “http://TykHost:TykPort” } } } ]

The Change Log for v2.0 of Tyk API Gateway

  • Limited multi-target support on a per-version basis: simply add "override_target": "http://domain.com" to the version section in your API Definition. Round Robin LB and Service Discovery are not supported.
  • Centralised JWT keys are now supported, adding jwt_source to an API definition will enable a central cert to validate all incoming tokens.
  • jwt_source can either be a base64 encoded valid RSA/HMAC key OR a JWK URL, if it is a JWK URL then the kid must match the one in the JWK
  • Centralised JWT keys need a jwt_identity_base_field that basically identifies the user in the Claims of the JWT, this will fallback to sub if not found. This field forms the basis of a new “virtual” token that gets used after validation, it means policy attributes are carried forward through Tyk for attribution purposes.
  • Centralised JWT keys also need a jwt_policy_field_name which sets the policy to apply to the “virtual” key
  • JWT header can now support “Bearer xxxx” style auth headers
  • HMAC authentication now supports an alternate header (x-aux-date) for clients that do not provide a date header, this header is checked first before reverting to the Date field
  • Added capability to preserve host header, if proxy.preserve_host_header is set to true in an API definition then the host header in the outbound request is retained to be the inbound hostname of the proxy.
  • Added more default tags for better segmentation: key-{key-id}, org-{org-id} and api-{apiid} can now be used as tags to lock down the analytics filter in the dashboard.
  • HMAC support re-written and updated to the latest spec
  • HMAC: request-target now supported
  • HMAC: headers signature field is now supported (this means Digest can be included)
  • Purger has been removed from core completely (replaced by Pump)
  • More tracing and more logging has been put in place, especially around API operations for easy tracing
  • Hot reloads (redis based), will not reset the muxer if no specs are returned (mproves stability if a data source goes down or fails)
  • REMOVED: MongoDB poller
  • REMOVED: MongoDB Policy poller
  • ADDED: Service-based API Definition loader (dashboard)
  • ADDED: Service-based Policy loader (dashboard)
  • To configure for API Defs:

    "use_db_app_configs": true,
    "db_app_conf_options": {
        "connection_string": "http://dashboard_host:port",
        "node_is_segmented": false,
        "tags": []
  • To configure for Policies:

    "policies": {
        "policy_source": "service",
        "policy_connection_string": "http://dashboard_host:port"
  • Tyk nodes now register with a dashboard to be assigned an ID based on the licenses available.

  • X-Forwarded For now used to log IP addresses in event log

  • Analytics now records IP Address (OR X-F-F)

  • Analytics now records GeoIP data, to enable add (DB is MaxMind):

    "enable_geo_ip": true,
    "geo_ip_db_path": "./GeoLite2-City.mmdb"
  • Analytics GeoIP DB can be replaced on disk, it will cleanly auto-reload every hour

  • Detail logging can now be activated on an organisation basis, setting enforce_org_data_detail_logging in the tyk.conf will enforce it (quotas must also be enforced for this to work), then setting enable_detail_recording in the org session object will enable or disable the logging method

  • Centralised JWTs add a TykJWTSessionID to the session meta data on create to enable upstream hosts to work with the internalised token should things need changing

  • New System Events handler, works with existing event handlers, configure add to tyk.conf:

    "event_handlers": {
        "events": {
            "TokenCreated": [{
                "handler_name": "eh_log_handler",
                "handler_meta": {
                    "prefix": "[TEST API EVENT]"
            "TokenUpdated": [{
                "handler_name": "eh_log_handler",
                "handler_meta": {
                    "prefix": "[TEST API EVENT]"
  • Nw Multi-DC / segregated environment / single dashboard support added for API and Keyspace propagation

  • Added new rate limit handler that is non-transactional, this can be enabled by setting enable_non_transactional_rate_limiter to true, this can provide exceptional performance improvements

  • Added option to enable or disable the sentinel-based rate-limiter, sentinel-based rate limiter provides a smoother performance curve as rate-limit calculations happen off-thread, but a stricter time-out based cooldown for clients. Disabling the sentinel based limiter will make rate-limit calculations happen on-thread and therefore offers staggered cool-down and a smoother rate-limit experience for the client and similar performance as the sentinel-based limiter. TThis is disabled by default. To enable, set enable_sentinel_rate_limiter to true