Login 24/7 Support Community

Tyk Gateway Configuration Options

Tyk Gateway Configuration

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

Environment Variables

Environment variables (env var) can be used to override the settings defined in the configuration file. Where an environment variable is specified, its value will take precedence over the value in the configuration file.

tyk lint

In v2.4 we have added a new tyk lint command which will validate your tyk.conf file and validate it for syntax correctness, misspelled attribute names or format of values. The Syntax can be:

tyk lint or tyk --conf=path lint

If --conf is not used, the first of the following paths to exist is used:

./tyk.conf /etc/tyk/tyk.conf

listen_port

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

(env var:TYK_GW_LISTENPORT)

node_secret

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

(env var:TYK_GW_NODESECRET)

secret

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-Authorization header 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.

(env var:TYK_GW_SECRET)

template_path

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).

(env var:TYK_GW_TEMPLATEPATH)

app_path

If Tyk is being used in its standard configuration (CE Mode), then API definitions are stored in the apps folder (by default in /opt/tyk-gateway/apps). This file is scanned for files that ending in .json extension and interpreted at startup or reload. See the API Management section of the Tyk Gateway API for more details.

(env var:TYK_GW_APPPATH)

hash_keys

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 its 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.

(env var:TYK_GW_HASHKEYS)

enable_hashed_keys_listing

This is set to false by default. If you set this to true you are able to retrieve all (or per API) key hash listings. This needs to be enabled in the Tyk Gateway configuration file tyk.conf and in the Tyk Dashboard configuration file tyk_analytics.conf. Restart both the Gateway and Dashboard after making any changes.

(env var:TYK_GW_ENABLEHASHEDKEYSLISTING)

allow_master_keys

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.

(env var:TYK_GW_ALLOWMASTERKEYS)

min_token_length

This allows you to set a minimum key length for Authorisation key requests. Any request containing less than the minimum length will automatically rejected. The default setting is 3.

(env var:TYK_GW_MINTOKENLENGTH)

use_db_app_configs

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.

(env var:TYK_GW_USEDBAPPCONFIGS)

db_app_conf_options

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

db_app_conf_options.connection_string

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

(env var:TYK_GW_DBAPPCONFOPTIONS_CONNECTIONSTRING)

Note

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

db_app_conf_options.node_is_segmented

Set to true to enable filtering (sharding) of APIs.

(env var:TYK_GW_DBAPPCONFOPTIONS_NODEISSEGMENTED)

Note

If you set to true for multiple gateway nodes, you should ensure that management_node is set to false. This is to ensure visibility for the management node across all APIs.

db_app_conf_options.tags

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

(env var:TYK_GW_DBAPPCONFOPTIONS_TAGS)

storage

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

storage.type

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

(env var:TYK_GW_STORAGE_TYPE)

storage.host

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

(env var:TYK_GW_STORAGE_HOST)

storage.port

The Redis instance port.

(env var:TYK_GW_STORAGE_PORT)

storage.password

If your Redis instance has a password set for access, you can tell Tyk about it here.

(env var:TYK_GW_STORAGE_PASSWORD)

storage.timeout

Set cutom timeout for Redis network operations. Default value 5 seconds.

(env var:TYK_GW_STORAGE_TIMEOUT)

storage.optimisation_max_idle

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

(env var:TYK_GW_STORAGE_MAXIDLE)

storage.use_ssl

Enable SSL/TLS connection between Tyk Gateway & Redis.

(env var:TYK_GW_STORAGE_USESSL)

enable_analytics

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

(env var:TYK_GW_ENABLEANALYTICS)

Note

For performance reasons, Tyk will store traffic data to Redis initially and then purge the data from Redis to MongoDB or other, data stores, on a regular basis as determined by the purge_delay setting in your Tyk Pump configuration.

analytics_config

This section defines options on what analytics data to store.

analytics_config.enable_detailed_recording

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 degradation on analytics processing by the Dashboard. This setting can be overridden 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.

(env var:TYK_GW_ANALYTICSCONFIG_ENABLEDETAILEDRECORDING)

analytics_config.enable_geo_ip and analytics_config.geo_ip_db_path

enable_geo_ip

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.

Please make sure you have also enabled analytics storing by setting <code>enable_analytics</code> in the Gateway.

