plugin-developer-guide.mdx

title	Plugin Developer Guide
description	A comprehensive guide for developers building custom plugins for the Tyk Gateway.

import { Callout } from '/components/callout';

This guide provides an in-depth technical reference for developers building custom plugins for the Tyk Gateway. It is intended for developers who want to extend the functionality of the Tyk Gateway with custom logic.

This guide covers the following topics:

• An overview of the Tyk Gateway's middleware architecture.
• A detailed reference of all built-in middleware.
• Information on the data available to custom plugins.
• Best practices for plugin development.

For information on how to write plugins in a specific language, see the following guides:

• Go Plugins
• Python Plugins
• gRPC Plugins

Data Available to Plugins

Custom plugins have access to a rich set of data, including the request and response objects, the session object, and metadata.

Request and Response Objects

The request and response objects provide access to the HTTP request and response, including headers, body, and other information.

Session Object

The session object contains information about the authenticated user, including their API key, rate limits, and access rights. The session object is only available in the PostKeyAuth, Post, and Response stages.

Metadata

The metadata object is a key-value store that can be used to pass data between middleware and plugins. The metadata object is available in all stages of the middleware execution chain.

Best Practices for Plugin Development

• Keep plugins small and focused. Each plugin should have a single responsibility.
• Handle errors gracefully. Plugins should not crash the Tyk Gateway.
• Write unit tests for your plugins. This will help to ensure that your plugins are working correctly.
• Use the metadata object to pass data between plugins. This is more efficient than modifying the request or response objects directly.

Middleware Execution Order

The Tyk Gateway processes requests in a series of stages, with middleware executing in a specific order. Understanding this execution order is crucial for developing custom plugins that interact with the request and response lifecycle.

The middleware execution chain is divided into five stages:

1. Pre (Pre-authentication): Executes before any authentication checks. This stage is ideal for tasks like header injection, request validation, or IP filtering.
2. AuthCheck (Authentication): Responsible for authenticating the client. Custom authentication plugins can be injected here.
3. PostKeyAuth (Post-authentication): Executes after a successful authentication. This stage can be used for tasks like granular access control or rate limiting.
4. Post (Final Request Processing): Performs final transformations and checks before proxying the request to the upstream service.
5. Response: Executes on the response from the upstream service before it is returned to the client.

The following diagram illustrates the middleware execution chain and the points where custom plugins can be injected.

Built-in Middleware Reference

The following table provides an exhaustive list of all built-in middleware in the Tyk Gateway, along with their execution stage and data access capabilities.

Middleware	Execution Stage	Session Access	Context Vars Access	Metadata Access	Configurable
VersionCheck	Pre	No	Yes	No	Yes
CORSMiddleware	Pre	No	Yes	No	Yes
RateCheckMW	Pre	Yes	Yes	No	Yes
IPWhiteListMiddleware	Pre	No	No	No	Yes
IPBlackListMiddleware	Pre	No	No	No	Yes
CertificateCheckMW	Pre	No	No	No	Yes
OrganizationMonitor	Pre	No	No	No	Yes
Oauth2KeyExists	AuthCheck	Yes	Yes	Yes	Yes
ExternalOAuthMiddleware	AuthCheck	Yes	Yes	Yes	Yes
BasicAuthKeyIsValid	AuthCheck	Yes	Yes	Yes	Yes
HTTPSignatureValidationMiddleware	AuthCheck	Yes	Yes	Yes	Yes
JWTMiddleware	AuthCheck	Yes	Yes	Yes	Yes
OpenIDMW	AuthCheck	Yes	Yes	Yes	Yes
StripAuth	AuthCheck	No	No	No	Yes
KeyExpired	PostKeyAuth	Yes	No	No	Yes
AccessRightsCheck	PostKeyAuth	Yes	No	No	Yes
GranularAccessMiddleware	PostKeyAuth	Yes	No	No	Yes
RateLimitAndQuotaCheck	PostKeyAuth	Yes	No	No	Yes
RateLimitForAPI	Post	No	No	No	Yes
GraphQLMiddleware	Post	No	Yes	Yes	Yes
ValidateJSON	Post	No	Yes	No	Yes
RequestSigning	Post	No	Yes	No	Yes
ValidateRequest	Post	No	Yes	No	Yes
TransformMiddleware	Post	No	Yes	Yes	Yes
URLRewriteMiddleware	Post	No	Yes	No	Yes
mockResponseMiddleware	Post	No	Yes	No	Yes
ResponseMiddleware	Response	Yes	Yes	Yes	Yes

Custom Plugin Injection Points (Hooks)

Custom plugins can be injected into the middleware chain at specific points, known as hooks. These hooks allow you to execute custom logic at different stages of the request and response lifecycle.

The following hooks are available for custom plugins:

• Pre-request Hook: Executes at the beginning of the Pre stage.
• Authentication Hook: Executes during the AuthCheck stage.
• Post-authentication Hook: Executes at the beginning of the PostKeyAuth stage.
• Post-request Hook: Executes at the beginning of the Post stage.
• Response Hook: Executes at the beginning of the Response stage.

Each hook provides access to the request and response objects, as well as the session and metadata. The data available at each hook is detailed in the middleware reference table above.