Documentation Documentation

API Definition Object Details

Tyk handles APIs through files / objects called Definitions. These either sit in the /etc/tyk/apps directory or in a MongoDB collection.

An API Definition has many switches that change the way an incoming request is handled. It is possible to set too many options in a definition which can lead to unexpected behaviour.

With this in mind, we have split this section into the most common settings that are used together.

Common elements

  • id: This is only used in the MongoDB context and bears no actual relation to the identity of the API.

  • name: Human readable name of the API. It is used for identification purposes but does not act as an index.

  • api_id: The identifier for the API This should be unique, but can actually be any kind of string. For single-instance setups this can probably be set to 1. It is recommended to make this a UUID. The api_id is used when querying the Tyk REST API for configuration details.

  • org_id: This is an identifier that can be set to indicate ownership of an API key or of an individual API. If the the Org ID is set (recommended), it is prepended to any keys generated by Tyk - this enables lookups by prefixes from Redis of keys that are in the system.

  • active: If set to false means that on start, restart or reload, the API will be ignored and all paths and routes for that API will cease to be proxied. Any keys assigned to it will still exist, though they will not be let through for that particular API.

  • session_lifetime: The session lifetime will override the expiry date if it has been set on a key (in seconds). for example, if a key has been created that never expires, then it will remain in the session cache forever unless manually deleted. If a re-auth needs to be forced or a default expiry needs to be applied to all keys, then use this feature to set the session expiry for an entire API.

Authentication type flags

By default, Tyk will revert to a simple authentication token scheme unless these flags and their metadata are set (setting all of these to false will enable standard token mode).

This scheme basically means that you could send an authentication parameter and its value (the API key) along with the request and Tyk will attach it to a session, just like a bearer token in OAuth or a session key in cookie-based setups.

However Tyk supports many more methods, and these can be set by enabling these flags (and their associated metadata).

  • use_keyless: This will switch off all key checking and open the API definition up, some analytics will still be recorded, but rate-limiting, quotas and security policies will not be possible (there is no session to attach requests to). This is a good setting for checking if Tyk works and is proxying traffic correctly.

This method has no additional metadata settings.

  • use_basic_auth: This method will enable basic auth as specified by the HTTP spec, an API with this flag set will request for a username and password and require a standard base64 Authentication header to be let through.

Keys cannot be generated by Tyk for this method and need to use the /tyk/keys/add method with the basic_auth_data metadata set in the keys session configuration (see Basic Authentication and the overview of the Session Object in this use case under Key Management).

  • enable_signature_checking: a.k.a HMAC signing. If this option is set to true, Tyk will attempt to implement the HMAC signing standard as proposed in the HTTP Signatures Spec. In particular the structure of the Authorisation header and the encoding method need to be taken into account.

This method will use a session key to identify a user and a user secret that should be used by the client to sign each request’s date header.

This method will also introduce clock skew checks, requests outside of 300ms of the system time will be rejected.

This method is not recommended for Single-Page-Webapps or Mobile apps due to the fact that secrets need to be distributed.

  • hmac_allowed_clock_skew: Set this value to anything larger than 0 to set the amount of milliseconds that will be tolerated for clock skew. Set to 0 to prevent clock skew checks on requests (only in HMAC mode).

  • use_oauth2: Tyk attempts to implement a semi-seamless OAuth2 flow. Given the nature of OAuth2’s three-party system, it is difficult to implement as a proxy without significantly compromising security or usability.

Enabling this option will cause Tyk to add OAuth2-standard endpoints to the API for /authorize and /token, these will supersede any other requests to your proxied system in order to enable the flow.

Please see the OAuth2 Flow section for a comprehensive discussion of how to integrate with Tyk.

  • oauth_meta.allowed_access_types: Should be a string array of OAuth access options, types can be:

  • authorization_code - client has an authorisation code to request a new access token.

  • refresh_token - client can use a refresh token to refresh expired bearer access token.