(env var:TYK_GW_ANALYTICSCONFIG_ENABLEGEOIP)

geo_ip_db_path

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

Don’t forget to mount it in case you use containers.

(env var:TYK_GW_ANALYTICSCONFIG_GEOIPDBLOCATION)

analytics_config.ignored_ips

Adding IP addresses to this list will cause Tyk to ignore these IPs 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. The IP addresses must be provided as a JSON array, with the values being single IPs. CIDR values are not supported.This is useful for health checks and other samplers that might skew usage data.

(env var:TYK_GW_ANALYTICSCONFIG_IGNOREDIPS)

analytics_config.normalise_urls

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

(env var:TYK_GW_ANALYTICSCONFIG_NORMALISEURLS_ENABLED)

analytics_config.normalise_urls.enabled

Set this to true to enable normalisation.

(env var:TYK_GW_ANALYTICSCONFIG_NORMALISEURLS_ENABLED)

analytics_config.normalise_urls.normalise_uuids

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}

(env var:TYK_GW_ANALYTICSCONFIG_NORMALISEURLS_NORMALISEUUIDS)

analytics_config.normalise_urls.normalise_numbers

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

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

(env var:TYK_GW_ANALYTICSCONFIG_NORMALISEURLS_NORMALISENUMBERS)

analytics_config.normalise_urls.custom_patterns

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.

(env var:TYK_GW_ANALYTICSCONFIG_NORMALISEURLS_CUSTOM)

analytics_config.storage_expiration_time

You can set a time (in seconds) to configure how long analytics are kept if they are not processed. The default is 60 seconds. This is used to prevent the potential infinite growth of Redis analytics storage.

(env var:TYK_GW_ANALYTICSCONFIG_STORAGEEXPIRATIONTIME)

analytics_config.purge_interval

You can set the interval length on how often the gateway will purge analytics data, this value is in seconds and defaults to 10 seconds.

(env var:TYK_GW_ANALYTICSCONFIG_PURGEINTERVAL)

Note

This option is available from v2.5.2 onwards.

analytics_config.enable_multiple_analytics_keys

Set this to true to have Tyk automatically divide the analytics records in multiple analytics keys. This is especially useful when storage.enable_cluster is true since it will distribute the analytic keys across all the cluster nodes.

(env var:TYK_GW_ANALYTICSCONFIG_ENABLEMULTIPLEANALYTICSKEYS)

Note

This option is available from v3.2.0 and Pump v1.2.1 onwards.

policies

The policies section allows you to define where Tyk can find its 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.

policies.policy_source

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

(env var:TYK_GW_POLICIES_POLICYSOURCE)

policies.policy_connection_string

This option is required if you desire to use policies.policy_source as service. Set this to the URL of your dashboard installation, the URL should take the form of: http://dashboard_host:port.

(env var:TYK_GW_POLICIES_POLICYCONNECTIONSTRING)

policies.policy_record_name

This option is required if you desire to use policies.policy_source as file. Specifies the path of a JSON file containing the available policies.

(env var:TYK_GW_POLICIES_POLICYRECORDNAME)

policies.allow_explicit_policy_id

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 option should only be used when transporting an installation to a new database.

(env var:TYK_GW_POLICIES_ALLOWEXPLICITPOLICYID)

health_check

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

health_check.enable_health_checks

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

(env var:TYK_GW_HEALTHCHECK_ENABLEHEALTHCHECKS)

health_check_endpoint_name

From v2.7.5 you can now rename the /hello endpoint by using this option.

(env var:TYK_GW_HEALTHCHECKENDPOINTNAME)

health_check.health_check_value_timeouts

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.

(env var:TYK_GW_HEALTHCHECK_HEALTHCHECKVALUETIMEOUT)

http_server_options

Set these options to hard-code values into the way the HTTP server behaves.

"http_server_options": {
  "enable_http2": true,
  "override_defaults": false,
  "use_ssl": false,
  "enable_websockets": false,
  "flush_interval": 1,
  "read_timeout": 120,
  "write_timeout": 120,
  "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"
    }
  ],
  "ssl_insecure_skip_verify": false
},

http_server_options.enable_http2

This defaults to true for HTTP/2 connections.

