HomeTyk Open Source API Gateway v2.xConfigurationGateway configuration options

Gateway configuration options

The Tyk gateway server is configured primarily via the Tyk.conf file, this file resides in /etc/Tyk on most systems, but can also live anywhere and be directly targeted with the --conf flag.

The configuration is split up into various sections, which will be detailed here.


Setting this value will change the port that Tyk listens on, by default Tyk will try to listen on port 5000.


This should be changed as soon as Tyk is installed on the system. this value is used in every interaction with the Tyk REST API, it should be passed along as the X-Tyk-Authorizationheader in any requests made. Tyk assumes that you are sensible enough not to expose the management endpoints to the public and to keep this configuration value to yourself.


The shared secret between the gateway and the dashboard to ensure that API Definition downloads, heartbeat and Policy loads are from a valid source.


This is the path to the Tyk templates, as of the current version there is only one template error.json which determines the output of any errors that are returned by Tyk to any clients attempting to connect (with the exception of the OAuth flow, which has hard-coded templates)


If you are a Tyk Pro user, this option will enable polling the Dashboard service for API definitions. On startup Tyk will attempt to connect and download any relevant application configurations from from a dashboard instance. The documents are exactly the same as the JSON configuration on disk with the exception of a BSON ID supplied by the service.


This section defines API loading and shard options, enable these settings to only selectively load API definitions on a node from a dashboard service.


Set the URL to your dashboard instance (or a load balanced instance), the URL should take the form of: http://dashboard_host:port

Note the same will need to be done for Policy loading, see the policies section below.


Set to true to enable filtering of APIs


The tags to use when filtering the nodes, tags are processed as OR operations. If you include a non-filter tage (e.g. an identifier such as node-id-1, this will become available to your analytics dashboard)


If Tyk is being used in it’s standard configuration, then API definitions are stored in the apps folder (by default in /etc/Tyk/apps). this file is scanned for files that ending in .json extension and interpreted at startup or reload.


This section of the configuration is to hold the Redis configuration.


This should be set to ‘redis’ (lowercase), the previous backup and testing option of csv is deprecated.


The redis host, by default this is set to localhost, but for production this should be set to a cluster


The redis instance port


Not used, may be used in future for other back-ends


if your redis instance has a password set for access, you can tell Tyk about it here


Set the number of maximum idle connections in the Redis connection pool, defaults to 100, set to higher if expecting more traffic.


Tyk is capable of recording every hit to your API into a database with various filtering parameters, set this value to true an fill in the sub-section below to enable logging.

Note that Tyk will store traffic data to Redis initially (for performance reasons) and then purge the data from redis into MongoDB/CSV on a regular basis as determined by the purge_delay. This should prevent your Redis instance from getting too bloated.


This section defines options on what analytics data to store


Set this value to true to have Tyk store the inbound request and outbound response data in HTTP Wire format as part of the Analytics data. Please note, this will greatly increase your analytics DB size and can cause performance degredation on analytics processing by the dashboard. This setting can be overriden with an organisation flag:

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 on a per-organisation basis. This can be useful for debugging live APIs.


As of Tyk API Gateway 2.0, Tyk can store GeoIP information based on MaxMind DB’s, to enable GeoIP tracking on inbound request analytics, set this value to true and assign a DB using the geo_ip_db_path setting.


Set this value to the absolute path the GeoIP Database file, e.g.: ./GeoLite2-City.mmdb The analytics GeoIP DB can be replaced on disk, it will cleanly auto-reload every hour.


Adding IP addresses to this list will cause Tyk to ignore these IP’s in the analytics data, these IP addresses will not produce an analytics log record. This is useful for health checks and other samplers that might skew usage data.


This section describes methods that enable you to normalise inbound URLs in your analytics so as to have more meaningful per-path data


Set this to true to enable normalisation


Set this to true to have tyk automatically clean up UUIDs, it will match the following styles:

  • /15873a748894492162c402d67e92283b/search
  • /CA761232-ED42-11CE-BACD-00AA0057B223/search
  • /ca761232-ed42-11ce-BAcd-00aa0057b223/search
  • /ca761232-ed42-11ce-BAcd-00aa0057b223/search

Each UUID will be replaced with a placeholder {uuid}