Note: If using auth codes and refresh tokens, Tyk needs to notify your webapp of newly issued keys - it does this via web hook. See the section on notifications.

  • oauth_meta.allowed_authorize_types: Should be a string array of OAuth authorisation types - options that are supported are:

    • code - Client can request an authorisation code which can be used to request an access code via a server request (traditionally reserved for server-side apps).
    • token - Client can request an access token directly, this will not enable refresh tokens and all tokens have a 12 hour validity. Recommended for mobile apps and single-page webapps.
  • oauth_meta.auth_login_redirect: The Tyk OAuth flow has a dummy (intercept) /authorize endpoint which basically redirects the user to your login and authentication page, it will also send along all OAuth data as part of the request (so as to mimic a regular app flow).

This is the URL that the user will be sent to (via POST).

Note: This interface method is only supported by modern browsers that respect a 307 redirect (retaining method and data), and varies between browsers.

  • notifications: When Tyk implements an OAuth2 flow, because it will handle access requests on your behalf once authorisation codes have been issued, it will need to notify your system that these have occurred.

It will POST key data to the URL set in these options to ensure that your system is synchronised with Tyk.

  • notifications.shared_secret: Posted data to your service will use this shared secret as an authorisation header. This is to ensure that messages being received are from Tyk and not from another system.

  • notifications.oauth_on_keychange_url: The URL that will be sent the updated information - the URL will be polled up to 3 times if there is a communications failure. On a 200 OK response it stops.

  • auth: The auth section handles the standard Tyk authentication method, and if none of the above are set, will be the method used to authenticate requests.

  • auth.auth_header_name: The header carrying the authentication token.

  • auth.use_param: This will force Tyk to look for the auth_header_name value in the URL querystring parameters instead of in the header.

  • auth.param_name: Added in v2.1, set this to the parameter name to use to extract the auth token if it is empty, then the header name will be used instead.

  • auth.use_cookie: This will force Tyk to look for the auth_header_name value in a cookie.

  • auth.cookie_name: Added in v2.1, this will set the cookie name to use, if blank, then the auth_header_name value will be used.

Versioning and Endpoint Handling

Tyk lets you version your API and apply access policies to versions, for example, if you have an API v1 that has a /widgets endpoint that is deprecated in v2, you can blacklist that endpoint so that requests to it are stopped before they hit your system.

In the same vein, you can white-list and ignore paths completely.

Version data can be transferred as either a header key or as a query parameter in all HTTP methods.

  • definition: This section handles information related to where to look for the version key.

  • definition.location: Can either be:

  • header: Tyk will look for the version information in a header field (e.g. api-version: 1.2.3).

  • url-param: Tyk will check form and request parameters for a key matching the definition.key value.

  • definition.key: The name of the key to check for versioning information.

  • version_data: Information relating to your actual version are stored here, if you do not wish to use versioning, use the not_versioned option and set up an entry called Default (see below).

  • version_data.not_versioned: If set to true Tyk will skip version checking, you can still apply blacklist and whitelist information to your API by specifying a Default version within the versions map.

  • version_data.versions: This is a keyed JSON object, in the form of:

    {
        "version-1": {
            "name": "version-1",
            "expires": "",
            "paths": {
                "ignored": [],
                "white_list": [],
                "black_list": []
            },
            "use_extended_paths": true,
            "extended_paths": {
                "ignored": [],
                "white_list": [],
                "black_list": []
            }
        }
    }

Each version of your API should be defined here with a unique name. This name is what will be matched by definition.key. Once Tyk has identified the API to load, and has allowed the access key through, it will check the access token’s session data for access permissions. If it finds none, it will let the token through. However, if there are permissions and versions defined, it will be strict in only allowing access to that version. For more information about handling access control, please see the access control section.

  • version_data.{version-name}.expires: The expires header, if set, will deprecate access to the API after the time specified. The entry here takes the form of: "YYYY-MM-DD HH:MM". If this is not set the version will never expire.

  • version_data.{version-name}.override_target: Setting this value will override the target of the API for this version, overriding the target will invalidate (and is not compatible with) Round Robin Load balancing and Service Discovery.

  • version_data.{version-name}.ignored (deprecated): This string array can define any paths (endpoints) in your API that should be ignored by Tyk, for example login, signup or any non-authenticated actions users can take. Specify these URL’s here in the form of

    [ "/user/login", "/user/signup" ]

