Tyk Classic API Definition

Introduction Tyk Classic API

Tyk stores API configurations as JSON objects called API Definitions. If you are using Tyk Dashboard to manage Tyk, then these are stored in either Postgres or MongoDB, as specified in the database settings. On the other hand, if you are using Tyk OSS, these configurations are stored as files in the /apps directory of the Gateway which is located at the default path /opt/tyk-gateway.

An API Definition has many settings and middlewares that influence the way incoming requests are processed.

Below, you will find an example of a Tyk Classic API Definition.

{
  "id": "5a4f1c029764510001dbc3f1",
  "name": "Sales Demo API",
  "slug": "sales-demo-api",
  "api_id": "6b6c9fc301614e607c591e4af785c465",
  "org_id": "580defdbe1d21e0001c67e5c",
  "use_keyless": false,
  "use_oauth2": false,
  "use_openid": false,
  "openid_options": {
    "providers": [],
    "segregate_by_client": false
  },
  "oauth_meta": {
    "allowed_access_types": [],
    "allowed_authorize_types": [],
    "auth_login_redirect": ""
  },
  "auth": {
    "use_param": false,
    "param_name": "",
    "use_cookie": false,
    "cookie_name": "",
    "auth_header_name": "Authorization",
    "use_certificate": false
  },
  "use_basic_auth": false,
  "use_mutual_tls_auth": false,
  "client_certificates": [],
  "upstream_certificates": {},
  "enable_jwt": false,
  "use_standard_auth": true,
  "enable_coprocess_auth": false,
  "jwt_signing_method": "",
  "jwt_source": "",
  "jwt_identity_base_field": "",
  "jwt_client_base_field": "",
  "jwt_policy_field_name": "",
  "notifications": {
    "shared_secret": "",
    "oauth_on_keychange_url": ""
  },
  "enable_signature_checking": false,
  "hmac_allowed_clock_skew": -1,
  "base_identity_provided_by": "",
  "definition": {
    "location": "header",
    "key": "x-api-version"
  },
  "version_data": {
    "not_versioned": true,
    "versions": {
      "Default": {
          "name": "Default",
          "expires": "",
          "paths": {
            "ignored": [],
            "white_list": [],
            "black_list": []
          },
          "use_extended_paths": true,
          "extended_paths": {},
          "global_headers": {},
          "global_headers_remove": [],
          "ignore_endpoint_case": false,
          "global_size_limit": 0,
          "override_target": ""
      }
    }
  },
  "uptime_tests": {
    "check_list": [],
    "config": {
      "expire_utime_after": 0,
      "service_discovery": {
        "use_discovery_service": false,
        "query_endpoint": "",
        "use_nested_query": false,
        "parent_data_path": "",
        "data_path": "",
        "port_data_path": "",
        "target_path": "",
        "use_target_list": false,
        "cache_timeout": 60,
        "endpoint_returns_list": false
      },
      "recheck_wait": 0
    }
  },
  "proxy": {
    "preserve_host_header": false,
    "listen_path": "/6b6c9fc301614e607c591e4af785c465/",
    "target_url": "http://httpbin.org/",
    "strip_listen_path": true,
    "enable_load_balancing": false,
    "target_list": [],
    "check_host_against_uptime_tests": false,
    "service_discovery": {
      "use_discovery_service": false,
      "query_endpoint": "",
      "use_nested_query": false,
      "parent_data_path": "",
      "data_path": "",
      "port_data_path": "",
      "target_path": "",
      "use_target_list": false,
      "cache_timeout": 0,
      "endpoint_returns_list": false
    },
    "transport": {
      "proxy_url": "http(s)://proxy.url:1234",
      "ssl_min_version": int,
      "ssl_ciphers": ["string"],
      "ssl_insecure_skip_verify": bool
    }
  },
  "disable_rate_limit": false,
  "disable_quota": false,
  "custom_middleware": {
    "pre": [],
    "post": [],
    "post_key_auth": [],
    "auth_check": {
      "name": "",
      "path": "",
      "require_session": false
    },
    "response": [],
    "driver": "",
    "id_extractor": {
      "extract_from": "",
      "extract_with": "",
      "extractor_config": {}
    }
  },
  "custom_middleware_bundle": "",
  "cache_options": {
    "cache_timeout": 60,
    "enable_cache": true,
    "cache_all_safe_requests": false,
    "cache_response_codes": [],
    "enable_upstream_cache_control": false
  },
  "session_lifetime": 0,
  "active": true,
  "auth_provider": {
    "name": "",
    "storage_engine": "",
    "meta": {}
  },
  "session_provider": {
    "name": "",
    "storage_engine": "",
    "meta": {}
  },
  "event_handlers": {
    "events": {}
  },
  "enable_batch_request_support": false,
  "enable_ip_whitelisting": false,
  "allowed_ips": [],
  "dont_set_quota_on_create": false,
  "expire_analytics_after": 0,
  "response_processors": [],
  "CORS": {
    "enable": false,
    "allowed_origins": [],
    "allowed_methods": [],
    "allowed_headers": [],
    "exposed_headers": [],
    "allow_credentials": false,
    "max_age": 24,
    "options_passthrough": false,
    "debug": false
  },
  "domain": "",
  "do_not_track": false,
  "tags": [],
  "enable_context_vars": false,
  "config_data": {},
  "tag_headers": [],
  "global_rate_limit": {
    "rate": 0,
    "per": 0
  },
  "strip_auth_data": false
}

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 in the Key Management section of the Tyk Gateway API).