St this to true to have Tyk automatically match for numeric ID’s, it will match with a preceeding slash so as not to capture actual numbers:

  • /widgets/123456/getParams will become /widgets/{id}/getParams


This is a list of custom patterns you can add, these must be valid regex strings, Tyk will replace these values with a {var} placeholder


This section enables the configuration of the health-check API endpoint and the size of the sample data cache (in seconds).


Setting this value to true will enable the health-check endpoint on /Tyk/health.


This setting defaults to 60, this is the time window that Tyk will use to sample health-check data. Increase this value for more accurate data (larger sample period), and decrease for less accurate. The reason this value is configurable is because sample data takes up space in your Redis DB to store the data to calculate samples, on high-availability systems this may not be desirable and smaller values may be preferred.


set this value to true to have Tyk manage session data using a goroutine, this is quite safe an can significantly boost performance in HA environments where Tyk is installed on a machine with multiple cores.


If this value is set to true, session objects (key definitions) that do not have explicit access rights set will be allowed by Tyk. This means that keys that are created have access to ALL APIs, which in many cases is unwanted behaviour unless you are sure about what you are doing.


The policies section allows you to define where Tyk can find it’s policy templates. Policy templates are similar to key definitions in that they allow you to set quotas, access rights and rate limits for keys.

Policies are loaded when Tyk starts and if changed require a hot-reload so they are loaded into memory.

A policy can be defined in a file (stand alone mode) or from the same database as the dashboard.


Set this value to file to look on the file system for a definition file, set to service to use the dashboard service. Note the option for mongo has now been removed.


Set this to the URL of your dashboard installation, the URl should take the form of: http://dashboard_host:port


Set this value to true to enable key hashing, this will start hashing all keys that are generated by Tyk in Redis. enabling this means that keys that are created are only exposed once, during creation. If the key is lost or misplaced after this it will not be retrievable (however it’s hash can still be deleted, if known).

If this is set to True, the same value should be enabled in the dashboard configuration so that the UI can react appropriately.


Tyk v1.6 will auto-reload when a change is detected when using the dashboard, this used to be done by the host-manager but is now directly integrated into the gateway. For backwards compatibility, this behaviour can be suppressed by setting this value to true.


Set this to true to enable the sentry logger, you must specify a sentry DSN under sentry_code


The Sentry-assigned DSN (a kind of URL endpoint) that Tyk can send log data to


Set to true to have Tyk enforce data age on analytics data sent to the Mongo DB purger, must be accompanied by an additional parameter to an organisation session object called data_expires which is larger than 0, this will define in seconds when analytics records for the inbound request will expire.


Set this value to true to have the Tyk node enforce Organisation quotas on the APIs it is managing.


Set this value to true to make it possible to have detail logging occur on a per-organisation basis, org quotas must also be enabled for this to work. Setting enable_detail_recording in the org session object will enable or disable the logging method on the fly.


This will by default be enabled, this is a new improved rate limiter that offers a significant improvement in performance by not using transactions on redis rate-limit buckets. To go back to the old rate limiter, imply set this value to false.


To enable, set to true The 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, i.e. when a throttling action is triggered, they are required to cool-down for the period of the rate limit.

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. I.e. the client can slow their connection throughput to regain entry into their rate limit, this is more of a “throttle” than a “block”. The standard rate limiter offers similar performance as the sentinel-based limiter. This is disabled by default.


Setting this option to true will cause the organisation quota checker to handle quota limits off the main request pipeline, this can provide a speed boost in some situations. enabling this will cause quotas to be enforced by a “lock”, in order to re-access the API once the quota has reset, the lock must be broken by sending one failed request, this will cause the sentinel to be disabled and allow traffic to pass normally again.


Set these options to hard-code values into the way the HTTP server behaves. this is highly experimental and should only b used for extreme tuning purposes it is not recommended to be used unless absolutely necessary.