Similar to other routers, matching is done on a first-come-first-served basis, ensuring that specific paths are higher up the list than generic ones.

Note: It is possible to ignore non-generic paths using standard REST documentation markup, e.g. /users/{user_id}/ will ignore /users/12345/ and /users/jively, this is handy for cases where an entire sub-branch of a resource should be ignored (though each wildcard must be specified individually). Parameter names are arbitrary, and should be for reference only.

  • version_data.{version-name}.white_list (deprecated): A string array of paths to white-list in your API. This is an explicit list of paths that are allowed access. Any other endpoints, except those specified in ignored_paths will be refused access. Use this to enforce highly-specific access rules.

Note: White listing paths is exclusive, so black listed paths will not take effect.

  • version_data.{version-name}.black_list (deprecated): The opposite of white_list. This will essentially block access to certain endpoints. This can be very handy if you are moving from a v1 to a v2 and have deprecated a path. Simply define the deprecated path in the list and requests to it with the new version header will be refused.

  • version_data.{version-name}.use_extended_paths: Set this value to true to use the new extended-paths feature. This will eventually become the default mode of operation.

Extended paths allow you to control which upstream paths are to be handled in a specific way (ignored, as part of white list or black list) by both path and method. The extended meta-data set also allows you to provide forced reply data to override or trap inbound requests for specific versions. This is very useful for mocking or slowly exposing a development API to a live upstream back end.

Each entry in the ignored, blacklist and whitelist have the same specification. The path specification has the following format:

    {
        "path": "{managed-path}",
        "method_actions": {
            "METHOD": {
                "action": "{action-code}",
                "code": {response-code},
                "data": "{body}",
                "headers": {
                    "{key}": "{value}"
                }
            }
        }
    }

You can set up the path to handle, and the action type. By default this should be set to no_action which means that Tyk will treat the path and method as-is without interference (i.e. if no_action is set, then code, data, headers and body are not used).

If you set action to reply Tyk will override the path and reply with settings defined in the remaining fields. This configuration can be used across all of the different path lists, and can be very useful when used in conjunction with the white_list access control list as if it is used exclusively it can be used to mock out an entire API.

Note: Any data that is placed in the ‘data’ section must be a string, not a JSON object (this could be a JSON string, for example).

  • global_headers: Set global headers to inject using a key:value map:
    "version_data": {
        "versions": {
            "Default": {
                ...
                "global_headers": {
                    "x-header-name": "x-header-value"
                }
                ...
            }
        }
    },
  • global_headers_remove: Remove headers from all requests:
    "version_data": {
        "versions": {
            "Default": {
                ...
                "global_headers_remove": [
                    "auth_id"
                ]
                ...
            }
        }
    },
  • global_size_limit: Set a global request size limit in bytes.

  • version_data.{version-name}.extended_paths.ignored: This section will define methods and paths that will be ignored and will bypass the quota and rate limiting machinery of Tyk.

An example entry:

    ...
    "ignored": [
        {
            "path": "/v1/ignored/literal",
            "method_actions": {
                "GET": {
                    "action": "no_action",
                    "code": 200,
                    "data": "",
                    "headers": {}
                }
            }
        },
        {
            "path": "/v1/ignored/with_id/{id}",
            "method_actions": {
                "GET": {
                    "action": "reply",
                    "code": 200,
                    "data": "Hello World",
                    "headers": {
                        "x-tyk-override": "tyk-override",
                    }
                }
            }
        }
    ],
    ...
  • version_data.{version-name}.extended_paths.black_list: This section defines methods and paths that will be blocked by Tyk.