(env var:TYK_GW_HTTPSERVEROPTIONS_ENABLEHTTP2)

http_server_options.use_ssl

Set to true to enable SSL connections.

(env var:TYK_GW_HTTPSERVEROPTIONS_USESSL)

http_server_options.certificates.domain_name

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

(env var:TYK_GW_HTTPSERVEROPTIONS_CERTIFICATES_NAME)

http_server_options.ssl_certificates

Added in v2.4, as altertnative to http_server_options.certificates, which supports our Certificate API format. It should be a list of certificate IDs returned by Certificate API, or paths to certificate in PEM format (including private key).

(env var:TYK_GW_HTTPSERVEROPTIONS_SSLCERTIFICATES)

http_server_options.skip_url_cleaning

Setting this option to true will allow the use of a double slash in url path, and can be useful if you need to pass raw URLs to your API endpoints. For example: http://myapi.com/get/http://example.com.

(env var:TYK_GW_HTTPSERVEROPTIONS_SKIPURLCLEANING)

http_server_options.skip_target_path_escaping

Setting this option to true will disable automatic character escaping, allowing to path original url data to the upstream.

(env var:TYK_GW_HTTPSERVEROPTIONS_SKIPTARGETPATHESCAPIN)

http_server_options.flush_interval

Set this to the number of seconds that Tyk should use to flush content from the proxied upstream connection to the 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.

(env var:TYK_GW_HTTPSERVEROPTIONS_FLUSHINTERVAL)

flush_interval is set in milliseconds.

http_server_options.enable_websockets

As of v2.2, Tyk supports transparent websocket connection upgrades, to enable this feature, ensure that this value is set to true.

(env var:TYK_GW_HTTPSERVEROPTIONS_ENABLEWEBSOCKETS)

http_server_options.ssl_insecure_skip_verify

Allows usage of self-signed certificates when connecting to the Gateway.

(env var:TYK_GW_HTTPSERVEROPTIONS_SSLINSECURESKIPVERIFY)

http_server_options.read_timeout

Network read timeout for user requests processed by Tyk. Defaults to 120 seconds.

(env var:TYK_GW_HTTPSERVEROPTIONS_READTIMEOUT)

http_server_options.read_timeout

Network write timeout for user requests processed by Tyk. Defaults to 120 seconds.

(env var:TYK_GW_HTTPSERVEROPTIONS_READTIMEOUT)

security.pinned_public_keys

Use this option to map pinned public keys. You need to use the following format:

{
  "example.com": "<key-id>",
  "foo.com": "/path/to/pub.pem",
  "*.wild.com": "<key-id>,<key-id-2>"
}

For key-id you should set the ID returned after you upload the public key using the Certificate API. Additionally, you can just set path to public key, located on your server. You can specify multiple public keys by separating their IDs by a comma. Upstream certificates now also have wildcard domain support

Note that only public keys in PEM format are supported.

(env var:TYK_GW_SECURITY_PINNEDPUBLICKEYS)

Note

This option is available from v2.6.0 onwards.

close_connections

Set this value to true to force Tyk 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. Setting to false can have performance benefits as the connection can be reused.

Prior to v2.6 this setting controlled the behaviour of both the client/Tyk connection and Tyk/server connection. Since v2.6 it is just for the client/Tyk connection, with Tyk/server being controlled by proxy_close_connections

(env var:TYK_GW_CLOSECONNECTIONS)

Note

This option is available from v2.3.5 onwards.

proxy_close_connections

Set this value to true to force Tyk to close the connection with the server, 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. Setting to false can have performance benefits as the connection can be reused.

(env var:TYK_GW_CLOSECONNECTIONS)

Note

This option is available from v26 onwards.

monitor

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
},

monitor.enable_trigger_monitors

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

(env var:TYK_GW_MONITOR_ENABLETRIGGERMONITORS)

monitor.configuration.method

The method to use for the webhook.

(env var:TYK_GW_MONITOR_CONFIG_METHOD)

monitor.configuration.target_path

The target path on which to send the request.

(env var:TYK_GW_MONITOR_CONFIG_TARGETPATH)

monitor.configuration.template_path

The template to load in order to format the request.

(env var:TYK_GW_MONITOR_CONFIG_TEMPLATEPATH)

