Tyk API Gateway: Complete Setup and Configuration Guide

Introduction to Tyk API Gateway

Tyk API Gateway is an open-source, lightweight, and high-performance API gateway written in Go. It acts as a reverse proxy that sits between your clients and backend services, handling critical concerns like authentication, rate limiting, analytics, transformations, and security. Whether you are exposing a single microservice or managing hundreds of APIs across multiple teams, Tyk provides a unified control plane to govern traffic.

Why Tyk Matters

Modern applications are increasingly composed of distributed services, each exposing its own API. Without a gateway, every service must independently solve the same cross-cutting problems: who is calling, are they allowed, how often, and what did they do. Tyk centralizes these responsibilities, which leads to several concrete benefits:

Security: Centralized authentication via API keys, OAuth2, JWT, OpenID Connect, and mTLS.
Traffic control: Fine-grained rate limiting and quotas per key, per API, or per consumer group.
Observability: Built-in analytics, request logging, and Prometheus integration.
Developer experience: A developer portal for API discovery and self-service key provisioning.
Extensibility: JavaScript middleware and Go plugins for custom request/response transformations.

Architecture Overview

A typical Tyk deployment consists of several components. Understanding how they fit together is essential before you begin installation.

Tyk Gateway: The core proxy engine that handles incoming requests and applies policies.
Tyk Dashboard: A commercial UI for managing APIs, keys, and policies (optional in the open-source edition).
Tyk Pump: A worker that reads analytics from Redis and forwards them to a datastore such as MongoDB, PostgreSQL, or Prometheus.
Redis: Used as the shared state store for keys, rate limit counters, and configuration caching.
Datastore: A persistent store for analytics (MongoDB, PostgreSQL, or InfluxDB).

In the open-source edition, you typically run the Gateway and Pump together with Redis, and manage configuration through JSON or YAML files rather than the Dashboard.

Installing Tyk Gateway

The fastest way to get started is with Docker. This approach gives you a clean, reproducible environment without polluting your host system. The following docker-compose.yml file spins up Redis, the Tyk Gateway, and Tyk Pump with Prometheus as the analytics backend.

Docker Compose Setup

version: "3.8"

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    restart: unless-stopped

  tyk-gateway:
    image: tykio/tyk-gateway:v5.3.0
    ports:
      - "8080:8080"
    depends_on:
      - redis
    volumes:
      - ./tyk.conf:/opt/tyk-gateway/tyk.conf
      - ./apps:/opt/tyk-gateway/apps
    environment:
      - TYK_GW_LISTENPORT=8080
    restart: unless-stopped

  tyk-pump:
    image: tykio/tyk-pump-docker-pub:v1.8.0
    depends_on:
      - redis
      - tyk-gateway
    volumes:
      - ./pump.conf:/opt/tyk-pump/pump.conf
    restart: unless-stopped

Bring the stack up with the following command:

docker-compose up -d

Once running, the Gateway listens on port 8080. You can verify it is healthy by hitting the health endpoint:

curl http://localhost:8080/hello

You should receive a JSON response containing the version and uptime, confirming the Gateway is operational.

Configuring the Gateway

The main configuration file is tyk.conf. This file controls the listener, Redis connection, analytics settings, and global middleware. Below is a minimal but production-aware configuration.

tyk.conf

{
  "listen_port": 8080,
  "secret": "352d20ee67be67f6340b4c0605b044b7",
  "node_secret": "352d20ee67be67f6340b4c0605b044b7",
  "template_path": "/opt/tyk-gateway/templates",
  "tyk_js_path": "/opt/tyk-gateway/js/tyk.js",
  "middleware_path": "/opt/tyk-gateway/middleware",
  "use_db_app_configs": false,
  "app_path": "/opt/tyk-gateway/apps",
  "storage": {
    "type": "redis",
    "host": "redis",
    "port": 6379,
    "username": "",
    "password": "",
    "database": 0,
    "optimisation_max_idle": 2000,
    "optimisation_max_active": 4000
  },
  "enable_analytics": true,
  "analytics_config": {
    "type": "",
    "ignored_ips": [],
    "enable_detailed_recording": false,
    "enable_geo_ip": false,
    "normalise_urls": {
      "enabled": true,
      "normalise_uuids": true,
      "normalise_numbers": true,
      "custom_patterns": []
    }
  },
  "health_check": {
    "enable_health_checks": true,
    "health_check_value_timeouts": 60
  },
  "optimisations_use_async_session_write": true,
  "allow_master_keys": false,
  "policies": {
    "policy_source": "file",
    "policy_record_name": "/opt/tyk-gateway/policies/policies.json"
  },
  "hash_keys": true,
  "close_connections": true,
  "http_server_options": {
    "enable_websockets": true,
    "read_timeout": 30,
    "write_timeout": 30
  }
}