An example entry:

    ...
    "black_list": [
        {
            "path": "v1/disallowed/blacklist/literal",
            "method_actions": {
                "GET": {
                    "action": "no_action",
                    "code": 200,
                    "data": "",
                    "headers": {}
                }
            }
        },
        {
            "path": "v1/disallowed/blacklist/{id}",
            "method_actions": {
                "GET": {
                    "action": "reply",
                    "code": 200,
                    "data": "Not allowed buddy",
                    "headers": {
                        "x-tyk-override-test": "tyk-override"
                    }
                }
            }
        }
    ], 
    ...
  • version_data.{version-name}.extended_paths.white_list: This section defines methods and paths that are exclusively allowed through by Tyk. Use this section to define an entire mock API as well as this will force a specific URL structure (and block all other paths) while replying to all requests, therefore never sending any requests upstream.

An example entry:

    ...
    "white_list": [
        {
            "path": "v1/allowed/whitelist/literal",
            "method_actions": {
                "GET": {
                    "action": "no_action",
                    "code": 200,
                    "data": "",
                    "headers": {}
                }
            }
        },
        {
            "path": "v1/allowed/whitelist/reply/{id}",
            "method_actions": {
                "GET": {
                    "action": "reply",
                    "code": 200,
                    "data": "flump",
                    "headers": {
                        "x-tyk-override-test": "tyk-override"
                    }
                }
            }
        },
        {
            "path": "v1/allowed/whitelist/{id}",
            "method_actions": {
                "GET": {
                    "action": "no_action",
                    "code": 200,
                    "data": "",
                    "headers": {}
                }
            }
        },
        {
            "path": "/tyk/rate-limits/",
            "method_actions": {
                "GET": {
                    "action": "no_action",
                    "code": 200,
                    "data": "",
                    "headers": {}
                }
            }
        }
    ], 
    ...

You’ll notice we’ve included the end user rate-limit check URL as a white listed path. If you don’t do this, Tyk will block access to this URL.

  • version_data.{version-name}.extended_paths.cache: If the cache is enabled (see cache_options), then these paths will be cached. Caching is applied on all safe methods (GET, OPTIONS and HEAD). Caching cannot be controlled on a per-method basis.

A sample entry would be:

    ...
    "cache": [
        "widgets/{widgetID}",
        "widgets",
        "foobars/{foobarID}",
        "foobars"
    ], ...
  • version_data.{version-name}.extended_paths.transform and version_data.{version-name}.extended_paths.transform_response: This section determines which paths are to have a template applied to them in order to transform the body data in the request or response to another structure. Currently on JSON body data is supported as an input. However, the template can output to any format, as it uses Golang templates so structure of outbound data is highly configurable.
    ...
    "transform": [
        {
            "path": "widget/{id}",
            "method": "POST"
            "template_data": {
                "template_mode": "file",
                "template_source": "./templates/transform_test.tmpl"
            }
        }
    ], 
    ...

All the settings that apply to request transforms also apply to response transforms.

  • version_data.{version-name}.extended_paths.transform.path: This is the path to apply the template to.

  • version_data.{version-name}.extended_paths.transform.method: This is the method to apply the template to.

  • version_data.{version-name}.extended_paths.transform.template_data.template_mode: Can be either file or blob. Setting this to file will have Tyk try to load the path and parse the template from a file set in template_source. Setting this to blob enables the template to be embedded in the definition, e.g. if Tyk is pulling configurations from a database. Embedded templates must be Base64 encoded strings and placed in the template_source field.

  • version_data.{version-name}.extended_paths.transform.template_data.template_source: The file, or base64-encoded blob that will be used as a template to perform the transformation.

  • version_data.{version-name}.extended_paths.transform_headers and version_data.{version-name}.extended_paths.transform_response_headers: Elements specified in this list will have their headers modified according to the rules set out in the path meta settings. These settings are the same for both request and response headers.

