From Tyk 5.14.0, the recommended replacement for third-party OAuth integration is the [OAuth 2.0 (External IdP)](/docs/api-management/authentication/oauth2-authentication) scheme, which provides token validation, scope enforcement, Protected Resource Metadata, and token exchange in a single declaration. If you are on an earlier version, use the [JSON Web Token (JWT)](/docs/basic-config-and-security/security/authentication-authorization/json-web-tokens) middleware as an interim replacement.
The remainder of this section is left for reference and is not maintained.
For integration with a third-party OIDC provider we recommend using the JSON Web Token (JWT) middleware which is described [above](/docs/basic-config-and-security/security/authentication-authorization/json-web-tokens), which offers the same functionality with a more streamlined setup and reduced risk of misconfiguration.
The remainder of this section is left for reference and is not maintained.
Now that we have Users service running on port `4000` and Reviews service running on port `4001` let's see how we can combine these two into one single UDG API in following tutorial. ### Creating Schema 1. Create API To start with a Universal Data Graph from scratch head over to the dashboard and click on “APIs” in the left menu. Then click the `“Add New API”` and `UDG`. You might want to give your Universal Data Graph an individual name (i.e. `User-Reviews-Demo`) 2. Set Authentication To get started easily we'll set the API to `Keyless(Open)`. To do this, scroll down to the Authentication section.
Now if we try to query our UDG API it should error at this moment as we do not have any data-source attached to it, let's see how we can do that in next section. ### Connect Datasource Upon navigating to schema tab on API details page you’ll see a split screen view with schema and user interface for available fields to configure the datasource. You can attach datasource to each individual field and can also re-use the datasource for multiple fields for performance benefits in case it has similar configuration (it needs to use the same upstream URL and method). We will start with attaching datasource to user query using following approach. #### 1. Select field to attach datasource. Upon selecting the `Users` field on type `Query`, you'll see the options to configure that field for following kinds of datasources. * REST * GraphQL * Kafka #### 2. Select datasource type. Since our upstream services are REST, we'll select REST as datasource type but other kind of datasources can be used as well: * *Use external data source*: Will allow to configure the field to resolve with the external API (outside Tyk environment) * *Using exiting APIs*: Which will allow to configure the field with the API that already exists in Tyk environment. * *Re-use already configured data source*: If you already have configured a data source for the same API you can re-use the same data-source. If the data source is reused the endpoint will only be called once by Tyk. You can learn more about it [here](#udg) #### 3. Configure datasource details. Configure the data source with the following fields **Name** Enter a unique datasource name configuration to reuse it in the future. We will name this as `getUserById` for the given example. When configuring a datasource name with Tyk Dashboard, a default name is created automatically by concatenating the field name and the GraphQL type name with an underscore symbol in between. For example, *getUserById\_Query*. This name is editable and can be changed by the user. **URL** We will use the URL for our `Users` service which returns details of an user for given `id` i.e `http://localhost:4000/users/:id`. To dynamically inject the `id` for every request made, we can use templating syntax and inject `id` with user supplied argument or we can also use session object. To avoid typos in template you can use the UI component to automatically create a template for you. You can select from the available argument and object template options from the list generated by input component which is triggered by entering `{` in input. To learn more about arguments click [here](#arguments) To learn more about reusing response fields click [here](#reusing-response-fields) #### 4. Enter datasource name. Enter a unique datasource name your configuration to reuse it in the future. We will name this as `getUserById` for the given example #### 5. Select HTTP method for the URL. You can select the HTTP method for your upstream url. Which should be `GET` in our case. #### 6. Add headers (Optional) If you upstream expects headers, you can supply them using this. You can also use templating syntax here to reuse request headers. #### 7. Select field mapping Keep the field mapping disabled by default. You can use field mapping to map the API response with your schema. You can learn more about field mapping [here](#field-mappings) #### 8. Save data source It is important to save the datasource configuration in order to reflect the changes in your API definition. The`“Save & Update API”`button will persist the full API definition. #### 9. Update API and Test Click Update the API. You can now query your UDG API of `user` using the Playground tab in API designer ```gql theme={null} query getUser { user(id:"1"){ username id reviews { id text user { id } } } } ``` The above query should return the response as follows ```json theme={null} { "data": { "user": { "username": "John Doe", "id": "1", "reviews": null } } } ``` #### Challenge 1. Try to resolve `reviews` field on type `Users` 2. Try to resolve `users` field on type `Reviews` As you can see our query resolved for user details but returns `null` for `reviews`. This happens because we haven't defined datasource on field level for `reviews` on type `User`. ``` Notes - For reviews field on type User - - Description :: get reviews by userId - - URL :: http://localhost:4001/reviews/:userId - - Method :: GET - For users field on type Review - - Description :: get user details by Id - - URL :: http://localhost:4000/users/:userId - - Method :: GET - You can reuse response filed using templating syntax example `{{.object.id}}` ```
Now that we have linked datasources for our queries, let's see how we can do the same for mutations in the next section. ### Mutations Now that we have attached datasources to our `Query` in the schema let's try to do the same for `Mutation`. #### Steps for Configuration 1. **Update Schema** ```gql theme={null} type Mutation { addReview(text: String, userId: String): Review deletReview(reviewId: String): String } ``` We’ll update the Mutatation type as above where we’ll add two operations * `addReview`: Which accepts two `arguments` (i.e `text` and `userId`) and adds a new review by making a `POST` request to `http://localhost:4001/reviews` endpoint, which expects something like the following in the request payload ``` { "id": "1", // UserId of the user posting review "text": "New Review by John Doe11" // review text } ``` * `deleteReview`: Which accepts one `argument` (i.e `reviewId`), that deletes a review by making a `DELETE` request to `http://localhost:4001/reviews/:reviewId` 2. **Configure datasource.** Follow these steps to configure a data source for the `Mutation`. * Navigate to schema tab in the api where you would see the split screen view of schema editor on left and list of configurable fields on right * Select `addReview` field from `Mutation` type * Select `REST` option * Set a unique datasource name * Set the URL as `http://localhost:4001/reviews` * Select method type as `POST` * Set request body to relay the graphql arguments to our upstream payload as follows: ``` { "text": "{{.arguments.text}}", "userId": "{{.arguments.userId}}" } ``` * Update the API 3. **Execute mutation operation** We can now test our mutation operation with the playground in API designer using the following operation ```gql theme={null} mutation AddReview { addReview(text: "review using udg", userId:"1"){ id text } } ``` That should return us the following response: ```gql theme={null} { "data": { "addReview": { "id": "e201e6f3-b582-4772-b95a-d25199b4ab82", "text": "review using udg" } } } ``` #### Challenge Configure a datasource to delete a review using review id. ``` Notes - For users field on type Review - - Description :: delete review using reviewId - - URL :: http://localhost:4001/reviews/:reviewId - - Method :: DELETE - Enable field mapping to map your API response ```
Now that we have a good idea how we could do CRUD operations with UDG APIs, let's see how we can secure them using policies ### Security Due to the nature of graphql, clients can craft complex or large queries which can cause your upstream APIs to go down or have performance issues. Some of the common strategies to mitigate these risks include * Rate limiting * Throttling * Query depth limiting For this tutorial we'll mitigate these risks using `Query Depth Limit` but you can also use common strategies like rate limiting and throttling, which you can read more about [here](/docs/api-management/rate-limit) #### Steps for Configuration 1. **Set authentication mode** In you Api designer core settings tab scroll down to Authentication section and set the authentication mode `Authentication Token` and update the API. Our API is not open and keyless anymore and would need appropriate Authentication token to execute queries. 2. **Applying to query depth** Currently if users want they could run queries with unlimited depth as follows ```gql theme={null} query getUser { user(id: "1") { reviews { user { reviews { user { reviews { user { reviews { user { id } } } } } } } } } } ``` To avoid these kind of scenarios we will set query depth limit on the keys created to access this API. Although we can directly create keys by selecting this API but we'll use a Policy as it will make it easier to update keys for this API in future. You can read more about Policies [here](/docs/api-management/policies) **Create Policy** * Navigate to policies page * Click Add Policy * Select our API from Access Rights table * Expand `Global Limits and Quota` section * Unselect `Unlimited Query Depth` and set limit to `5` * Switch to configuration tab * Set policy name (eg. user-reviews-policy) * Set expiration date for the keys that would be created using this policy * Click on create policy **Create a key using above policy** * Navigate to keys page * Click Add Key * Select our newly created policy * Click create key * Copy the key ID Now if you try to query our UDG API using the key you should see an error as follows ```json theme={null} { "error": "depth limit exceeded" } ```
`"url": "resource URL"`
`}` | The fetched document can be an OpenAPI or AsyncAPI document. The format will be detected automatically. The data source import API only checks the fetched data and tries to determine the document format, the status codes are ignored. It returns an error if it fails to determine the format and the document type. HTTP 500 is returned if a programming or network error occurs. If the fetched request body is malformed then HTTP 400 is returned. ### Import an OpenAPI document The data source import API supports importing OpenAPI documents. The document can be used as a request body. | **Property** | **Description** | | :- | :- | | Resource URL | `/api/data-graphs/data-sources/import` | | Method | `POST` | | Content-Type | `application/vnd.tyk.udg.v2.openapi` | | Body | `
For Tyk Gateway to protect and [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) calls to your upstream service, you need to configure an API on Tyk Gateway. The minimum information that Tyk requires is the **listen path** (which is a path on the Tyk Gateway URL that you want your consumers to call) and your **API URL** (which is the URL of your service to which Tyk should forward requests).
This information and other configuration values are stored in an object called a *Tyk API Definition*. Once you have created your Tyk API Definition and deployed it in the Gateway, Tyk can start serving your consumers, forwarding their requests to your upstream service's API. To reach a detailed guide to creating Tyk API Definitions, please choose the tab for the product you are using: ### Tyk Cloud Tyk Cloud is a fully managed service that makes it easy for API teams to create, secure, publish and maintain APIs at any scale, anywhere in the world. Tyk Cloud includes everything you need to manage your global API ecosystem: [Tyk Gateways](/docs/tyk-oss-gateway), [Tyk Dashboard](/docs/api-management/dashboard-configuration), [Tyk Developer Portal](/docs/portal/overview/intro) and [Universal Data Graph](/docs/api-management/data-graph#overview).
To embark on your API journey with Tyk Cloud, we recommend going to our [Quick Start guide](/docs/tyk-cloud#quick-start-tyk-cloud). This guide will walk you through the process of creating your very first API in Tyk Cloud. For an advanced step by step guide we recommend visiting our [Getting Started guide](/docs/tyk-cloud#comprehensive-tyk-cloud-setup). This will explain advanced configuration steps relating to how to distribute your API across nodes, in addition to adding and testing your API. ### Tyk Self-Managed
-
* `message` (string): a human readable message from Tyk Gateway that adds detail about the event * `cert_id` (string): the certificate ID * `cert_name` (string): the name of the certificate * `expires_at` (string, RFC3339): the certificate expiry date * `days_remaining` (integer): the remaining days until the certificate expires * `api_id`(string): the ID of the API that triggered the event -
* `message` (string): a human readable message from Tyk Gateway that adds detail about the event * `cert_id` (string): the certificate ID * `cert_name` (string): the name of the certificate * `expired_at` (string, RFC3339): the date when the certificate expired * `days_since_expiry` (integer): the number of days since the certificate expired * `api_id`(string): the ID of the API that triggered the event
If you're using Tyk OAS APIs, then you can find details and examples of how to configure webhook event handlers [here](/docs/api-management/gateway-events#webhook-event-handlers-with-tyk-oas-apis). If you're using Tyk Classic APIs, then you can find details and examples of how to configure webhook event handlers [here](/docs/api-management/gateway-events#webhook-event-handlers-with-tyk-classic-apis). ### Webhook event handlers with Tyk OAS APIs [Webhooks](/docs/api-management/gateway-events#event-handling-with-webhooks) are event handlers that can be registered against API Events. The webhook will be triggered when the corresponding event is fired and will send a customizable fixed payload to any open endpoint. Webhooks are configured in the [Tyk OAS API Definition](/docs/api-management/gateway-config-tyk-oas#operation). You can do this via the Tyk Dashboard API or in the API Designer. If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic](/docs/api-management/gateway-events#webhook-event-handlers-with-tyk-classic-apis) page. #### Set up a webhook event handler in the Tyk OAS API Definition Event handling is configured by adding the `eventHandlers` object to the `server` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition. The `eventHandlers` object is an array containing configurations for all event handlers registered with the API. ##### Local webhook configuration When using a local webhook, the event handler element in the `eventHandlers` object has the following configuration which fully declares the webhook behaviour: * `enabled`: enable the event handler * `trigger`: the API event that will trigger the webhook * `type`: the type of event handler, in this case should be set to `webhook` * `cooldownPeriod`: the [webhook cooldown](/docs/api-management/gateway-events#webhook-cooldown) for duplicate events (in duration format, e.g. 10s, 1m30s); use this to prevent flooding of the target endpoint when multiple events are fired in quick succession * `name`: a human readable name for the webhook, which will be displayed in Tyk Dashboard * `url`: this is an **absolute URL** to which the request will be sent * `method`: this can be any of `GET`, `PUT`, `POST`, `PATCH` or `DELETE` and will be the HTTP method used to send the request; methods that do not support an encoded request body will not have the event metadata provided with the request; we advise using `POST` where possible * `bodyTemplate`: this is the path to the [webhook template](/docs/api-management/gateway-events#webhook-payload) that will be used to construct the request body * `headers`: a map of custom headers to be provided with the request For example: ```json {hl_lines=["18-33"],linenos=true, linenostart=1} theme={null} { "info": { "title": "example-local-webhook", "version": "1.0.0" }, "openapi": "3.0.3", "paths": {}, "components": {}, "x-tyk-api-gateway": { "info": { "name": "example-local-webhook", "state": { "active": true } }, "server": { "eventHandlers": [ { "enabled": true, "trigger": "RatelimitExceeded", "cooldownPeriod": "1s", "type": "webhook", "name": "My local webhook", "url": "https://webhook.site/
If the global webhook is subsequently deleted from the Tyk Dashboard, the webhook will automatically be converted to a local webhook in any API definition that was using it.
`kubectl delete deployment.apps/mdcb-tyk-cp-tyk-pro -n tyk` 8. Now there's no connection from the data placne to the control plane, but try hitting the API endpoint on either Data Plane Gateway and you’ll see that they continue serving your users' requests regardless of their isolation from the Control Plane. 9. Back on the Tyk Dashboard make some changes - for example, re-enable Authentication on your API, add a second API. Verify that these changes **do not** propagate through to the Data Plane Gateways. 10. Now we’ll bring MDCB back online with this command:
`./up.sh -r redis-cluster -e load-balancer tyk-cp` 11. Now try hitting the original API endpoint from the Data Planes - you’ll find that you need the Authorization key again because MDCB has updated the Data Planes with the new config from the Control Plane. 12. Now try hitting the new API endpoint - this will also have automatically been propagated out to the Data Planes when MDCB came back up and so is now available for your users to consume. Pretty cool, huh? There’s a lot more that you could do - for example by deploying real APIs (after all, this is a real Tyk deployment) and configuring different Organisation Ids for each Data Plane to control which APIs propagate to which Gateways (allowing you to ensure data localisation, as required by the Acme Global Bank). ### Closing everything down We’ve provided a simple script to tear down the demo as follows: 1. `./down.sh -n tyk-worker-us` 2. `./down.sh -n tyk-worker-eu` 3. `./down.sh` **Don’t forget to tear down your clusters in GCP if you no longer need them!** ## MDCB Synchroniser ### Overview Data Plane Gateways need resources such as API keys, certificates, and OAuth clients to process API requests. To ensure high availability and resilience, these resources need to be synchronized from the Control Plane to the Data Planes. The MDCB Synchroniser is a feature that proactively pushes these resources to the Data Planes when they start up. This improves resilience if the MDCB link or the Control Plane is unavailable, as the Data Planes can continue to operate independently using the resources stored locally in their Redis instances. It also offers a performance improvement, as Gateways do not have to retrieve resources on demand when an API is first called.
in stream participant KafkaJobs as Kafka
topic **jobs** participant Worker as Worker
Worker stream participant KafkaCompleted as Kafka
topic **completed** participant GatewayOut as Gateway
out stream %% synchronous request from client Client ->> GatewayIn: POST /push-event **(sync)** GatewayIn -->> Client: 200 OK + echo **(sync)** %% asynchronous event flow GatewayIn -->> KafkaJobs: publish event **(async)** KafkaJobs -->> Worker: consume job **(async)** Worker -->> KafkaCompleted: publish result **(async)** KafkaCompleted -->> GatewayOut: consume result **(async)** %% synchronous delivery back to the same user GatewayOut ->> Client: GET /get-event / WS / SSE **(sync)** ``` ### Stream-per-responsibility pattern | Stream | Role | Input | Output | | :- | :- | :- | :- | | **`in`** | Edge entrypoint: accepts HTTP, enriches payload (`user_id`, `job_id`), publishes to **`jobs`** and echoes to caller | HTTP | Kafka + sync response | | **`Worker`** | Background micro-service: listens to **`jobs`**, attaches `result: "bar"`, publishes to **`completed`** | Kafka | Kafka | | **`out`** | Edge exit point: listens to **`completed`**, drops messages not owned by caller, delivers via REST/WS/SSE | Kafka | HTTP | *** ## Processor mapping (built-in scripting) Streams pipelines include **processors**. The *mapping* processor embeds [Bloblang](https://www.benthos.dev/docs/guides/bloblang/about/) so you can transform or filter messages inline: * **Enrich** – `in` adds `user_id` & `job_id` * **Augment** – `Worker` adds a static field `{ "result": "bar" }` * **Filter** – `out` calls `deleted()` for non-matching users Dynamic placeholders (`$tyk_context.…`) can reference query params, headers, JWT claims, or any other context variable—usable anywhere in the Streams config. *** ## Observability (optional) Uncomment the `metrics:` and `tracer:` blocks to push per-stream Prometheus metrics and Jaeger traces. Tags like `stream: Worker` make end-to-end tracing trivial. *** ## Full OpenAPI definition Copy/paste into `streams-demo.yaml`, import via Dashboard UI, or apply with Tyk Operator: ```yaml theme={null} info: title: streams-demo version: 1.0.0 openapi: 3.0.3 servers: - url: http://tyk-gateway:8282/stream-demo/ x-tyk-streaming: streams: Worker: input: kafka: addresses: - localhost:9093 consumer_group: worker topics: - jobs output: kafka: addresses: - localhost:9093 topic: completed pipeline: processors: - mapping: | root = this.merge({ "result": "bar" }) # metrics: # prometheus: # push_interval: 1s # push_job_name: Worker # push_url: http://localhost:9091 # tracer: # jaeger: # collector_url: http://localhost:14268/api/traces # tags: # stream: Worker in: input: http_server: path: /push-event ws_path: /ws-out output: broker: outputs: - kafka: addresses: - localhost:9093 topic: jobs - sync_response: {} pipeline: processors: - mapping: | root = this root.user_id = "$tyk_context.request_data_user" # or $tyk_context.jwt.claims.sub root.job_id = uuid_v4() # tracer: # jaeger: # collector_url: http://localhost:14268/api/traces # tags: # stream: in # metrics: # prometheus: # push_interval: 1s # push_job_name: in # push_url: http://localhost:9091 out: input: kafka: addresses: - localhost:9093 consumer_group: $tyk_context.request_data_user topics: - completed output: http_server: path: /get-event ws_path: /ws-in pipeline: processors: - mapping: | root = if this.user_id != "$tyk_context.request_data_user" { deleted() } # tracer: # jaeger: # collector_url: http://localhost:14268/api/traces # tags: # stream: out # metrics: # prometheus: # push_interval: 1s # push_job_name: out # push_url: http://localhost:9091 security: [] paths: {} components: securitySchemes: {} x-tyk-api-gateway: info: name: stream-demo state: active: true internal: false middleware: global: contextVariables: enabled: true trafficLogs: enabled: true server: listenPath: strip: true value: /stream-demo/ upstream: proxy: enabled: false url: "" ``` *** ## Running the demo 1. **Start Kafka** (e.g. docker-compose). 2. **Launch Tyk Gateway 5.8+** with the YAML above. 3. **Send an event** ```bash theme={null} curl -X POST "http://localhost:8282/stream-demo/push-event?user=alice" \ -H "Content-Type: application/json" \ -d '{"message":"hello world"}' ``` 4. **Receive the result** (only *alice*’s jobs) ```bash theme={null} curl "http://localhost:8282/stream-demo/get-event?user=alice" ``` 5. **Switch transport** – connect via websocket `wscat -c http://127.0.0.1:8282/stream-demo/ws-in\?user\=alice` 6. *(Optional)* **Enable metrics & tracing** – uncomment blocks, restart Gateway, explore in Grafana & Jaeger. # Tyk Pump Source: https://tyk.io/docs/api-management/tyk-pump Install and configure Tyk Pump, the component that moves analytics data out of Redis to persistent database and external systems. ## What Is Tyk Pump? Tyk Gateway writes a [traffic log](/docs/api-management/logs/traffic-logs), a structured record of the request and response, for every API call it processes, into Redis. Redis is a temporary, high-throughput buffer, not a long-term store, so something has to move those traffic logs out before they expire. Tyk Pump is the [open source](https://github.com/TykTechnologies/tyk-pump) component that does this. It reads traffic logs out of Redis and writes them to one or more configured destinations, which Tyk calls pumps. Each pump has a type, such as `mongo` or `sql`, from the [Pump Type Catalog](#pump-type-catalog) below: depending on the type, it can forward traffic logs unaltered, or compute aggregated analytics or metrics from them. A single Tyk Pump process can run several pumps at once, so the same traffic data can be sent to multiple destinations in parallel.
Don’t hesitate to contact us for assistance
- Rate Limiting
- Authentication
- API Versioning
- Granular Access Control
- GraphQL
- and [much more](/docs/tyk-open-source)
e.g., API Key] Auth1 --> Auth2[Authentication Method 2
e.g., Basic Auth] Auth2 --> Auth3[Authentication Method N
e.g., JWT] Auth3 --> SessionCreation[Create Session
& Apply Policies] SessionCreation --> AccessDecision{Access
Decision} end AccessDecision -->|Granted| Upstream[(Upstream
API)] AccessDecision -->|Denied| Reject[Reject Request] %% Styling classDef client fill:#f9f9f9,stroke:#333,stroke-width:2px classDef gateway fill:#d4edda,stroke:#28a745,stroke-width:2px classDef auth fill:#e2f0fb,stroke:#0275d8,stroke-width:1px classDef session fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px classDef decision fill:#cce5ff,stroke:#0275d8,stroke-width:2px classDef upstream fill:#f8f9fa,stroke:#6c757d,stroke-width:2px classDef reject fill:#f8d7da,stroke:#dc3545,stroke-width:2px class Client client class Gateway gateway class Auth1,Auth2,Auth3 auth class SessionCreation session class AccessDecision decision class Upstream upstream class Reject reject ``` ## Use Cases * **Multi-tenant APIs**: Different tenants using different identity providers * **Migration scenarios**: Supporting both legacy and modern auth during transitions * **Partner integrations**: External partners use mTLS while internal users use JWT * **Mobile + Web**: Different auth methods for different client types ## Understanding Authentication Modes ```mermaid theme={null} graph LR Client([Client]) -->|Request| Gateway[Tyk Gateway] subgraph "Tyk Multiple Authentication" Gateway --> AuthConfig{Authentication
Configuration} %% Legacy Mode AuthConfig -->|Legacy Mode| LegacyAuth["AND Logic
(All must pass)"] LegacyAuth --> Auth1[Auth Method 1] Auth1 --> Auth2[Auth Method 2] Auth2 --> SessionCreation["Create Session
(from BaseIdentityProvider)"] %% Compliant Mode AuthConfig -->|Compliant Mode| CompliantAuth["OR Logic
(Any group can pass)"] CompliantAuth --> Group1["Group 1
(AND Logic)"] CompliantAuth --> Group2["Group 2
(AND Logic)"] Group1 --> G1Auth1["Auth Method A"] G1Auth1 --> G1Auth2["Auth Method B"] Group2 --> G2Auth1["Auth Method C"] G2Auth1 --> G2Auth2["Auth Method D"] G1Auth2 --> DynamicSession1["Create Session
(from last auth in group)"] G2Auth2 --> DynamicSession2["Create Session
(from last auth in group)"] SessionCreation --> AccessDecision DynamicSession1 --> AccessDecision DynamicSession2 --> AccessDecision AccessDecision{Access
Decision} end AccessDecision -->|Granted| Upstream[(Upstream
API)] AccessDecision -->|Denied| Reject[Reject Request] %% Styling classDef client fill:#f9f9f9,stroke:#333,stroke-width:2px classDef gateway fill:#d4edda,stroke:#28a745,stroke-width:2px classDef auth fill:#e2f0fb,stroke:#0275d8,stroke-width:1px classDef group fill:#fff3cd,stroke:#ffc107,stroke-width:1px classDef session fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px classDef decision fill:#cce5ff,stroke:#0275d8,stroke-width:2px classDef upstream fill:#f8f9fa,stroke:#6c757d,stroke-width:2px classDef reject fill:#f8d7da,stroke:#dc3545,stroke-width:2px class Client client class Gateway gateway class Auth1,Auth2,G1Auth1,G1Auth2,G2Auth1,G2Auth2,LegacyAuth,CompliantAuth auth class Group1,Group2 group class SessionCreation,DynamicSession1,DynamicSession2 session class AuthConfig,AccessDecision decision class Upstream upstream class Reject reject ``` Tyk OAS offers two modes for configuring multiple authentication methods: * **Legacy Mode** (Default): Maintains backward compatibility with existing Tyk implementations using AND logic only * **Compliant Mode**: Introduced in 5.10.0, provides enhanced flexibility by supporting both AND and OR logic between authentication methods
``` 3. **Create the new page:** The content is organized into folders under the root directory, reflecting the website's navigation structure (tabs, groups, etc.). Choose the appropriate folder for your new page. * Create a new `.mdx` file for the page. For example, for a page titled “API Versioning” you might create a file named `api-versioning.mdx`. * Add [front matter](https://mintlify.com/docs/pages#frontmatter) to the top of the file. This is a YAML block containing metadata like the title, description, and tags. **Example front matter:** ```mdx theme={null} --- title: "API Versioning" description: "Create and manage multiple versions of an API" sidebarTitle: "API Versioning" tags: ['API versioning', 'version', 'Tyk Classic', 'Tyk OAS', 'API', 'versioning'] ---
``` 6. **Create a pull request** on GitHub to merge your changes into `main`. Once the PR is opened, a series of automated checks will run: * Link Check: Mintlify checks for broken internal links. * Spell Check: A vale-spellcheck ensures content quality. * Documentation Validation: A custom script checks for things like missing images and redirect conflicts. 7. **Preview your changes** using the link provided by Mintlify before merging. **For Contributors Outside Tyk:** A Tyk team member will need to approve the Mintlify CI build for your pull request (PR). You will need to wait until the CI status is green. **Locating Your Changes:** Since there's no search feature in this Mintlify build, you can find your changes by following these steps: 1. **Copy the file path**: From the file path in GitHub, copy the path, excluding the `.md` file extension. 2. **Construct the URL**: Append this copied path to the Mintlify URL after `/docs`. 3. **Example**: To see the document at tyk-docs GitHub repository, copy `/tyk-self-managed/install` (omit `.md`) and add it after /docs/ in the Netlify URL, resulting in [https://branch-name.mintlify.app/docs/tyk-self-managed/install/](https://branch-name.mintlify.app/docs/tyk-self-managed/install/). 8. **Merge to main (Updates Nightly)** Once the PR is reviewed, approved, and all checks pass, it can be merged into `main`. This automatically triggers a deployment, and your changes will go live on the Nightly version of the docs. 9. **Backporting to Release Versions (Cherry-Picking)** If your change needs to be included in a stable release (e.g., v5.9): 1. Go to your original, now-merged PR on GitHub. 2. Add a label corresponding to the target version, for example, release-5.9. 3. That's it! An automated bot (buger) will detect this label. The bot will: 1. Cherry-pick the commit from your original PR. 2. Create a new PR with those changes, targeting the release-5.9 branch. 3. Automatically merge this new PR once all checks pass. The merge into the `release-5.9` branch triggers the `main` deployment workflow, which rebuilds the `production` branch. Mintlify detects the update and deploys the changes to the live v5.9 documentation. ## Updating an Existing Page To make changes to an existing page in the Tyk documentation, follow these steps: 1. **Switch to the `main` branch and pull the latest changes:** ```bash theme={null} git checkout main git pull origin main ``` 2. **Create a new branch:** ```bash theme={null} git checkout -b
``` 3. **Locate and edit the page:** * Navigate to the appropriate folder in the repository where the `.mdx` file for the page is located. * Open the file and make your changes using Markdown syntax. You can enhance content using Mintlify UI components like callouts, accordions, tabs, and code blocks. * If needed, update the front matter (e.g., `title`, `description`, `tags`) at the top of the file. 4. **Preview your changes locally** to ensure formatting and layout appear as expected. ```bash theme={null} mint dev ``` 5. **Commit and push your changes:** ```bash theme={null} git add . git commit -m "
``` 6. **Create a pull request** on GitHub to merge your branch into `main`. 7. **Review the preview link** provided in the pull request to verify your changes before merging. ## Deleting a Page To delete a page from the Tyk documentation, follow these steps: 1. **Switch to the `main` branch and pull the latest changes:** ```bash theme={null} git checkout main git pull origin main ``` 2. **Create a new branch from `main`:** ```bash theme={null} git checkout -b
``` 3. **Delete the relevant Markdown file** corresponding to the page you want to remove. 4. **Update `docs.json`:** * Remove the entry for the deleted page from the `navigation` section. * Add a redirect in the `redirect` section to point users to a relevant page. This prevents 404 errors when the deleted page is accessed. 5. **Commit and push your changes:** ```bash theme={null} git add . git commit -m "Delete page:
``` 6. **Create a pull request** on GitHub to merge your branch into `main`. 7. **Review the preview link** provided by Mintlify to ensure your changes appear as expected before merging. ## Guide for UI features Apart from the basic markdown writing, Tyk documentation also support UI components like accordions, callouts, cards, expandables, tabs etc. These components help in enhance the documentation's usability and readability. Here's a table summarizing the UI features available for Tyk documentation: | Name | Description | | :- | :- | | [Code Blocks](https://mintlify.com/docs/code) | Display inline code and code blocks | | [Accordions](https://mintlify.com/docs/components/accordions) | A dropdown component to toggle content visibility | | [Callouts](https://mintlify.com/docs/components/callouts) | Use callouts to add eye-catching context to your content | | [Cards](https://mintlify.com/docs/components/cards) | Highlight main points or links with customizable icons | | [Expandables](https://mintlify.com/docs/components/expandables) | Toggle to display nested properties. | | [Tabs](https://mintlify.com/docs/components/tabs) | Toggle content using the Tabs component | | [Mermaid](https://mintlify.com/docs/components/mermaid-diagrams) | Display diagrams using Mermaid | | [Steps](https://mintlify.com/docs/components/steps) | Sequence content using the Steps component | | Snipptet | A custom component written by us. TODO | **Note:** The above components is a list of mostly used components in Tyk documentation. To see the complete list of components, refer to the [Mintlify documentation](https://mintlify.com/docs/components). # Tyk Deprecation and EOL Policy Source: https://tyk.io/docs/developer-support/deprecation Official schedule and information regarding Tyk component deprecation and End-of-Life (EOL). ## Introduction This page provides important information about the deprecation and End-of-Life (EOL) schedules for various **Tyk components, features, and packages**. Our goal is to keep you informed so you can plan your upgrades effectively and maintain a secure and supported environment. **Scope:** This policy and the notices on this page apply specifically to software, features, and components developed and distributed by Tyk. While we actively manage and update our external dependencies (like databases, libraries, Go versions), their individual EOL schedules are governed by their respective maintainers and are outside the scope of this specific Tyk deprecation policy. Currently, this page primarily focuses on Tyk software **packages** (Debian/RPM distributions hosted on packagecloud.io). We will expand this page to include other components or features as their lifecycle status changes. Please consider this a living document and check back periodically for updates. ## Understanding Deprecation and End-of-Life (EOL) It's crucial to understand the terms we use for the lifecycle of Tyk components and features: * **Deprecation:** This marks the phased retirement of a Tyk component or feature. * **What it means:** The component/feature will still be available for a period but will **no longer receive active support, updates, or enhancements** from Tyk. * **Action Required:** Customers are advised to plan and execute an upgrade or migration to the recommended alternative within the specified timeframe (the deprecation window). * **Future State:** Continued use is discouraged as the component/feature will eventually reach its End-of-Life (EOL). * **End-of-Life (EOL):** This is the final stage following deprecation. * **What it means:** The Tyk component or feature is **completely removed from the product or service**, or rendered inaccessible. * **Action Required:** After the specified EOL date, the component/feature will no longer be available or functional. All dependencies on it within your systems must be eliminated *before* this date. * **Deprecation Window:** This refers to the period between the initial deprecation announcement (when support ceases) and the final End-of-Life (EOL) date when the component/feature is removed or becomes inaccessible. **Key Distinction:** Deprecation is the *start* of the retirement process (support ends), while EOL is the *end* (removal/inaccessibility). ## Deprecated Packages Schedule & Repository Removal The table below outlines the lifecycle dates for specific versions of Tyk software **packages** hosted on [packagecloud.io/tyk/](https://packagecloud.io/tyk/). | Component | Deprecation Date (Support Ends) | EOL Date (Package Removal) | Reason | Recommended Action | | :- | :- | :- | :- | :- | | Gateway & Dashboard \< v3.0 | 2023 | March 15, 2025 | Version reached End-of-Life | Upgrade to a supported version | | Pump \< v1.6.0 | 2023 | March 15, 2025 | Version reached End-of-Life | Upgrade to a supported version | | Tyk Identity Broker \< v1.1.0 | 2023 | March 15, 2025 | Version reached End-of-Life | Upgrade to a supported version | | MDCB \< v1.8.2 | 2023 | March 15, 2025 | Version reached End-of-Life | Upgrade to a supported version | *Deprecation Date indicates when support and updates ceased. EOL Date indicates when the package artifact will be removed from the public repository.* ## Plan Your Upgrade Running outdated software versions can expose your systems to security vulnerabilities and prevent you from benefiting from the latest features, performance improvements, and bug fixes. Components that have passed their Deprecation Date are unsupported. We strongly recommend upgrading any components that are deprecated or nearing their EOL date to a currently supported version. * **Upgrade Guides:** Please consult the official [Tyk Upgrade Documentation](/docs/developer-support/upgrading) for detailed instructions. * **Release Notes:** Review the [Tyk Release Notes](/docs/developer-support/release-notes/overview) for information on new features and changes in recent versions. ## Need Assistance? If you have questions regarding this schedule, require help planning your upgrade strategy, or need specific guidance related to your Tyk deployment: * **Contact Tyk Support:** Please reach out to our [Support Team](https://tyk.io/contact) for assistance. We're here to help ensure your upgrade process is as smooth as possible. # Inclusive Naming Source: https://tyk.io/docs/developer-support/documentation-projects/inclusive-naming Explains the inclusive naming initiative concerning Tyk docs This document is intended for Tyk users, contributors, and anyone interested in our commitment to inclusive language within Tyk's documentation and product interfaces. ## Inclusive Naming project We are excited to announce the launch of our *Inclusive Naming* project, in June 2024, dedicated to updating our documentation and aligning with the [Inclusive Naming Initiative (INI)](https://inclusivenaming.org). This initiative reflects our commitment to fostering an inclusive and respectful environment for our users and within our company. The [Inclusive Naming Initiative](https://inclusivenaming.org/) is a community-driven effort to promote and standardize the use of inclusive language in software and documentation. By adhering to their guidelines, we aim to eliminate terms that can be considered exclusionary, offensive, or insensitive and replace them with language that is respectful and welcoming to all. ## Purpose Our commitment to diversity, equity, and inclusion is foundational to our values. By updating our documentation to comply with the *Inclusive Naming Initiative (INI)*, we are taking a significant step towards ensuring that our language reflects our dedication to inclusivity. This project will help us: * **Create a more welcoming environment**: By using inclusive language, we create a space where everyone feels valued and respected. * **Enhance accessibility**: Clear and inclusive documentation improves accessibility for all users, regardless of their background or identity. ## Tier 1 word list INI sorts terms into word lists, considering both the severity of the term and the level of scrutiny it has received. [INI Tier 1 words](https://inclusivenaming.org/word-lists/tier-1) are considered critical and are recommended to be replaced immediately. INI has identified that terms included in this list have one or all of the following attributes: * Strong social consensus within the software development community on replacements * Are identified by the INI as high-severity terms in need of immediate replacement * Terms where the impact of change or removal is low: for example, there is little entanglement in low-level systems or standardized language set by standards bodies * Have passed through all the review stages in Tiers 2 and 3 ## Phase 1: Review of Tyk Documentation for Tier 1 Words An initial review of the Tyk documentation was conducted in April 2024 to check which tier 1 words can be replaced, which can't, and why. ### Findings and planning The main findings of the review are: 1. **Explanatory content with INI tier 1 words**: The content on these pages can be easily rephrased and is now completed. 2. **Configuration parameters containing INI tier 1 words**: * Some *INI tier 1 words* are embedded in the code as part of the name of parameters, fields, and keywords. * These words are sourced from Tyk products, and third-party libraries, and tooling, e.g. Redis. * Possible actions: * Being part of the source code, we can't simply rephrase and use a different terminology. Such change requires following a deprecation process to ensure there are no breaking changes for our users. * For now, we can minimize their usage and rephrase the explanatory content to use inclusive words. ## Phase 2: Removing Tier 1 words from Tyk documentation In June 2024, based on the review we executed the planned changes to the content in our [documentation](https://github.com/tykTechnologies/tyk-docs/). ### Status update This is the update on the status of our documentation 1. **Regular explanatory content with INI tier 1 words**: Content in the documentation has been rephrased and the work is now completed. 2. **Configuration parameters containing INI tier 1 words**: These words are still in our docs, however, we minimized their usage and rephrased their explanatory content to use inclusive words. * **Tyk products**: These words are still in our docs, however, Tyk aims to gradually replace them (in a backward-compatible way) and update the docs accordingly. * **Third-party and dependencies**: There's nothing much we can do at the moment except wait for them to replace these parameters, however, we are committed to updating our docs once this gets done. ### List of configuration parameters containing INI tier 1 word For your records, the following sections highlight the existing *INI tier 1 words* in our docs, per Tyk component: #### Tyk Gateway **Config parameters** * [allow\_master\_keys](/docs/tyk-oss-gateway/configuration#allow_master_keys) * [analytics\_storage.master\_name](/docs/tyk-oss-gateway/configuration#analytics_storage-master_name) * [cache\_storage.master\_name](/docs/tyk-oss-gateway/configuration#cache_storage-master_name) * [storage.master\_name](/docs/tyk-oss-gateway/configuration#storage-master_name) * [slave\_options](/docs/tyk-oss-gateway/configuration#slave_options) * [blacklisted\_ips](/docs/api-management/gateway-config-tyk-classic#ip-access-control) * [disable\_ports\_whitelist](/docs/key-concepts/tcp-proxy#allowing-specific-ports) * [enable\_ip\_blacklisting](/docs/api-management/gateway-config-tyk-classic#ip-access-control) * [ports\_whitelist](/docs/key-concepts/tcp-proxy#allowing-specific-ports) #### Tyk Classic API Definition The Tyk Gateway OpenAPI Document (Tyk Gateway swagger), includes references to the following Tyk Classic API Definition parameters: * [version\_data.versions.version-name.extended\_paths.black\_list](/docs/api-management/traffic-transformation/block-list#api-definition). There is also a parameter with equivalent functionality under the `paths` object (`version_data.versions.{version_name}.paths.black_list`). * [version\_data.versions.version-name.extended\_paths.white\_list](/docs/api-management/traffic-transformation/allow-list#api-definition). There is also a parameter with equivalent functionality under the `paths` object (`version_data.versions.{version_name}.paths.white_list`). #### Tyk Dashboard **Config parameters** * [enable\_master\_keys](/docs/tyk-dashboard/configuration#enable_master_keys) * [redis\_master\_name](/docs/tyk-dashboard/configuration#redis_master_name) **Tyk Classic API Definition** The Tyk Dashboard OpenAPI Document (Tyk Dashboard swagger), contains references to [the parameters from the above Tyk Classic API Definition list](#gw-classic-api-definition). **Dashboard UI** The Tyk Classic APIs *Endpoint Designer* shows configuration of [blacklist](/docs/api-management/traffic-transformation/block-list#api-designer) and [whitelist](/docs/api-management/traffic-transformation/allow-list#api-definition) middleware plugins. #### Tyk MDCB The following MDCB configuration parameters contain tier 1 word occurrences: * [analytics\_storage.master\_name](/docs/tyk-multi-data-centre/mdcb-configuration-options#analytics_storage-master_name) * [storage.master\_name](/docs/tyk-multi-data-centre/mdcb-configuration-options#storage-master_name) #### Tyk Pump The following Tyk Pump configuration parameters contain tier 1 word occurrences: * [analytics\_storage\_config.master\_name](/docs/tyk-pump/tyk-pump-configuration/tyk-pump-environment-variables#analytics_storage_config-master_name) #### Third-party dependencies Content contains *INI Tier 1 word* occurrences due to the following external dependencies: * Links to Tyk Component GitHub repositories with a default branch set as `master`. * Tyk Gateway and Tyk Pump content use Redis terminology for `master` in relation to key storage and analytics. * Tyk Classic Developer Portal provides [documentation](/docs/tyk-developer-portal/tyk-portal-classic/keycloak-dcr) that explains how to integrate Tyk with Keycloak using the [OpenID Connect Dynamic Client Registration](https://tools.ietf.org/html/rfc7591) protocol. The example in the guide uses the Keycloak default `master` realm. * Tyk Bitnami Helm charts use a service with a DNS name of *tyk-redis-master.tyk.svc*. # Early Access Features Source: https://tyk.io/docs/developer-support/release-types/early-access-feature Explain what Early Access Features means and what to expect Early Access features are fully tested Tyk features. However, please note that your access to these features is on an "early access" basis and as a result they may not support the functionality of similar features or functionality that you would otherwise expect. As we extend the capabilities of our Early Access features we may make changes that are not backwards compatible. Please ensure that you consider these limitations before using an Early Access feature. Early Access features are provided "as is" and Tyk disclaims and excludes to the fullest extent permitted by applicable laws all warranties, representations, conditions and all other terms, express or implied, including, but not limited to, implied warranties of merchantability and fitness for a particular purpose. By accessing the Early Access features, you agree that Tyk will not be liable for any losses or damages caused in connection with Early Access features, unless the relevant losses or damages are due to our fraud, willful misconduct or gross negligence. This limitation does not apply to limitations that cannot be limited by law. # FIPS 140-3 Compliance Source: https://tyk.io/docs/developer-support/release-types/fips-release How Tyk supports regulated organizations, such as government, healthcare, and financial sectors, in achieving FIPS 140-3 compliant deployments using validated cryptographic modules and hardened container images ## What is FIPS? The [Federal Information Processing Standards](https://csrc.nist.gov/glossary/term/federal_information_processing_standard) (FIPS) are U.S. government standards for cryptographic modules, defined by the [National Institute of Standards and Technology](https://www.nist.gov/) (NIST). FIPS compliance is often required for organizations in: * Government and defence * Healthcare and life sciences * Financial services * Critical infrastructure For API management in regulated sectors, FIPS matters because it ensures that only approved cryptographic algorithms are used for data in transit, that token signing and key hashing operations use validated methods, and that your deployment meets regulatory requirements when FIPS is mandated. *** ## Tyk FIPS Offering Tyk's FIPS-compliant products are available as a paid **Enterprise Edition FIPS add-on (EE-FIPS)**. Please speak to your account manager for access. Subject to the terms of this policy, and our wider FIPS terms, the following components are available in FIPS-compliant form (the “**FIPS Products**”): * Tyk Gateway * Tyk Dashboard * Tyk Pump * MDCB * Tyk Sync * Tyk Operator (images only; packages are not generated for Operator) * Kubernetes bootstraps * Tyk Enterprise Developer Portal FIPS Products are distributed separately and are identifiable by the `-fips` suffix (e.g. `tyk-gateway-fips`, `tyk-pump-fips`). FIPS Products are available on the **current LTS**, **LTS-1**, and **latest feature branch**. We recommend staying on the current LTS for the most stable and regularly patched FIPS releases. See the [LTS policy](https://tyk.io/docs/developer-support/release-types/long-term-support) for details. *** ## FIPS Standard by Version Compliance posture depends on the software version. See below for version-specific details. **5.13.x is our current LTS release. Please refer to this [page](/docs/developer-support/release-types/long-term-support) for exact timelines** * Targets **FIPS 140-3** compliance * Available as **Docker Hardened Images (DHI)** or **native OS packages (RPM/DEB)** * Both formats deliver the same FIPS 140-3 compliant application-layer cryptography * DHI builds additionally use a FIPS-validated base image, are STIG-compliant, and include enterprise supply chain security controls (SLSA Level 3 build provenance, signed SBOMs, and cryptographic image signatures) * Native packages deliver the core FIPS-compliant cryptographic binaries but do not include a certified base image or supply chain attestations **Version 5.8.x (LTS-1, now in Maintenance Support)** * Targets **FIPS 140-2** compliance * Available as **RPM/DEB packages only** using the BoringCrypto cryptographic module * Not built on a FIPS-certified base image * Compliance applies to the packaged binaries only; it does not extend to the container image, plug-ins, or surrounding environment * Does not include DHI supply chain attestations (SLSA/SBOMs) > **If your organisation has regulatory obligations requiring FIPS 140-3, a certified base image, or supply chain attestations, you should be on version 5.13.x or later using Docker Hardened Images.** Contact your Tyk account team for upgrade planning support. *** ## What "FIPS-compliant" means Please note that the FIPS Products have not been submitted to a [NIST](https://www.nist.gov/federal-information-processing-standards-fips) testing lab for validation and Tyk is not FIPS certified. **FIPS-compliant** means that the FIPS Products only use FIPS 140-3 approved cryptographic algorithms when running in FIPS mode, and are built on a FIPS-certified base image. This is only available to specific Tyk-built products as detailed in this policy. In particular: * The FIPS Products use Go 1.25's native FIPS implementation to provide FIPS 140-3 validated cryptographic operations. See [Go FIPS 140-3 documentation](#) for more details. * These packages are distributed separately, identifiable by the `-fips` suffix (e.g., `tyk-gateway-fips`, `tyk-pump-fips`). * The FIPS Products **have not been submitted to a NIST testing lab**. They are therefore *FIPS-compliant*, as per the above definition, but are not *FIPS-certified*. * Tyk’s FIPS-compliant packages are only available to customers who have purchased the right to access and use Tyk’s FIPS Products via an Enterprise Edition FIPS add-on (a “**EE-FIPS add-on**”). Tyk’s EE-FIPS add-on is provided via a Tyk Global Order Form and is subject to Tyk’s latest FIPS policy. * **At all times, customers remain responsible for ensuring compliance with their overall deployment, configuration, infrastructure, and the use of the FIPS Tyk Products.** In addition to being FIPS-compliant, our DHI is also STIG-compliant (Security Technical Implementation Guide). Alongside, we’ve introduced Enterprise-grade supply chain security, including SLSA Level 3 build provenance, signed SBOMs, and cryptographic signatures for the base image. *** ## Important Notes Use of Tyk's FIPS Products is conditional on: * A signed **EE-FIPS add-on** via a Tyk Global Order Form * Acceptance of any additional terms specific to FIPS releases *** ## FAQ
## Quick Setup This section provides a step-by-step guide to quickly set up Tyk Self-Managed using Docker. ### Prerequisites 1. Install [Docker Engine](https://docs.docker.com/engine/install/) 24.0 or newer and [Docker Compose](https://docs.docker.com/compose/install/) v2.20 or later 2. Install the following CLI tools: * [Jq](https://stedolan.github.io/jq/download/) (for JSON processing) * [Git](https://git-scm.com/downloads) (for cloning Github repository) * [curl](https://curl.se/download.html) (for making API requests) 3. Tyk Self-Managed license key (from your trial email) * If you are having issues with your trial license, please contact [info@tyk.io](mailto:info@tyk.io) ### Installation 1. Clone the repository and navigate to the self-managed Docker directory: ```bash theme={null} git clone https://github.com/TykTechnologies/tyk-install cd tyk-install/docker/self-managed ``` 2. Copy the example environment file and add your license keys: ```bash theme={null} cp .env.example .env ``` Open `.env` and set your license keys: ```bash theme={null} TYK_LICENSE_KEY=
# Tyk Documentation
The hub for Tyk API management. Whether you’re new or experienced, get started with Tyk, explore our product stack and core concepts, access in-depth guides, and actively contribute to our ever-evolving products.
Try it out
Get started on any of our platforms
Try Tyk Cloud
Get 48 hours of free, immediate access to our fully managed SaaS solution. No installation required.
Ideal for quick, hassle-free evaluation
Try Tyk Self Managed
Deploy Tyk on your own infrastructure with a free 14-day trial. Full access, full control.
Ideal for on premise environments or custom setups
Proof of Concept
For complex or regulated environments, work with our team on a tailored proof of concept or request an extended, in-depth trial of Tyk.
We’ll map your requirements to Tyk’s architecture.
Most viewed
Quick links to pages our users visit most
Explore by Tyk Stack
Explore everything Tyk has to offer
**Note:** *protobuf* is not currently supported in *MDCB* deployment. If using Tyk Cloud platform under high load, it is also recommended that analytics are stored within a local region. This means that a local Tyk Pump instance can send the analytics to a localised data sink, such as PostgreSQL or MongoDB (no need for the hybrid pump). This can reduce traffic costs since your analytics would not be sent across regions. ## Use the right hardware Tyk is CPU-bound: you will get exponentially better performance the more cores you throw at Tyk - it's that simple. Tyk will automatically spread itself across all cores to handle traffic, but if expensive operations like health-checks are enabled, then those can cause keyspace contention, so again, while it helps, health-checks do throttle throughput. ## Resource limits Make sure your host operating system has resource limits set to handle an appropriate number of connections. You can increase the maximum number of files available to the kernel by modifying `/etc/sysctl.conf`. ``` fs.file-max=160000 ``` Please note that a single file, with associated inode & dcache consumes approximately 1KB RAM. As such, setting `fs.file-max=160000` will consume a maximum of 160MB ram. The changes will apply after a system reboot, but if you do not wish to reboot quite yet, you can apply the change for the current session using `echo 160000 > /proc/sys/fs/file-max`. ## File Handles / File Descriptors Now we need to configure the file handles available to your Tyk services. ### systemd Override your `systemd` unit files for each of the Tyk services using `systemctl edit {service_name}`. * Gateway `systemctl edit tyk-gateway.service` * Dashboard `systemctl edit tyk-dashboard.service` * Pump `systemctl edit tyk-pump.service` * Multi Data-Center Bridge `systemctl edit tyk-sink.service` You may then add `LimitNOFILE=80000` to the `[Service]` directive as follows: ``` [Service] LimitNOFILE=80000 ``` After making these changes, you'll need to restart your service, for example: ``` systemctl restart tyk-gateway.service ``` ### Docker You may set *ulimits* in a container using the `--ulimit` option. See *Docker* documentation for detail on [setting *ulimits*](https://docs.docker.com/engine/reference/commandline/run/#set-ulimits-in-container---ulimit) ``` docker run --ulimit nofile=80000:80000 \ -it --name tyk-gateway \ tykio/tyk-gateway:latest ```
**Using the Circuit Breaker middleware with Tyk OAS APIs** Tyk's circuit breaker middleware is configured at the endpoint level, where it monitors the rate of failure responses (HTTP 500 or higher) received from the upstream service. If that failure rate exceeds the configured threshold, the circuit breaker will trip and Tyk will block further requests to that endpoint (returning `HTTP 503 Service temporarily unavailable`) until the end of a recovery (cooldown) time period. When working with Tyk OAS APIs the circuit breaker is configured in the [Tyk OAS API Definition](/docs/api-management/gateway-config-tyk-oas#operation). You can do this via the Tyk Dashboard API or in the API Designer. If you're using the legacy Tyk Classic APIs, then check out the [Tyk Classic](#configuring-the-circuit-breaker-in-the-tyk-classic-api-definition) page. ## Configuring the Circuit Breaker in the Tyk OAS API Definition The design of the Tyk OAS API Definition takes advantage of the `operationId` defined in the OpenAPI Document that declares both the path and method for which the middleware should be added. Endpoint `paths` entries (and the associated `operationId`) can contain wildcards in the form of any string bracketed by curly braces, for example `/status/{code}`. These wildcards are so they are human-readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: `(.*)`. The circuit breaker middleware (`circuitBreaker`) can be added to the `operations` section of the Tyk OAS Extension (`x-tyk-api-gateway`) in your Tyk OAS API Definition for the appropriate `operationId` (as configured in the `paths` section of your OpenAPI Document). The `circuitBreaker` object has the following configuration: * `enabled`: enable the middleware for the endpoint * `threshold`: the proportion of requests that can error before the breaker is tripped, this must be a value between 0.0 and 1.0 * `sampleSize`: the minimum number of requests that must be received during the rolling sampling window before the circuit breaker can trip * `coolDownPeriod`: the period for which the breaker will remain *open* after being tripped before returning to service (seconds) * `halfOpenStateEnabled`: if set to `true` then the circuit breaker will operate in [half-open mode](#half-open-mode) once it has been tripped ```json {hl_lines=["39-45"],linenos=true, linenostart=1} theme={null} { "components": {}, "info": { "title": "example-breaker", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/status/200": { "get": { "operationId": "status/200get", "responses": { "200": { "description": "" } } } } }, "x-tyk-api-gateway": { "info": { "name": "example-breaker", "state": { "active": true } }, "upstream": { "url": "http://httpbin.org/" }, "server": { "listenPath": { "value": "/example-breaker/", "strip": true } }, "middleware": { "operations": { "status/200get": { "circuitBreaker": { "enabled": true, "threshold": 0.5, "sampleSize": 10, "coolDownPeriod": 60, "halfOpenStateEnabled": true } } } } } } ``` In this example Tyk OAS API Definition the circuit breaker has been configured to monitor requests to the `GET /status/200` endpoint. It will configure the circuit breaker so that if a minimum of 10 requests (`sampleSize`) to this endpoint are received during the [rolling sampling window](#how-the-circuit-breaker-works) then it will calculate the ratio of failed requests (those returning `HTTP 500` or above) within that window. * if the ratio of failed requests exceeds 50% (`threshold = 0.5`) then the breaker will be tripped * after it has tripped, the circuit breaker will remain *open* for 60 seconds (`coolDownPeriod`) * further requests to `GET /status/200` will return `HTTP 503 Service temporarily unavailable` * the circuit breaker will operate in *half-open* mode (`halfOpenStateEnabled = true`) so when the threshold has been reached and the breaker is tripped, Tyk will periodically poll the upstream service to test if it has become available again The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the circuit breaker. ## Configuring the Circuit Breaker in the API Designer Adding the circuit breaker to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow these steps: **Step 1: Add an endpoint** From the **API Designer** add an endpoint that matches the path and method to which you want to apply the middleware.
(Gateway continues to accept traffic) LB->>LB: Remove Gateway from active pool Note over Gateway: Delay period elapsed Gateway->>Gateway: Stop accepting new connections par Process existing connections Gateway->>Connections: Wait for completion (up to graceful_shutdown_timeout_duration) and Prepare resources for cleanup Gateway->>Gateway: Prepare to release resources end Note over Gateway: Timeout or connections completed Gateway->>Gateway: Clean up resources alt Using Dashboard Gateway->>Dashboard: Deregister node end alt Using MDCB Gateway->>MDCB: Disconnect end Gateway->>Gateway: Log completion Gateway->>OS: Process terminates ``` ### Kubernetes Deployments In Kubernetes environments, a pod receiving `SIGTERM` is removed from the Service endpoints list, but the time for that change to propagate to all load balancers and ingress controllers (such as AWS ALB) varies. During this propagation window, traffic can still be routed to a pod that has already stopped accepting connections, resulting in `HTTP 502` errors. `graceful_shutdown_delay_seconds` addresses this by keeping the Gateway accepting traffic while the `/ready` probe fails, giving the load balancer time to complete deregistration before the Gateway stops accepting connections. Set `graceful_shutdown_delay_seconds` to be at least as long as it takes your load balancer to detect the failing readiness probe and stop routing traffic to the pod. This depends on your readiness probe configuration (`periodSeconds` and `failureThreshold`) and your load balancer's deregistration delay setting. For example, with a readiness probe configured as `periodSeconds: 10` and `failureThreshold: 1`, the load balancer may take up to 10 seconds to remove the pod. Setting `graceful_shutdown_delay_seconds: 15` provides a safety margin. Also ensure that Kubernetes `terminationGracePeriodSeconds` on the pod is greater than `graceful_shutdown_delay_seconds` + `graceful_shutdown_timeout_duration`, otherwise Kubernetes will send `SIGKILL` before the shutdown sequence completes. ### Best Practices * Adjust the drain timeout for your workloads: If your APIs handle long-running requests, increase `graceful_shutdown_timeout_duration` accordingly. * Kubernetes deployments: Set `graceful_shutdown_delay_seconds` to exceed your load balancer's deregistration detection time, and ensure `terminationGracePeriodSeconds` is greater than `graceful_shutdown_delay_seconds` + `graceful_shutdown_timeout_duration`. * Monitor shutdown logs: Check for timeout warnings during restarts, which may indicate you need a longer drain timeout. ### Advanced Details If the drain period exceeds `graceful_shutdown_timeout_duration`, Tyk Gateway logs a warning and forcibly terminates any remaining connections. This prevents the Gateway from hanging indefinitely if connections do not close properly. The implementation uses Go's context with timeout to manage the shutdown process, ensuring that resources are properly released even in edge cases. ## Tyk Pump Tyk Pump also includes a graceful shutdown mechanism that ensures clean termination while preserving analytics data integrity. Pump will wait until the current purge cycle completes before flushing the data from all Pumps that have an internal buffer. This feature is particularly important during deployments, updates, or when you need to restart your pump service in production environments. ### Configuration The graceful shutdown behavior in Tyk Pump is primarily controlled by the [purge\_delay](/docs/tyk-pump/tyk-pump-configuration/tyk-pump-environment-variables#purge_delay) parameter in your Tyk Pump configuration file (or set the environment variable `TYK_PMP_PURGEDELAY`): ```json theme={null} { "purge_delay": 10 } ``` | Parameter | Type | Description | | :- | :- | :- | | `purge_delay` | integer | The number of seconds between each purge loop execution. This also affects the graceful shutdown timing as Tyk Pump will complete the current purge cycle before shutting down. Default: 10 seconds. | ### How It Works #### Signal Handling Tyk Pump listens for standard termination signals: * `SIGTERM`: Sent by container orchestrators such as Kubernetes * `SIGINT`: Interrupt signal (Ctrl+C)
- Validates the Tyk Dashboard license key to ensure proper installation prerequisites. | | `bootstrap-post-install` | - Executes post-installation.
- Sets up an organization and admin user in the Tyk Dashboard.
- Creates Kubernetes secrets required by Tyk Operator and Tyk Enterprise Portal.
**Note**: If an existing organization and admin user are found in the database, the bootstrapping job will not set up a new organization and user. The Kubernetes secrets will not contain the expected Org ID or API key. Please update the Secret with existing credentials in this case. | | `bootstrap-pre-delete` | - Functions as a pre-delete hook.
- Cleans up resources, ensuring no residual configurations remain post-uninstallation. | Key Notes on Bootstrapping: * Bootstrapping is triggered **only during** a `helm install` and does not run during a `helm upgrade`. * If `global.components.bootstrap` is set to `false`, only the dashboard license check will be performed. Handling Bootstrapping Failures: * If the bootstrapping process fails, check the logs from the bootstrap pods to diagnose the issue. * Once reviewed, you can safely delete the bootstrap pods. * To re-trigger the bootstrapping process after a failure, you must run `helm uninstall` and start the installation process anew. ### Setting Environment Variables Should any environment variables not be set by the Helm Chart, users can easily add them under the `extraEnvs` section within the charts for further customization. Values set under `extraEnvs` would take precedence over all configurations. Example of setting extra environment variable to gateway: ```yaml theme={null} tyk-gateway: gateway: extraEnvs: - name: TYK_GW_LOGLEVEL value: debug ``` An example is listed below for setting extra [environment variable using ConfigMap data](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-container-environment-variables-using-configmap-data), using gateway: ```yaml theme={null} tyk-gateway: gateway: extraEnvs: - name: CONFIG_USERNAME valueFrom: configMapKeyRef: name: backend-user key: backend-username ``` An example is listed below for setting extra [environment variable using secret data](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data), using gateway: ```yaml theme={null} tyk-gateway: gateway: extraEnvs: - name: SECRET_USERNAME valueFrom: secretKeyRef: name: backend-user key: backend-username ``` In the above example, an extra environment variable `SECRET_USERNAME` will be added to the Gateway container, with a value of `backend-username` associated with the secret `backend-user`. It is useful if you want to access secret data from [Tyk Gateway configuration file (tyk.conf) or API definitions](/docs/tyk-configuration-reference/kv-store). ### Set Redis Connection Details (Required) Tyk uses Redis for distributed rate-limiting and token storage. You may use the [Bitnami chart](https://github.com/bitnami/charts/tree/main/bitnami/redis) or Tyk's [simple-redis](https://artifacthub.io/packages/helm/tyk-helm/simple-redis) to install chart for POC purpose. Set the following values after installing Redis: | Name | Description | | :- | :- | | `global.redis.addrs` | Redis addresses | | `global.redis.pass` | Redis password in plain text | | `global.redis.passSecret.name` | If global.redis.pass is not provided, you can store it in a secret and provide the secret name here | | `global.redis.passSecret.keyName` | key name to retrieve redis password from the secret | ***Recommended: via *Bitnami* chart*** For Redis you can use these rather excellent charts provided by [Bitnami](https://github.com/bitnami/charts/tree/main/bitnami/redis). Copy the following commands to add it: ```bash theme={null} helm upgrade tyk-redis oci://registry-1.docker.io/bitnamicharts/redis -n tyk --create-namespace --install --version 19.0.2 --set image.repository=bitnamilegacy/redis ```
- Validates the Tyk Dashboard license key to ensure proper installation prerequisites. | | `bootstrap-post-install` | - Executes post-installation.
- Sets up an organization and admin user in the Tyk Dashboard.
- Creates Kubernetes secrets required by Tyk Operator and Tyk Enterprise Portal.
**Note**: If an existing organization and admin user are found in the database, the bootstrapping job will not set up a new organization and user. The Kubernetes secrets will not contain the expected Org ID or API key. Please update the Secret with existing credentials in this case. | | `bootstrap-pre-delete` | - Functions as a pre-delete hook.
- Cleans up resources, ensuring no residual configurations remain post-uninstallation. | Key Notes on Bootstrapping: * Bootstrapping is triggered **only during** a `helm install` and does not run during a `helm upgrade`. * If `global.components.bootstrap` is set to `false`, only the dashboard license check will be performed. Handling Bootstrapping Failures: * If the bootstrapping process fails, check the logs from the bootstrap pods to diagnose the issue. * Once reviewed, you can safely delete the bootstrap pods. * To re-trigger the bootstrapping process after a failure, you must run `helm uninstall` and start the installation process anew. ### Setting Environment Variables Should any environment variables not be set by the Helm Chart, users can easily add them under the `extraEnvs` section within the charts for further customization. Values set under `extraEnvs` would take precedence over all configurations. Example of setting extra environment variable to gateway: ```yaml theme={null} tyk-gateway: gateway: extraEnvs: - name: TYK_GW_LOGLEVEL value: debug ``` An example is listed below for setting extra [environment variable using ConfigMap data](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#define-container-environment-variables-using-configmap-data), using gateway: ```yaml theme={null} tyk-gateway: gateway: extraEnvs: - name: CONFIG_USERNAME valueFrom: configMapKeyRef: name: backend-user key: backend-username ``` An example is listed below for setting extra [environment variable using secret data](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data), using gateway: ```yaml theme={null} tyk-gateway: gateway: extraEnvs: - name: SECRET_USERNAME valueFrom: secretKeyRef: name: backend-user key: backend-username ``` In the above example, an extra environment variable `SECRET_USERNAME` will be added to the Gateway container, with a value of `backend-username` associated with the secret `backend-user`. It is useful if you want to access secret data from [Tyk Gateway configuration file (tyk.conf) or API definitions](/docs/tyk-configuration-reference/kv-store). ### Set Redis Connection Details (Required) Tyk uses Redis for distributed rate-limiting and token storage. You may use the Bitnami chart to install or Tyk's `simple-redis` chart for POC purpose. Set the following values after installing Redis: | Name | Description | | :- | :- | | `global.redis.addrs` | Redis addresses | | `global.redis.pass` | Redis password in plain text | | `global.redis.passSecret.name` | If global.redis.pass is not provided, you can store it in a secret and provide the secret name here | | `global.redis.passSecret.keyName` | key name to retrieve redis password from the secret | ***Recommended: via *Bitnami* chart*** For Redis you can use these rather excellent charts provided by [Bitnami](https://github.com/bitnami/charts/tree/main/bitnami/redis). Copy the following commands to add it: ```bash theme={null} helm upgrade tyk-redis oci://registry-1.docker.io/bitnamicharts/redis -n tyk --create-namespace --install --version 19.0.2 --set image.repository=bitnamilegacy/redis ```
```bash theme={null} helm install tyk-redis bitnami/redis -n tyk --version 19.0.2 ```
```bash theme={null} helm install tyk-mongo bitnami/mongodb --set "replicaSet.enabled=true" -n tyk --version 15.1.3 ```
```bash theme={null} helm install tyk-postgres bitnami/postgresql --set "auth.database=tyk_analytics" -n tyk --version 12.12.10 ```
**Step 3: Configure Tyk Pump** If you don't complete this step, you won't see any analytics in your Dashboard, so to enable the analytics service, we need to ensure Tyk Pump is running and configured properly. **Configure Tyk Pump for MongoDB**
```yaml expandable theme={null} tyk-gateway: gateway: securityContext: enabled: false containerSecurityContext: enabled: false initContainers: setupDirectories: securityContext: enabled: false tyk-dashboard: dashboard: securityContext: enabled: false containerSecurityContext: enabled: false tyk-pump: pump: securityContext: enabled: false containerSecurityContext: enabled: false tyk-bootstrap: bootstrap: securityContext: enabled: false containerSecurityContext: enabled: false # Only required when global.components.devPortal is true tyk-dev-portal: securityContext: enabled: false containerSecurityContext: enabled: false # Only required when global.components.operator is true tyk-operator: managerPodSecurityContext: enabled: false # Required for `helm test` to pass tests: securityContext: enabled: false containerSecurityContext: enabled: false ``` Tyk Pump is enabled by default in this chart. Tyk Developer Portal and Tyk Operator are not.
```yaml expandable theme={null} tyk-gateway: gateway: securityContext: enabled: false containerSecurityContext: enabled: false initContainers: setupDirectories: securityContext: enabled: false tyk-dashboard: dashboard: securityContext: enabled: false containerSecurityContext: enabled: false tyk-bootstrap: bootstrap: securityContext: enabled: false containerSecurityContext: enabled: false tyk-mdcb: mdcb: podSecurityContext: enabled: false containerSecurityContext: enabled: false # Only required when global.components.pump is true tyk-pump: pump: securityContext: enabled: false containerSecurityContext: enabled: false # Only required when global.components.devPortal is true tyk-dev-portal: securityContext: enabled: false containerSecurityContext: enabled: false # Only required when global.components.operator is true tyk-operator: managerPodSecurityContext: enabled: false ``` Note that Tyk MDCB uses `podSecurityContext`, not `securityContext`, for its pod-level block. Tyk Pump is disabled by default in this chart. This chart ships no Helm test pod, so it has no `tests` section.
```yaml expandable theme={null} tyk-gateway: gateway: securityContext: enabled: false containerSecurityContext: enabled: false initContainers: setupDirectories: securityContext: enabled: false tyk-pump: pump: securityContext: enabled: false containerSecurityContext: enabled: false # Required for `helm test` to pass tests: securityContext: enabled: false containerSecurityContext: enabled: false ``` Tyk Pump is enabled by default in this chart.
```yaml expandable theme={null} tyk-gateway: gateway: securityContext: enabled: false containerSecurityContext: enabled: false initContainers: setupDirectories: securityContext: enabled: false # Only required when global.components.pump is true tyk-pump: pump: securityContext: enabled: false containerSecurityContext: enabled: false # Only required when global.components.operator is true tyk-operator: managerPodSecurityContext: enabled: false # Required for `helm test` to pass tests: securityContext: enabled: false containerSecurityContext: enabled: false ``` Tyk Pump and Tyk Operator are both disabled by default in this chart.
Before diving into Tyk Operator reconciliation, let's briefly mention some technical details about how and when reconciliation happens. Reconciliation only happens when certain events happen on your cluster or objects. Therefore, Reconciliation will **NOT** be triggered when there is an update or modification on Tyk’s side. It only watches certain Kubernetes events and is triggered based on them. Usually, the reconciliation happens when you modify a Kubernetes object or when the cache used by the controller expires - side note, controllers, in general, use cached objects to reduce the load in the Kube API server. Typically, caches expire in \~10 hours or so but the expiration time might change based on Operator configurations. So, in order to trigger Reconciliation, you can either * modify an object, which will trigger reconciliation over this modified object or, * restart Tyk Operator pod, which will trigger reconciliation over each of the objects watched by Tyk Operator. **What happens during Reconciliation?**
Tyk Operator will compare desired state of the Kubernetes object with the observed state in Tyk. If there is a drift, Tyk Operator will update the actual state on Tyk with the desired state. In the reconciliation, Tyk Operator mainly controls three operations; DELETE, CREATE, and UPDATE. * **CREATE** - an object is created in Kubernetes but not exists in Tyk * **UPDATE** - an object is in different in Kubernetes and Tyk (we compare that by hash) * **DELETE** - an object is deleted in Kubernetes but exists in Tyk **Drift Detection**
If human operators or any other system delete or modify API Definition from Tyk Gateway or Dashboard, Tyk Operator will restore the desired state back to Tyk during reconciliation. This is called Drift Detection. It can protect your systems from unauthorized or accidental modifications. It is a best practice to limit user access rights on production environment to read-only in order to prevent accidental updates through API Manager directly. ### CRD Versioning Tyk follows standard practices for naming and versioning custom resources as outlined by the Kubernetes Custom Resource Definition [versioning guidelines](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/). Although we are currently on the `v1alpha1` version, no breaking changes will be introduced to existing Custom Resources without a version bump. This means that any significant changes or updates that could impact existing resources will result in a new version (e.g., `v1beta1` or `v1`) and Operator will continue supporting all CRD versions for a reasonable time before deprecating an older version. This ensures a smooth transition and compatibility, allowing you to upgrade without disrupting your current configurations and workflows. For more details on Kubernetes CRD versioning practices, refer to the Kubernetes Custom Resource Definition [Versioning documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/). ### Operator User Tyk Operator is a Kubernetes Controller that manages Tyk Custom Resources (CRs) such as API Definitions and Security Policies. Developers define these resources as [Custom Resource (CRs)](#custom-resources-in-tyk), and Tyk Operator ensures that the desired state is reconciled with the Tyk Gateway or Dashboard. This involves creating, updating, or deleting API configurations until the target state matches the desired state. For the Tyk Dashboard, Tyk Operator functions as a system user, bound by Organization and RBAC rules. During start up, Tyk Operator looks for these keys from `tyk-operator-conf` secret or from the environment variables (listed in the table below). | Key or Environment Variable | Description | | :- | :- | | `TYK_MODE` | "ce" for OSS or "pro" for licensed users | | `TYK_URL` | URL of Tyk Gateway or Dashboard API | | `TYK_ORG` | Organization ID of Operator user | | `TYK_AUTH` | API key of Operator user | These would be the default credentials Tyk Operator uses to connect to Tyk. ### Multi-tenancy in Tyk Tyk Dashboard is multi-tenant capable, which means you can use a single Tyk Dashboard instance to host separate [organizations](/docs/dashboard-admin-api#organizations) for each team or department. Each organization is a completely isolated unit with its own: * API Definitions * API Keys * Users * Developers * Domain * Tyk Classic Portal This structure is ideal for businesses with a complex hierarchy, where distinct departments operate independently but within the same overall infrastructure.