"http_server_options": {
    "override_defaults": false,
    "use_ssl": false,
    "enable_websockets": false,
    "flush_interval": 1,
    "certificates": [
            "domain_name": "ssl.domain.com",
            "cert_file": "./certs/ssl.domain.com.cert",
            "key_file": "./certs/ssl.domain.com.cert.key"
            "domain_name": "cname.domain.com",
            "cert_file": "./certs/cert2/cname.domain.com.cert.cert",
            "key_file": "./certs/cert2/cname.domain.com.key"


Set to true to enable SSL connections


A list of certificates and domains to match against. Please see the SSL section for more detail for this feature


Set this to the number of seconds that Tyk should use to flush content from the proxied upstream connection tot he open downstream connection. This is usually required for HTTP Streams.

For more resilient connection management, it is suggested to use the close_connections option below.

[As of v2.2] Flush interval is in milliseconds


[As of v2.2]

Tyk supports transparent websocket connection upgrades, to enable this feature, ensure that this value is set to true


Set this value to true to force Tyk to get clients to close the connection with the client, otherwise the connections will remain open for as long as your OS keeps TCP connections open, this can cause a file-handler limit to be exceeded.


If you do not wish for virtual path JavaScript code that is loaded from the dashboard to run on virtual endpoints in the node, set this value to false and the code will not be loaded into the VM when the API definition initialises. This is useful for systems where you want to avoid having third-party code run.


The monitor section is useful if you wish to enforce a global trigger limit on organisation and user quotas. this feature will trigger a webhook event to fire when specific triggers are reached. Triggers can be global (set in the node), by organisation (set in the organisation session object) or by key (set in the key session object).

While Organisation-level and Key-level triggers can be tiered (e.g. trigger at 10%, trigger at 20%, trigger at 80%), in the node-level configuration only a global value can be set. If a global value and specific trigger level are the same the trigger will only fire once:

“monitor”: { “enable_trigger_monitors”: true, “configuration”: { “method”: “POST”, “target_path”: “http://domain.com/notify/quota-trigger”, “template_path”: “templates/monitor_template.json”, “header_map”: {“some-secret”: “89787855”}, “event_timeout”: 10 }, “global_trigger_limit”: 80.0, “monitor_user_keys”: false, “monitor_org_keys”: true },


Set this to true to have monitors enabled in your configuration for the node


The method to use for the webhook


The target path on which to send the request


The template to load in order to format the request


Headers to set when firing the webhook


The cool-down for the event so it does not trigger again (in seconds)


The trigger limit, as a percentage of the quota that must be reached in order to trigger the event, any time the quota percentage is increased the event will trigger.


Apply the monitoring subsystem to user keys


Apply the monitoring subsystem to organisation keys


Tyk can cache some data locally, this can speed up lookup times on a single node and lower the number of connections and operations being done on reddis, it will however introduce a slight delay when updating or modifying keys as the cache must expire.

This does not affect rate limiting.


By default sessions are set to cache, set this to true to stop Tyk from caching keys locally on the node


Tyk nodes can provide uptime awareness, uptime testing and analytics for your underlying APIs uptime and availability.

Tyk can also notify you when a service goes down.


To disable uptime tests on this node, switch this value to true


The configuration section for the uptime tests on this node.


Set this value to true to have the node capture and record analytics data regarding the uptime tests


The sample size to trigger a HostUp or HostDown event, e.g. a setting of 3 will require at least three failures to occur before the uptime test is triggered.


The amount of seconds between tests runs, all tests will run simultaneously, this value will set the periodicity between those tests. e.g. A value of 60 will run all uptime teests every 60 seconds.


The goroutine pool size to keep idle for uptime tests, if you have many uptime tests running at a high periodicity, then make this value higher.


The hostname to bind the node to. If set, all API traffic must go via this host name, otherwise it will raise a 404.


Set this value to true to enable this node to bind APIs to custom domains set in the API definition


By default we have now disabled the JavaScript middleware system to ensure higher performance on nodes. If you are using the JSVM (custom middleware, or virtual paths), then enable this setting.


For additional security it is possible to have Tyk put it’s REST API on a separate hostname, this means that all calls to the /api functions must go via this hostname for this node otherwise they will 404. This is useful if you do not wish to expose the Tyk API to proxy API users.


The hostname to bind the REST API to.


Change the expiry time of refresh token, by default 1 hour (in seconds)


Change the expiry time of OAuth token (in seconds)


[As of v2.1]

By default, in a Pro installation, Tyk will load Policy IDs and use the internal object-ID as the ID of the policy. This is not portable in cases where the data needs to be moved from installation to installation.

If you set this value to true, then the “id” parameter in a stored policy (or imported policy using the REST API of the Dashboard), will be used instead of the internal ID.

This options should only be used when transporting an installation to a new database

Was this article helpful to you? Yes No