monitor.configuration.header_map

Headers to set when firing the webhook.

(env var:TYK_GW_MONITOR_CONFIG_HEADERLIST)

monitor.configuration.event_timeout

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

(env var:TYK_GW_MONITOR_CONFIG_EVENTTIMEOUT)

monitor.global_trigger_limit

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.

(env var:TYK_GW_MONITOR_GLOBALTRIGGERLIMIT)

monitor.monitor_user_keys

Apply the monitoring subsystem to user keys.

(env var:TYK_GW_MONITOR_MONITORUSERKEYS)

monitor.monitor_org_keys

Apply the monitoring subsystem to organisation keys.

(env var:TYK_GW_MONITOR_MONITORORGKEYS)

uptime_tests

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.

uptime_tests.disable

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

(env var:TYK_GW_UPTIMETESTS_DISABLE)

uptime_tests.poller_group

Change the default poller group of the uptime tests.

(env var:TYK_GW_UPTIMETESTS_POLLERGROUP)

uptime_tests.config

The configuration section for the uptime tests on this node.

uptime_tests.config.enable_uptime_analytics

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

(env var:TYK_GW_UPTIMETESTS_CONFIG_ENABLEUPTIMEANALYTICS)

uptime_tests.config.failure_trigger_sample_size

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.

(env var:TYK_GW_UPTIMETESTS_CONFIG_FAILURETRIGGERSAMPLESIZE)

uptime_tests.config.time_wait

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 tests every 60 seconds.

(env var:TYK_GW_UPTIMETESTS_CONFIG_TIMEWAIT)

uptime_tests.config.checker_pool_size

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.

(env var:TYK_GW_UPTIMETESTS_CONFIG_CHECKERPOOLSIZE)

local_session_cache

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 Redis, it will however introduce a slight delay when updating or modifying keys as the cache must expire.

This does not affect rate limiting.

(env var:TYK_GW_LOCALSESSIONCACHE_CACHESESSIONEVICTION)

local_session_cache.disable_cached_session_state

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

(env var:TYK_GW_LOCALSESSIONCACHE_DISABLECACHESESSIONSTATE)

oauth_token_expire

Change the expiry time of OAuth token (in seconds).

(env var:TYK_GW_OAUTHTOKENEXPIRE)

oauth_refresh_token_expire

Change the expiry time of refresh token, by default 14 days (in seconds).

(env var:TYK_GW_OAUTHREFRESHEXPIRE)

oauth_token_expired_retain_period

Specifies how long expired tokens are stored in Redis. The value is in seconds and the default is 0. Using the default means expired tokens are never removed from Redis.

(env var:TYK_GW_OAUTHTOKENEXPIREDRETAINPERIOD)

Note

This option is available from v2.6 onwards.

control_api_hostname

The hostname to bind the REST API to.

(env var:TYK_GW_CONTROLAPIHOSTNAME)

control_api_port

This allows you to run the Gateway Control API on separate port, and protect it behind a firewall if needed. Please make sure you follow these instructions when setting the control port.

(env var:TYK_GW_CONTROLAPIPORT)

Note

This option is available from v2.4 onwards.

enable_api_segregation

For additional security it is possible to have Tyk put its 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.

(env var:TYK_GW_ENABLEAPISEGREGATION)

Note

This has been deprecated. Enter a value for control_api_hostname instead.

hostname

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

(env var:TYK_GW_HOSTNAME)

enable_custom_domains

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

(env var:TYK_GW_ENABLECUSTOMDOMAINS)

proxy_enable_http2

This defaults to true for HTTP/2 upstream connections.

(env var:TYK_GW_PROXYENABLEHTTP2)

enable_jsvm

This defaults to false. Set to true if you are using JSVM custom middleware or virtual endpoints.

(env var:TYK_GW_ENABLEJSVM)

disable_virtual_path_blobs

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 true 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.

(env var:TYK_GW_DISABLEVIRTUALPATHBLOBS)

experimental_process_org_off_thread

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.

(env var:TYK_GW_EXPERIMENTALPROCESSORGOFFTHREAD)

enable_sentinel_rate_limiter

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 cool-down 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.

(env var:TYK_GW_ENABLESENTINELRATELIMITER)