Entries look like this:

    "transform_headers": [
        {
            "delete_headers": ["Content-Type", "authorization"],
            "add_headers": {"x-tyk-test-inject": "new-value"},
            "path": "widgets/{id}",
            "method": "GET"
        }
    ]
  • version_data.{version-name}.extended_paths.transform_headers.delete_headers: Tyk will remove these headers from a request if it is processed.

  • version_data.{version-name}.extended_paths.transform_headers.add_headers: Tyk will add the headers and values specified in this list. Deletions happen before additions, so modifying headers that already exist is possible by specifying the same key in delete and add.

  • version_data.{version-name}.extended_paths.transform_headers.path: The path that the header injection will be applied to.

  • version_data.{version-name}.extended_paths.transform_headers.path: The method for this path that the injection will be applied to.

  • version_data.{version-name}.extended_paths.hard_timeouts: This section enables you to set hard timeouts on a path-by-path basis. For example, if you have a long-running microservice, but do not want to hold up a dependent client should a query take too long, you can enforce a timeout for that path so the requesting client is not held up forever.

    ...
    extended_paths: {
        ...
        hard_timeouts: [
            {
                path: "delay/5",
                method: "GET",
                timeout: 3
            }
        ]
    }
    ...

The path and method properties are the same as all the other extended path middleware settings.

  • version_data.{version-name}.extended_paths.hard_timeouts.timeout: Set this value to the number of seconds that the hard-timeout should respect. Hard timeout can behave strangely, especially with HTTP 1.1 connections where TCP connections stay open, a client will often retry a call if it times out. The way to fix this is to configure the node to use the close_connections setting in its configuration file.

  • version_data.{version-name}.extended_paths.circuit_breakers: This section defines whether a path should act as a circuit breaker against the upstream proxy. Our circuit breaker is threshold-based, so if x% of requests are failing then the circuit is tripped. When the circuit is tripped, then the gateway will stop all inbound requests to that service for a pre-defined period of time (a recovery time-period).

The circuit breaker will also emit an event which you can hook into to perform some corrective or logging action.

The path and method properties are the same as all other extended_path middleware actions

    "circuit_breakers": [
        {
            "path": "get",
            "method": "GET",
            "threshold_percent": 0.5,
            "samples": 5,
            "return_to_service_after": 60
        }
    ]
  • version_data.{version-name}.extended_paths.circuit_breakers.threshold_percent: The threshold to use for triggering an event, in this case it is between 0 and 1, with 1 being 100% of requests.

  • version_data.{version-name}.extended_paths.circuit_breakers.samples: The number of samples to apply the threshold to, so x% of y samples will trip the circuit.

  • version_data.{version-name}.extended_paths.circuit_breakers.return_to_service_after: The number of seconds to take the path offline. Once this time limit is up, the breaker is reset and the service comes back online.

  • version_data.{version-name}.extended_paths.url_rewrites: Tyk has support for rudimentary URL rewrites. This will enable you to modify inbound URLs to ones that your service understands. The URL rewrite section takes a similar form to other extended paths, with a bit of quirk.

Tyk will match the path element. Like any other path in the extended paths section, here you can use wildcards such as widgets/{id} to show that anything should match.

However, it is important to remember that wildcards like this {id} actually get converted to (.*) regexes, and are not extracted, they are thrown away and are ONLY used for matching the path to trigger the middleware.