The secret field is the admin API token used to manage the Gateway programmatically. Always change this value in production and store it securely.

Defining Your First API

API definitions in the open-source edition are stored as JSON files in the apps directory. Each file describes one API, including its upstream target, authentication mechanism, and traffic controls. Below is a complete definition that proxies requests to a public test service.

apps/example-api.json

{
  "name": "Example API",
  "slug": "example-api",
  "api_id": "example-api",
  "org_id": "default",
  "use_keyless_access": 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": {
    "auth_header_name": "Authorization",
    "use_certificate": false
  },
  "definition": {
    "location": "header",
    "key": "x-api-version"
  },
  "version_data": {
    "not_versioned": true,
    "versions": {
      "Default": {
        "name": "Default",
        "expires": "",
        "paths": {
          "ignored": [],
          "white_list": [],
          "black_list": []
        }
      }
    }
  },
  "proxy": {
    "listen_path": "/example/",
    "target_url": "https://httpbin.org",
    "strip_listen_path": true,
    "preserve_host_header": false
  },
  "rate_limit": {
    "rate": 10,
    "per": 60,
    "quota_max": 1000,
    "quota_renewal_rate": 3600
  },
  "active": true
}

Key fields to understand:

listen_path is the prefix Tyk matches against incoming requests.
target_url is the upstream service Tyk forwards matched requests to.
strip_listen_path removes the listen path prefix before forwarding.
use_keyless_access set to false requires authentication on every request.
rate_limit defines per-key throttling and quota limits.

After saving the file, reload the Gateway to pick up the new definition:

curl -H "x-tyk-authorization: 352d20ee67be67f6340b4c0605b044b7" \
     -s http://localhost:8080/tyk/reload/group

Authentication and API Keys

Tyk supports multiple authentication modes. The simplest is the standard API key (bearer token) approach. To create a key that grants access to the Example API, send a POST request to the Gateway's admin API.

Creating an API Key

curl -X POST http://localhost:8080/tyk/keys/create \
  -H "x-tyk-authorization: 352d20ee67be67f6340b4c0605b044b7" \
  -H "Content-Type: application/json" \
  -d '{
    "allowance": 1000,
    "rate": 10,
    "per": 60,
    "expires": -1,
    "quota_max": 10000,
    "quota_renewal_rate": 86400,
    "access_rights": {
      "example-api": {
        "api_id": "example-api",
        "api_name": "Example API",
        "versions": ["Default"],
        "allowed_urls": [],
        "limit": null,
        "allowance_scope": ""
      }
    },
    "org_id": "default"
  }'

The response includes a key field. Store this value securely because it is the bearer token your clients will use. To test the authenticated request:

curl -H "Authorization: 352d20ee67be67f6340b4c0605b044b7e" \
     http://localhost:8080/example/get

If the key is valid and within its rate limit, Tyk forwards the request to https://httpbin.org/get and returns the response. If the key is missing or invalid, Tyk responds with a 403 Forbidden JSON error.

Using JWT Authentication

For scenarios where you already issue JWTs from an identity provider, Tyk can validate them directly. Update the API definition to enable JWT mode:

{
  "name": "JWT Protected API",
  "api_id": "jwt-api",
  "org_id": "default",
  "use_keyless_access": false,
  "enable_jwt": true,
  "jwt_signing_method": "rsa",
  "jwt_source": "https://your-idp/.well-known/jwks.json",
  "jwt_identity_base_field": "sub",
  "jwt_policy_field_name": "policy",
  "proxy": {
    "listen_path": "/jwt/",
    "target_url": "https://httpbin.org",
    "strip_listen_path": true
  },
  "active": true
}

The jwt_source can be a JWKS URL, a raw public key, or an HMAC secret depending on your signing method. Tyk validates the signature, checks expiry, and extracts the identity claim to apply the correct policy.

Rate Limiting and Quotas

Rate limiting protects your backends from abuse and noisy neighbors. Tyk distinguishes between two concepts:

Rate limit: The maximum number of requests allowed within a sliding window (for example, 10 requests per 60 seconds).
Quota: A total request budget that resets on a renewal cycle (for example, 10,000 requests per day).

Limits can be applied at three levels: globally on the API definition, per key, or per policy. Policies are reusable templates that bundle rate limits, quotas, and access rights, which is the recommended approach for managing many consumers.