enable_non_transactional_rate_limiter

This will be enabled by default. 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, simply set this value to false.

(env var:TYK_GW_ENABLENONTRANSACTIONALRATELIMITER)

enforce_org_data_detail_logging

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.

(env var:TYK_GW_ENFORCEORGDATADETAILLOGGING)

enforce_org_quotas

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

(env var:TYK_GW_ENFORCEORGQUOTAS)

enforce_org_data_age

Set to true to have Tyk enforce data age on analytics data sent to the Mongo DB purger. This 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.

(env var:TYK_GW_ENFORCEORGDATAAGE)

use_sentry

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

(env var:TYK_GW_USESENTRY)

sentry_code

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

(env var:TYK_GW_SENTRYCODE)

suppress_redis_signal_reload

Tyk 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.

(env var:TYK_GW_SUPPRESSREDISSIGNALRELOAD)

optimisations_use_async_session_write

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

Note

This has been deprecated. Removed from v3.0.3+ and 3.1.1+ onwards.

disable_dashboard_zeroconf

Disable the capability of the Gateway to “autodiscover” the Dashboard through heartbeat messages via Redis. The goal of zeroconf is auto-discovery, so you do not have to specify the Tyk Dashboard address in tyk.conf. In some specific cases, for example, when the Dashboard is bound to a public domain, not accessible inside an internal network, or similar, disable_dashboard_zeroconf can be set to true, in favour of directly specifying a Tyk Dashboard address.

(env var:TYK_GW_DISABLEDASHBOARDZEROCONF)

auth_override

Is used as part of the RPC / Hybrid back-end configuration when using Tyk Enterprise and isn’t used anywhere else.

use_redis_log

Enables the real-time Gateway log view in the Dashboard.

(env var:TYK_GW_USEREDISLOG)

management_node

If set to true, distributed rate limiter will be disabled for this node, and it will be excluded from rate limit calculation.

(env var:TYK_GW_MANAGEMENTNODE)

Note

If you set db_app_conf_options.node_is_segmented to true for multiple gateway nodes, you should ensure that management_node is set to false. This is to ensure visibility for the management node across all APIs.

proxy_ssl_insecure_skip_verify

This boolean option allows you to skip SSL checking for upstream APIs with self-signed certificates. The default setting is false.

(env var:TYK_GW_PROXYSSLINSECURESKIPVERIFY)

Note

This option is available from v2.3.5 onwards.

proxy_default_timeout

This can specify a default timeout in seconds for upstream API requests.

(env var:TYK_GW_PROXYDEFAULTTIMEOUT)

Note

This option is available from v2.3.8 onwards.

log_level

You can now set a logging level (log_level). The following levels can be set:

  • debug
  • info
  • warn
  • error

If unset or left empty, it will default to info.

(env var:TYK_GW_LOGLEVEL)

Note

This option is available from v2.4 onwards.

enable_key_logging

By default all key ids in logs are hidden. Turn it on if you want to see them for debugging reasons.

(env var:TYK_GW_ENABLEKEYLOGGING)

Note

This option is available from v2.5 onwards.

max_conn_time

This setting forces a DNS cache flush (in seconds). The default setting is 0.

(env var:TYK_GW_MAXCONNTIME)

Note

This option is available from v2.5.2 onwards.

proxy_ssl_min_version

You use this setting to have Tyk only accept connections from TLS V1.0, 1.1 and 1.2 respectively.

You need to use the following values for this setting:

TLS Version Value to Use
1.0 769
1.1 770
1.2 771
1.3 772

(env var:TYK_GW_PROXYSSLMINVERSION)

proxy_ssl_ciphers

This allows you to add ssl ciphers which takes an array of strings as its value.

Each string must be one of the allowed cipher suites as defined at https://golang.org/pkg/crypto/tls/#pkg-constants

(env var:TYK_GW_PROXYSSLCIPHERSUITES)

proxy_ssl_disable_renegotiation

From v2.7.2, TLS renegotiation is now enabled by default. You can disable it by setting proxy_ssl_disable_renegotiation to false.

(env var:TYK_GW_PROXYSSLDISABLERENEGOTIATION)

disable_regexp_cache

If set to true this allows you to disable the regular expression cache. The default setting is false.