The transform is handled by the other two options, which can use any valid regex to group parameters:

    "url_rewrites": [
        {
            "path": "virtual/{wildcard1}/{wildcard2}",
            "method": "GET",
            "match_pattern": "virtual/(.*)/(d+)",
            "rewrite_to": "new-path/id/$2/something/$1"
        }
    ]
  • version_data.{version-name}.extended_paths.url_rewrites.match_pattern: This is the match pattern to use to extract parameters from the URL.

  • version_data.{version-name}.extended_paths.url_rewrites.rewrite_to: This is the path structure to rewrite to, use $1, $2, $n to specify which group to reference in the new URL.

  • version_data.{version-name}.extended_paths.virtual: This section specifies the paths that should execute a “virtual” path, for example, execute a blob of JavaScript to perform some kind of function in the API. These can be anything from mock responses to aggregates. See Virtual Endpoints for more details.

  • proxy: The proxy section outlines the actual API proxying functionality. You can define where Tyk should listen, and where Tyk should proxy traffic to.

  • proxy.listen_path: The path to listen on, e.g. /api or /. Any requests coming into the host, on the port that Tyk is configured to run on, that go to this path will have the rules defined in the API Definition applied. Versioning assumes that different versions of an API will live on the same URL structure. If you are using URL-based versioning (e.g. /v1/function, /v2/function/) then it is recommended to set up a separate non-versioned definition for each version as they are essentially separate APIs.

Proxied requests are literal, no re-writing takes place, for example, if a request is sent to the listen path of: /listen-path/widgets/new and the URL to proxy to is http://your.api.com/api/ then the actual request that will land at your service will be: http://your.api.com/api/listen-path/widgets/new.

This behaviour can be circumvented so that the listen_path is stripped from the outgoing request. See the section on strip_listen_path below.

  • proxy.target_url: This defines the target URL that the request should be proxied to if it passes all checks in Tyk.

  • proxy.enable_load_balancing: Set this value to true to have a Tyk node distribute traffic across a list of servers. **Required: ** You must fill in the target_list section.

  • proxy.target_list: A list of upstream targets (can be one or many hosts).

  • proxy.service_discovery: The service discovery section tells Tyk where to find information about the host to proxy to. In a clustered environment this is useful if servers are coming online and offline dynamically with new IP addresses. The service discovery module can pull out the required host data from any service discovery tool that exposes a RESTful endpoint that outputs a JSON object.

    enable_load_balancing: true,
    service_discovery: {
      use_discovery_service: true,
      query_endpoint: "http://127.0.0.1:4001/v2/keys/services/multiobj",
      use_nested_query: true,
      parent_data_path: "node.value",
      data_path: "array.hostname",
      port_data_path: "array.port",
      use_target_list: true,
      cache_timeout: 10
    },
  • proxy.service_discovery.use_discovery_service: Set this to true to enable the discovery module.

  • proxy.service_discovery.query_endpoint: The endpoint to call.

  • proxy.service_discovery.data_path: The namespace of the data path. For example, if your service responds with:

    {
        "action": "get",
        "node": {
            "key": "/services/single",
            "value": "http://httpbin.org:6000",
            "modifiedIndex": 6,
            "createdIndex": 6
        }
    }

Then your name space would be node.value.

  • proxy.service_discovery.use_nested_query: Sometimes the data you are retrieving is nested in another JSON object. For example, this is how Etcd responds with a JSON object as a value key:
    {
        "action": "get",
        "node": {
            "key": "/services/single",
            "value": "{"hostname": "http://httpbin.org", "port": "80"}",
            "modifiedIndex": 6,
            "createdIndex": 6
        }
    }

In this case, the data actually lives within this string-encoded JSON object. So in this case, you set the use_nested_query to true, and use a combination of the data_path and parent_data_path (below)

  • proxy.service_discovery.parent_data_path: This is the namespace of where to find the nested value In the above example, it would be node.value.

You would then change the data_path setting to be hostname.

Tyk will decode the JSON string and then apply the data_path namespace to that object in order to find the value.

  • proxy.service_discovery.port_data_path: In the above nested example, we can see that there is a separate PORT value for the service in the nested JSON. In this case you can set the port_data_path value and Tyk will treat data_path as the hostname and zip them together (this assumes that the hostname element does not end in a slash or resource identifier such as /widgets/).