Defining a Policy

{
  "default": {
    "rate": 100,
    "per": 60,
    "quota_max": 10000,
    "quota_renewal_rate": 86400,
    "access_rights": {
      "example-api": {
        "api_id": "example-api",
        "versions": ["Default"]
      }
    },
    "org_id": "default",
    "active": true,
    "name": "Standard Plan",
    "is_inactive": false,
    "tags": ["standard"]
  }
}

Save this file as policies/policies.json and reload the Gateway. When creating keys, reference the policy by ID instead of repeating the limits:

curl -X POST http://localhost:8080/tyk/keys/create \
  -H "x-tyk-authorization: 352d20ee67be67f6340b4c0605b044b7" \
  -H "Content-Type: application/json" \
  -d '{
    "apply_policy_id": "default",
    "org_id": "default"
  }'

Request and Response Transformations

Tyk can modify requests before they reach the upstream and responses before they return to the client. Common use cases include injecting headers, renaming fields, and masking sensitive data. The API definition supports declarative transformations through the transform and transform_response blocks.

Injecting a Header on Every Request

{
  "name": "Transformed API",
  "api_id": "transform-api",
  "org_id": "default",
  "use_keyless_access": true,
  "proxy": {
    "listen_path": "/transform/",
    "target_url": "https://httpbin.org",
    "strip_listen_path": true
  },
  "version_data": {
    "not_versioned": true,
    "versions": {
      "Default": {
        "name": "Default",
        "use_extended_paths": true,
        "extended_paths": {
          "transform": [
            {
              "template_data": {
                "input_type": "empty",
                "template_mode": "blob",
                "enable_session": false,
                "template": "e3sgLkhlYWRlcnMgfX0="
              },
              "path": "/transform/anything",
              "method": "GET",
              "to": "header",
              "from": "request"
            }
          ]
        },
        "paths": {
          "ignored": [],
          "white_list": [],
          "black_list": []
        }
      }
    }
  },
  "active": true
}

For more complex logic, you can write JavaScript middleware that runs inside the Tyk JSVM. The middleware has access to the request object, session state, and configuration, allowing you to implement custom validation or enrichment.

Monitoring and Analytics

Tyk Pump ships with backends for MongoDB, PostgreSQL, InfluxDB, and Prometheus. For infrastructure monitoring, Prometheus is the most common choice because it integrates well with Grafana dashboards.

pump.conf with Prometheus

{
  "analytics_storage_type": "redis",
  "analytics_storage_config": {
    "type": "redis",
    "host": "redis",
    "port": 6379,
    "database": 0
  },
  "purge_delay": 10,
  "pumps": {
    "prometheus": {
      "name": "prometheus",
      "meta": {
        "path": "/metrics",
        "port": 9090
      }
    }
  },
  "uptime_pump_config": {
    "collection_interval": 10
  }
}

With this configuration, Pump exposes a /metrics endpoint on port 9090 that Prometheus can scrape. Key metrics include request counts, latency histograms, error rates, and quota usage. You can build Grafana dashboards on top of these metrics to visualize API health in real time.

Best Practices

Rotate secrets regularly. The Gateway admin secret and Redis password should be stored in a secrets manager and rotated on a schedule.
Use policies over per-key limits. Policies make it easy to update limits for an entire class of consumers without touching individual keys.
Enable key hashing. Set hash_keys: true so that raw API keys are never stored in Redis, reducing risk if Redis is compromised.
Separate Gateway and Pump. In production, run Pump on dedicated instances so analytics processing does not compete with proxy traffic for CPU.
Use health checks. Configure upstream health checks so Tyk can avoid routing traffic to unhealthy backends.
Validate input with request size limits. Set max_request_body_size to prevent oversized payloads from reaching your services.
Version your APIs. Use Tyk's versioning feature to maintain backward compatibility while rolling out breaking changes.
Monitor Redis carefully. Redis is the single point of state; its latency directly affects every proxied request.

Conclusion

Tyk API Gateway provides a powerful, extensible foundation for managing API traffic at any scale. By centralizing authentication, rate limiting, transformations, and analytics, it frees your backend services to focus on business logic rather than infrastructure concerns. Starting with the Docker-based setup shown here, you can progressively adopt more advanced features like JWT validation, custom JavaScript middleware, and Prometheus-backed observability. As your API surface grows, investing in well-structured policies, automated deployments, and proactive monitoring will ensure that your gateway remains a reliable and secure entry point for every consumer of your platform.