(env var:TYK_GW_DISABLEREGEXPCACHE)

Note

This option is available from v2.7.0 onwards.

regexp_cache_expire

If you set disable_regexp_cache to false, you can use this setting to limit how long the regular expression cache is kept for in seconds. The default is 60 seconds. This must be a positive value. If you set to 0 this sets it uses the default value.

(env var:TYK_GW_REGEXPCACHEEXPIRE)

Note

This option is available from v2.7.0 onwards.

Key Value store

This section enables the usage of the KV capabilites to subsitute configuration values.

{
  "kv": {
    "consul": {
      "address": "localhost:8025",
      "scheme": "http",
      "datacenter": "dc-1",
      "timeout": 30,
      "http_auth": {
        "username": "username",
        "password": "password"
      },
      "wait_time": 10,
      "token": "Token if available",
      "tls_config": {
        "address": "",
        "ca_path": "",
        "ca_file": "",
        "cert_file": "",
        "key_file": "",
        "insecure_skip_verify": false
      }
    },
    "vault": {
      "address": "http://localhost:1023",
      "agent_adress": "input if available",
      "max_retries": 3,
      "timeout": 30,
      "token": "token if available",
      "kv_version": 2
    }
  }
}

Consul

kv.consul.address

The address of the consul server

(env var:TYK_GW_KV_CONSUL_ADDRESS)

kv.consul.scheme

The URI scheme of the Consul server.

Valid values: http, https

(env var:TYK_GW_KV_CONSUL_SCHEME)

kv.consul.datacenter

The datacenter the consul agent is running in.

Default : dc1

(env var:TYK_GW_KV_CONSUL_DATACENTER)

kv.consul.wait_time

This limits how long a Watch will block

Default: 0

(env var:TYK_GW_KV_CONSUL_WAITTIME)

kv.consul.http.auth

HTTP Basic authentication to the Consul server.

kv.consul.http_auth.username

This is the username that is needed to perform the authentication to the server.

(env var:TYK_GW_KV_CONSUL_HTTPAUTH_USERNAME)

kv.consul.http_auth.password

This is the password that is needed to perform the authentication to the server.

(env var:TYK_GW_KV_CONSUL_HTTPAUTH_PASSWORD)

kv.consul.token

Per request ACL token which will override the default agent’s token.

(env var:TYK_GW_KV_CONSUL_TOKEN)

kv.consul.tls_config

kv.consul.tls_config.address

Optional. This is the adress of the consul server.

(env var:(env var:TYK_GW_KV_CONSUL_TLSCONFIG_ADDRESS))

kv.consul.tls_config.ca_path

Optional. This is the path to the CA certificates used by the Consul server. It defaults to the system certificates’ path.

(env var:TYK_GW_KV_CONSUL_TLSCONFIG_CAPATH)

kv.consul.tls_config.cert_file

The path to the certificate file used by the Consul server.

(env var:TYK_GW_KV_CONSUL_TLSCONFIG_CERTFILE)

kv.consul.tls_config.key_file

Path to the private cert file. If this is provided, then kv.consul.tls_config.cert_file must be set too.

(env var:TYK_GW_KV_CONSUL_TLSCONFIG_KEYFILE)

kv.consul.tls_config.insecure_skip_verify

Disable TLS verification

(env var:TYK_GW_KV_CONSUL_TLSCONFIG_INSECURESKIPVERIFY)

Vault

kv.vault.address

Address of the vault server.

Defaults : https://127.0.0.1:8200. It can be overriden with VAULT_ADDR.

(env var:TYK_GW_KV_VAULT_ADDRESS)

kv.vault.agent_address

Address of the local Vault agent

(env var:TYK_GW_KV_VAULT_AGENTADDRESS)

kv.vault.max_retries

Controls the maximum number of times to retry when an internal error occurs

Defaults: 2.

(env var:TYK_GW_KV_VAULT_MAXRETRIES)

kv.vault.max_retries

Controls the maximum number of times to retry when an internal error occurs

Defaults: 2.

(env var:TYK_GW_KV_VAULT_MAXRETRIES)

kv.vault.timeout

Timeout for HTTP client

(env var:TYK_GW_KV_VAULT_TIMEOUT)