• 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 Authorization 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 (SPA) or Mobile apps due to the fact that secrets need to be distributed.

• hmac_allowed_algorithms: From v2.7.5, Tyk supports the following HMAC algorithms: “hmac-sha1", “hmac-sha256”, “hmac-sha384”, “hmac-sha512”. You can limit which ones you want to support with this option. For example, [“hmac-sha256”]

• 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 authorization code to request a new access token.

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

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

  • code - Client can request an authorization 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).

• notifications: When Tyk implements an OAuth2 flow, because it will handle access requests on your behalf once authorization 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 authorization 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.

• strip_auth_data: When set to true, auth related headers will be stripped from requests proxied through the gateway.

• auth_configs: New from v2.9.2 this enables better control with multiple chained authentication mechanisms enabled for an API. Now we can set distinct Headers for different auth modes.

auth_configs example:

{
  "auth_configs": {
    "authToken": {"auth_header_name": "My-Auth-Header-Key"}
    "basic": {"auth_header_name": "My-Basic-Auth-Header-Key"},
    ...
  }
}

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 listed in the examples below for Tyk Gateway and Tyk Operator.

Examples

"CORS": {
  "enable": true,
  "allowed_origins": [
    "http://foo.com"
  ],
  "allowed_methods": [],
  "allowed_headers": [],
  "exposed_headers": [],
  "allow_credentials": false,
  "max_age": 24,
  "options_passthrough": false,
  "debug": false
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin-cors-sample
spec:
  name: httpbin-cors-sample
  use_keyless: true
  protocol: http
  active: true
  proxy:
    target_url: http://httpbin.org
    listen_path: /cors
    strip_listen_path: true
  CORS:
    enable: true
    allowed_origins:
      - "http://foo.com"
    allowed_methods: null
    allowed_headers: null
    exposed_headers: null
    allow_credentials: false
    max_age: 24
    options_passthrough: false
    debug: false

Configuration

The CORS middleware has the following options:

• CORS.allowed_origins: A list of origin domains to allow access from. Wildcards are also supported, e.g. http://*.foo.com

• 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: allow CORS OPTIONS preflight request to be proxied directly to upstream, without authentication and rest of checks. 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. If your service handles CORS natively, then enable this option.

• debug: If set to true, this option produces log files for the CORS middleware.

Fallback values

Always keep in mind that empty arrays will fallback to some sensible defaults. If you want to avoid this, you will have to provide explicit values.

• Fallback values for CORS.allowed_origins: ["*"]
• Fallback values for CORS.allowed_methods: ["GET", "POST", "HEAD"]
• Fallback values for CORS.allowed_headers: ["Origin", "Accept", "Content-Type", "X-Requested-With"]

Custom Analytics Tags using HTTP Headers

tag_headers is a string array of HTTP headers that can be extracted and transformed into analytic tags(statistics aggregated by tag, per hour).

For example if you include X-test-header header in the tag_headers array, then, for each incoming request Tyk will add a x-test-header-<header_value> tag to the list of tags in the request analytic record.

If you are using Tyk Operator please refer to how to setup tag headers with Tyk Operator.

When is it useful?

Example use cases are:

• You need to record additional information from the request into the analytics. When enabling detailed logging, Tyk Gateway records the full request and response objects which consumes a lot of space. Using this config will save you this space and only record this header.

• You wish to track a group of API requests. For example:

  • Show me all API requests where tenant-id=123
  • Show me all API requests where user-group=abc

Tags and aggregated analytics

Tyk Gateway, by default, creates aggregations points for all the tags it records. Since we are making the header name that is recorded part of the tag value, Tyk, will also add an aggregation point for that tag value in the aggregated analytics, i.e. x-test-header-<header_value>.

How to avoid the creation of aggregation analytics?

If you don’t want or need aggregated analytics for the headers you record with tag_headers, it is possible to set Tyk to ignore them, by creating a list of tags to ignore. This is done while writing the recorded aggregated analytics to the data stores. Configure a list of tags that are ignored when writing aggregated analytics to MongoDB. This can be configured for Tyk Pump and MDCB.

Ignore list in Tyk pump

In Tyk Pump config field (tyk_sink.conf or whatever name you chose to use), add the tags you want to ignore, or their prefixes to the ignore_tag_prefix_list field, (root level).

Ignore list in Tyk MDCB

In MDCB deployment, if you use the MDCB component to write the aggregated analytics to the data stores, you need to define the ignore list of headers or their prefixes, in MDCB config field (tyk_sink.conf or whatever name you chose to use), under ignore_tag_prefix_list field, (root level).

Note: the field above is replacing aggregates_ignore_tags which is still working but will eventually be deprecated.

"ignore_tag_prefix_list": [ "x-request-id" ]

How to set up and test tag headers in the dashboard?

1. Open: In the Dashboard, with an API configured, open your API and click on “Advanced Options”.
2. Set up: Navigate down to the Tag Headers section and add X-Team-Name to the list.

3. Test: Using your preferred HTTP client, make a request that includes the X-Team-Name header. For example, with curl run the following:

curl http://tyk-gateway.localhost:8080/basic-open-api/get -H "X-Team-Name: devops-us-1" -vv

4. Check: Navigate back to the Dashboard and select the “Log Browser” option to view the logged requests. Open the request record and in the “Gateway Metadata” section (on the right), you can find the “Tags” attached to our request. There you should see the header and value you sent in the request. You should also see that Tyk Gateway recorded it as a tag.

We can now have Tyk track API requests which contain our business logic!!!

How to setup tag headers with Tyk Operator

To setup tag headers with Tyk Operator add the list of headers to tag to the tag_headers object within the spec field of the API definition resource. An example is given below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
metadata:
  name: httpbin-tag-headers
spec:
  name: httpbin-tag-headers
  use_keyless: true
  protocol: http
  active: true
  tag_headers:
  - Host
  - User-Agent
  proxy:
    target_url: http://httpbin.org
    listen_path: /httpbin-tag-headers
    strip_listen_path: true

In this example we can see that the Host and User-Agent headers exist within the tag_headers array. For each incoming request Tyk will add a host-<header_value> and user-agent-<header_value> tags to the list of tags in the request analytic record.

Events

• event_handlers: This adds the ability to configure an API with event handlers to perform specific actions when an event occurs.

• events: Each event handler that is added to the event_handlers.events section, is mapped by the event type, and then a list of each handler configuration, defined by the handler name and the handler metadata (usually some kind of configurable options for the specific handler)

"event_handlers": {
  "events": {
    "EVENT_NAME": [
      {
        "handler_name": "HANDLER TO USE",
        "handler_meta": {
            ...
        }
      }
  ],
  "EVENT_NAME": [
      {
        "handler_name": "HANDLER TO USE",
        "handler_meta": {
            ...
        }
      }
    ],
  }
}

See Report, Monitor and Trigger Events for more details.

API Definition GraphQL

• graphql: The GraphQL config object.

  • enabled: If it is set to true, it means the API is a GraphQL API. Tyk GraphQL middlewares will be enabled.

  • execution_mode: The mode of a GraphQL API. There are two types: proxyOnly and executionEngine.

    • proxyOnly: There is one single upstream which is a GraphQL API and Tyk proxies it.
    • executionEngine: It lets you to configure your own GraphQL API with multiple data sources. This means that you will compose your own schema.

  • schema: The GraphQL schema of your API is saved in this variable in SDL format.

  • type_field_configurations: A list of configurations used when execution_mode is executionEngine. For your schema, you can set data sources for fields in your types.

    • type_name: A type of the schema that a field of it will be data source configured.

    • field_name: A field of the type that will be data source configured.

    • mapping: Mapping configurations of a field. It is used to map the field in the received data and a field in the schema. It is used to represent a field with a different name in the schema.

      • disabled: If it is false, it means enabled.
      • path: Original name of the field in the received data.

    • data_source: Configuration object of a data source.

      • kind: Kind of the upstream. It can be one of HTTPJSONDataSource, GraphQLDataSource.
      • data_source_config: The details of the data_source.

        • url: URL of the upstream data source like https://swapi.dev/api or it can be another Tyk API which you can set like tyk://<tyk-api-name> or tyk://<tyk-api-id>. Also, you can pass parameters e.g. "/my-path/{{ .arguments.id }}, where id is passed as query variable in a GraphQL request.

        • method: HTTP request method which the upstream server waits for the url e.g. GET, POST, UPDATE, DELETE.

        • body: HTTP request body to send to upstream.

        • headers: HTTP headers to send to upstream.

          • key: Key of the header.
          • value: Value of the header.

          Example:

          [
              {
                  "key": "Authorization",
                  "value": "{{ .request.headers.Authorization }}"
              }                                                
          ]
          

        • default_type_name: The optional variable to define a default type name for the response object. It is useful in case the response might be a Union or Interface type which uses status_code_type_name_mappings. - only valid for HTTPJSONDataSource

        • status_code_type_name_mappings: A list of mappings from http.StatusCode to GraphQL type_name. It can be used when the type_name depends on the response code. - only valid for HTTPJSONDataSource

          • status_code: The HTTP response code to map to type_name.
          • type_name: Type name to be mapped to status_code.

  • playground: Configuration of the playground which is exposed from the Gateway route.

    • enabled: If it is true, it means the playground will be exposed.
    • path: The path where playground will sit e.q. if it is /playground in your API with name composed, you can access to the playground by https://tyk-gateway/composed/playground.

A composed API example is shown below. It composes two different data sources:

1. Countries - GraphQLDataSource
2. People - HTTPJSONDataSource

"graphql": {
  "enabled": true,
  "execution_mode": "executionEngine",
  "schema": "type Country {\n  code: String\n}\n\ntype People {\n  count: Int\n}\n\ntype Query {\n  countries: [Country]\n  people: People\n}\n",
  "type_field_configurations": [
    {
      "type_name": "Query",
      "field_name": "countries",
      "mapping": {
        "disabled": false,
        "path": "countries"
      },
      "data_source": {
        "kind": "GraphQLDataSource",
        "data_source_config": {          
          "url": "https://countries.trevorblades.com/",
          "method": "POST"
        }
      }
    },
    {
      "type_name": "Query",
      "field_name": "people",
      "mapping": {
        "disabled": true,
        "path": ""
      },
      "data_source": {
        "kind": "HTTPJSONDataSource",
        "data_source_config": {          
          "url": "https://swapi.dev/api/people/",
          "method": "GET",
          "body": "",
          "headers": [],
          "default_type_name": "People",
          "status_code_type_name_mappings": [
            {
              "status_code": 200,
              "type_name": ""
            }
          ]
        }
      }
    }
  ],
  "playground": {
    "enabled": true,
    "path": "/playground"
  }
}

JSON Web Tokens (JWT)

• 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 or a url to a resource serving JWK, 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. See Dynamic public key rotation using public JWKs URL for more details on JWKs.

• 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 metadata 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.

Clock Skew

Due to the nature of distrusted systems it is expected that despite best efforts you can end up in a situation with clock skew between the issuing party (An OpenID/OAuth provider) and the validating party (Tyk).

This means that in certain circumstances Tyk would reject requests to an API endpoint secured with JWT with the “Token is not valid yet” error . This occurs due to the clock on the Tyk server being behind the clock on the Identity Provider server even with all servers ntp sync’d from the same ntp server.

You can disable the validation check on 3 claims IssueAt, ExpireAt and NotBefore by adding the following boolean fields to your API definition:

  "enable_jwt": true,
  "jwt_disable_issued_at_validation": true,
  "jwt_disable_expires_at_validation": true,
  "jwt_disable_not_before_validation": true

See JSON Web Tokens for more details.

Other Root Objects

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

• slug: The URL segment that will map to this API, e.g. if set to widgets then the full API URL will be https://your-organization.cloud.tyk.io/widgets.

• 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 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: When used in conjunction with the dashboard, 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.

• session_lifetime_respects_key_expiration: If this is set to true and the key expiration date is less than the session_lifetime, the key expiration value will be set to session_lifetime. Don’t forget that the key expiration is set in unix timestamp but session_lifetime is set in seconds. Also, session_lifetime_respects_key_expiration exists in the global config too. When the global one is set to true, the one set at the API level will be ignored.

• domain: The domain to bind this API to. Multiple APIs can share the same domain, so long as their listen paths are unique. This domain will affect your API only. To set up the portal domain for your organization, please register it in the main Tyk Dashboard settings file. Your Tyk Gateway can listen on multiple domains/subdomains through the use of regular expressions, more precisely the RE2 Syntax. They are defined using the format {name} or {name:pattern}.

  • www.example.com Matches only if domain is www.example.com
  • {subdomain:[a-z]+}.example.com Matches dynamic subdomain
  • {subdomain:foo|bar}.example.com will listen on foo.example.com and bar.example.com"

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

• enable_context_vars: Context variables are extracted from the request at the start of the middleware chain, and must be explicitly enabled in order for them to be made available to your transforms. These values can be very useful for later transformation of request data, for example, in converting a Form-based POST into a JSON-based PUT or to capture an IP address as a header. See Context Variables for more details.

• config_data: You can use the config_data field in your API definition to pass custom attributes to middleware via a virtual endpoint. See Virtual Endpoints for more details.

• tag_headers: This specifies a string array of HTTP headers values which turned into tags. For example, if you include the X-Request-ID header to tag_headers, for each incoming request it will include an x-request-id-<header_value> tag to request an analytic record. This functionality can be useful if you need analytics for request headers without the body content (Enabling detailed logging is another option, but it records the full request and response objects and consumes a lot more space). Check the page custom Analytics Tags using HTTP Headers for more important information.

• ignore_endpoint_case: New for v2.9.4. If set to true the case of a call to endpoints for this API will be ignored. So for an endpoint called getuser all the following calls will be allowed:

  • getuser
  • getUser
  • GetUser

If set to true, this will override ignoring the case for a particular endpoint with the Ignore and Allowlist plugins. This setting can be overriden at a “global” Tyk level by setting ignore_endpoint_case to true in your tyk.conf file. See ignore_endpoint_case for details.

Proxy Transport Settings

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

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.

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 behavior 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.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.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.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.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.disable_strip_slash

This boolean option allows you to add a way to disable the stripping of the slash suffix from a URL.

Internal proxy setup

The transport section allows you to specify a custom proxy and set the minimum TLS versions and any SSL ciphers.

This is an example of proxy.transport definition followed by explanations for every field.

{
  "transport": {
    "proxy_url": "http(s)://proxy.url:1234",
    "ssl_min_version": 771,
    "ssl_ciphers": [
      "TLS_RSA_WITH_AES_128_GCM_SHA256", 
      "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"
    ],
    "ssl_insecure_skip_verify": true,
    "ssl_force_common_name_check": false
  }
}

proxy.transport.proxy_url

Use this setting to specify your custom forward proxy and port.

proxy.transport.ssl_min_version

Use this setting to specify your minimum TLS version:

  You need to use the following values for this setting:

proxy.transport.ssl_ciphers

You can 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

proxy.transport.ssl_insecure_skip_verify

Boolean flag to control at the API definition whether it is possible to use self-signed certs for some APIs, and actual certs for others. This also works for TykMakeHttpRequest & TykMakeBatchRequest in virtual endpoints.

proxy.transport.ssl_force_common_name_check

Use this setting to force the validation of a hostname against the certificate Common Name.

API Level Rate Limits

• global_rate_limit: This specifies a global API rate limit in the following format: {"rate": 10, "per": 1}, similar to policies or keys.

The API rate limit is an aggregate value across all users, which works in parallel with user rate limits, but has higher priority.

• disable_rate_limit: Is set to true, rate limits are disabled for the specified API.

See Rate Limiting for more details including setting via the Dashboard.

Uptime Tests

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

IP Allowlist (Middleware)

• enable_ip_whitelisting: Enables IPs allowlist¹ . When set to true, only requests coming from the explicit list of IP addresses defined in (allowed_ips) are allowed through.

• allowed_ips: A list of strings that defines the IP addresses (in CIDR notation) 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"]
...
}

For more details on CIDR notation, see this Wikipedia entry.

Tyk Operator

Please consult the Tyk Operator supporting documentation for an example of how to configure an IP allow list with Tyk Operator.

IP Blocklist (Middleware)

• enable_ip_blacklisting: Enables IPs blocklist² . If set to true, requests coming from the explicit list of IP addresses (blacklisted_ips) are not allowed through.

• blacklisted_ips: A list of strings that defines the IP addresses (in CIDR notation) that are blocked access via Tyk. This list is explicit and wildcards are currently not supported. e.g.:

...
"enable_ip_blacklisting": true,
"blacklisted_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14"]
...

For more details on CIDR notation, see this Wikipedia entry.

²

Tyk Operator

Please consult the Tyk Operator supporting documentation for an example of how to configure an IP block list with Tyk Operator.