In the above example, the port_data_path would be port.

  • proxy.service_discovery.target_path: The target path to append to the host:port combination provided by the service discovery engine.

  • proxy.service_discovery.use_target_list: If you are using load_balancing, set this value to true and Tyk will treat the data path as a list and inject it into the target list of your API definition.

  • proxy.service_discovery.cache_timeout: Tyk caches target data from a discovery service. In order to make this dynamic you can set a cache value when the data expires and new data is loaded.

  • proxy.strip_listen_path: By setting this to true, Tyk will attempt to replace the listen-path in the outgoing request with an empty string. This means that in the above scenario where /listen-path/widgets/new and the URL to proxy to is http://your.api.com/api/ becomes http://your.api.com/api/listen-path/widgets/new, actually changes the outgoing request to be: http://your.api.com/api/widgets/new.

  • proxy.check_host_against_uptime_tests: If uptime tests are enabled, Tyk will check the hostname of the outbound request against the downtime list generated by the host checker. If the host is found, then it is skipped.

  • proxy.preserve_host_header: Set to true to preserve the 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.

See Versioning for more details on versioning your APIs.

IP White-listing (Middleware)

  • enable_ip_whitelisting: If set to true, only requests coming from the explicit list of IP addresses (allowed_ips) are allowed through.

  • allowed_ips: A list of strings that defines the IP addresses that are allowed access via Tyk. This list is explicit and wildcards are currently not supported. e.g.:

        ...
        "enable_ip_whitelisting": true,
        "allowed_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14"]
        ...

CORS

It is possible to enable CORS for certain APIs so users can make browser-based requests. The CORS section is added to an API definition as follows:

    "CORS": {
        "enable": true,
        "allowed_origins": [
            "http://foo.com"
        ]
    },

The CORS middleware has many options, these include:

  • CORS.allowed_origins: A list of origin domains to allow access from.

  • CORS.allowed_methods: A list of methods to allow access via.

  • CORS.allowed_headers: Headers that are allowed within a request.

  • CORS.exposed_headers: Headers that are exposed back in the response.

  • CORS.allow_credentials: Whether credentials (cookies) should be allowed.

  • CORS.max_age: Maximum age of credentials.

  • CORS.options_passthrough: Whether OPTIONS requests should pass through to the rest of the middleware. Update in v1.9: If this option is selected, OPTIONS requests will be completely ignored by the Tyk middleware. This means that pre-flight requests generated by web-clients such as SwaggerUI or the Tyk Portal documentation system will be able to test the API using trial keys.

  • enable_jwt: Set JWT as the access method for this API.

  • jwt_signing_method: Either HMAC or RSA - HMAC requires a shared secret while RSA requires a public key to use to verify against. Please see the section on JSON web tokens for more details on how to generate these.

  • jwt_source: Must either be a base64 encoded valid RSA/HMAC key, this key will then be used to validate inbound JWT and throttle them according to the centralised JWT options and fields set in the configuration.

  • jwt_identity_base_field: Identifies the user or identity to be used 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 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.

  • jwt_policy_field_name: The policy ID to apply to the virtual token generated for a JWT.

  • uptime_tests: This section defines the uptime tests to run for this API.

  • uptime_tests.check_list A list of tests to run, takes the form:

    uptime_tests: {
        check_list: [
            {
                "url": "http://google.com/"
            },
            {
                "url": "http://posttestserver.com/post.php?dir=uptime-checker",
                "method": "POST",
                "headers": {
                    "this": "that",
                    "more": "beans"
                },
                "body": "VEhJUyBJUyBBIEJPRFkgT0JKRUNUIFRFWFQNCg0KTW9yZSBzdHVmZiBoZXJl"
            }
        ]
    },

See Uptime Tests for details on how uptime tests work and how to configure them.

  • domain: The domain to bind this API to. Domains can have multiple listen paths, so multiple APIs can be spanned across a domain using different listen_paths, must be a valid domain name, without the protocol section (e.g. http or https).

  • do_not_track: Set this value to true to have traffic for this API completely ignored.