kv.vault.token

Token to authenticate requests to the Vault server.

(env var:TYK_GW_KV_VAULT_TOKEN)

kv.vault.kv_version

KV version of Vault.

Defaults: 2.

(env var:TYK_GW_KV_VAULT_KVVERSION)

Secrets map

Values that are set in this map will be available for use to your app. Please take a look at KV store reference for usage

"secrets": {
    "key": "value",
    "yet_another_key": "yet_another_value",
}

Note

Please use Consul/Vault to store more sensitive data

Environment store

Environment variables can also be used as a KV store. A value in the environment as SOME_VALUE will be accessible as env://SOME_VALUE.

Please take a look at KV store reference for usage

Note

Please use Consul/Vault to store more sensitive data

DNS caching

DNS caching

This section enables the global configuration of the expireable dns records caching for gateway API endpoints. By design caching affects only http(s), ws(s) protocols apis and doesn’t affect any plugin/middleware dns queries.

"dns_cache": {
    "enabled": true, //Turned off by default
    "ttl": 60, //Time in seconds before the record will be removed from cache
    "multiple_ips_handle_strategy": "random" //A strategy, which will be used when dns query will reply with more than 1 ip address per single host.
}

dns_cache.enabled

Valid values: true, false Default value: false Setting this value to true will enable caching of dns queries responses used for API endpoint’s host names. By default caching is disabled.

(env var:TYK_GW_DNSCACHE_ENABLED)

dns_cache.ttl

Units: seconds Default value: 0 This setting allows to specify duration in seconds before the record will be removed from cache after being added to it on first dns query resolution of API endpoints. Setting ttl to -1 prevents record from being expired and removed from cache on next check interval.

(env var:TYK_GW_DNSCACHE_TTL)

dns_cache.multiple_ips_handle_strategy

Valid values: pick_first, random, no_cache A strategy, which will be used when dns query will reply with more than 1 ip address per single host. As dns query response ip addresses can have changing order depending on dns server balancing strategy(eg: round robin, geographically dependent origin-ip ordering, etc) this option allows to not to limit connection to first host within cached response list or prevent response caching.

  • pick_first will instruct gateway to connect to first ip in returned ips list and cache the response.
  • random will instruct gateway to connect to random ip in returned ips list and cache the response.
  • no_cache will instruct gateway to connect to first ip in returned ips list and fetch each addresses list without caching on each API endpoint dns query.

(env var:TYK_GW_DNSCACHE_MULTIPLEIPSHANDLESTRATEGY)

hide_generator_header

By default, we set the X-Generator header to tyk.io when returning errors. You can set hide_generator_header to trueto turn this header off.

(env var:TYK_GW_HIDEGENERATORHEADER)

oauth_error_status_code

New in v2.9.2, you can now configure the OAuth error status code returned. If not set, it defaults to a 403 error.

(env var:TYK_GW_OAUTHERRORSTATUSCODE)

override_messages

New in 2.9.4, you can now override the default error code and or message returned by middleware. The following message IDs can be used to override the message and error codes:

(env var:TYK_GW_OVERRIDEMESSAGES_MESSAGE)

AuthToken message IDs

  • auth.auth_field_missing
  • auth.key_not_found

OIDC message IDs

  • oauth.auth_field_missing
  • oauth.auth_field_malformed
  • oauth.key_not_found
  • oauth.client_deleted

Sample Override Message Setting

"override_messages": {
  "oauth.auth_field_missing" : {
    "code": 401,
    "message": "Token is not authorised"
  }
}

ignore_endpoint_case

New in v2.9.4 you can now configure Tyk to ignore the case of any endpoints for APIs managed by Tyk. Setting this to true will override any individual API and Ignore, Blacklist and Whitelist plugin endpoint settings.

(env var:TYK_GW_IGNOREENDPOINTCASE)

ssl_force_common_name_check

From v2.9.3 you can force the validation of the hostname against the common name by setting ssl_force_common_name_check to true.

(env var:TYK_GW_SSLFORCECOMMONNAMECHECK)

track_404_logs

From v3.0 you can log all the 404 errors happening if user tried to access Gateway with unknown listen path. The log level used for these records is Error and the feature can be enabled by setting the config track_404_logs to true in the gateway’s config file.

(env var:TYK_GW_TRACK404LOGS)

Slave options

The slave_options allow you to configure the RPC slave connection for MDCB installations. These settings must be configured for every RPC slave/worker node.

slave_options.use_rpc

Set to true to connect a worker gateway using RPC.

(env var:TYK_GW_SLAVEOPTIONS_USERPC)

slave_options.use_ssl

Set this option to true to use an SSL RPC connection.

(env var:TYK_GW_SLAVEOPTIONS_USESSL)

slave_options.ssl_insecure_skip_verify

Set this option to true to allow the certificate validation (certificate chain and hostname) to be skipped. This can be useful if you use a self-signed certificate.

(env var:TYK_GW_SLAVEOPTIONS_SSLINSECURESKIPVERIFY)

slave_options.connection_string

Use this setting to add the URL for your MDCB or load balancer host.

(env var:TYK_GW_SLAVEOPTIONS_CONNECTIONSTRING)

slave_options.rpc_key

Your organisation ID to connect to the MDCB installation.

(env var:TYK_GW_SLAVEOPTIONS_RPCKEY)

slave_options.api_key

This the API key of a user used to authenticate and authorise the Gateway’s access through MDCB. The user should be a standard Dashboard user with minimal privileges so as to reduce risk if compromised. The suggested security settings are read for Real-time notifications and the remaining options set to deny.

(env var:TYK_GW_SLAVEOPTIONS_APIKEY)

slave_options.enable_rpc_cache

Set this option to true to enable RPC caching for keys.

(env var:TYK_GW_SLAVEOPTIONS_ENABLERPCCACHE)

slave_options.bind_to_slugs

Set this option to true to bind to the API slug/name instead of the listen path. For Self-Managed installations, including Hybrid Gateway installations, this can be left at false (the default setting).

(env var:TYK_GW_SLAVEOPTIONS_BINDTOSLUGSINSTEADOFLISTENPATHS)

slave_options.disable_keyspace_sync

Set this option to true if you don’t want to monitor changes in the keys from a master Gateway.

(env var:TYK_GW_SLAVEOPTIONS_DISABLEKEYSPACESYNC)

slave_options.group_id

This is the “zone” that this instance inhabits, e.g. the cluster/data-centre the Gateway lives in. The group ID must be the same across all the Gateways of a data-centre/cluster which are also sharing the same Redis instance. This ID should also be unique per cluster (otherwise another Gateway cluster can pick up your keyspace events and your cluster will get zero updates).

(env var:TYK_GW_SLAVEOPTIONS_GROUPID)

slave_options.call_timeout

Call Timeout allows to specify a time in seconds for the maximum allowed duration of a RPC call.

(env var:TYK_GW_SLAVEOPTIONS_CALLTIMEOUT)

slave_options.ping_timeout

The maximum time in seconds that a RPC ping can last.

(env var:TYK_GW_SLAVEOPTIONS_PINGTIMEOUT)

slave_options.rpc_pool_size

The number of RPC connections in the pool, basically it creates a set of connections that you can re-use as needed.

(env var:TYK_GW_SLAVEOPTIONS_RPCPOOLSIZE)

slave_options.key_space_sync_interval

You can use this config to set the period’s length in which the gateway will check if there’re changes in keys that must be synchronized, if this value is not set then by default it will be 10 seconds. From 3.0.1 you have the ability to set the interval’s length in which the slaved gateway will check for changes in the key space, this value is measured in seconds.

(env var:TYK_GW_SLAVEOPTIONS_KEYSPACESYNCINTERVAL)

ignore_canonical_mime_header_key

Added in v3.0.2. When enabled Tyk ignores the canonical format of the MIME header keys.

For example when a request header with a “my-header” key is injected using “global_headers”, the upstream would typically get it as “My-Header”, when this flag is enabled it will be sent as “my-header” instead.

(env var:TYK_GW_IGNORECANONICALMIMEHEADERKEY)

Current support is limited to JS plugins, global header injection, virtual endpoint and JQ transform header rewrites. This functionality doesn’t affect headers that are sent by the HTTP client and the default formatting will apply for this case.

For technical details refer to the CanonicalMIMEHeaderKey functionality in the Go documentation.