Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tyk.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

In Tyk, a Session dictates the lifecycle, limits, and access rights for a specific client. However, managing these settings individually for thousands or millions of clients is inefficient and error-prone. This is where Policies come in. A Policy is essentially a reusable template or blueprint that defines a set of access rights, rate limits, and quotas. Instead of configuring these rules directly on every individual Session, you configure them once in a Policy, and then link multiple Sessions to that Policy.

​
Why Use Policies?

We highly recommend using Policies as the primary method for managing access control in Tyk.

​
1. Management at Scale

If you need to change a rate limit or grant access to a new API endpoint, doing so without Policies would require updating all the relevant Sessions in your database. With Policies, you simply update the Policy object once, and the changes instantly apply to all linked Sessions.

​
2. Tiered Access Models

Policies are perfect for implementing tiered subscription models (e.g., “Free”, “Pro”, and “Enterprise”). You can create a Policy for each tier with different rate limits and quotas, and assign clients to the appropriate Policy when they register.

​
3. Granular Feature Toggles

Because you can apply multiple Policies to a single Session, you can use Policies to represent individual features or add-ons. If a user purchases an add-on, you simply link the corresponding Policy to their Session.

​
How Policies are Managed

How you create and manage Policies depends on your Tyk deployment:
  • Tyk Dashboard (Cloud & Self-Managed): Policies are managed centrally via the Dashboard UI or the Dashboard API. They are stored in your database and automatically synchronized across all your connected Gateways.
  • Tyk Open Source: If you are using the open-source Gateway, Policies are typically defined in a local policies.json file or managed directly via the Gateway API.

​
How and When Policies are Applied

When a Policy is linked to a Session, the Gateway does not permanently copy the Policy’s rules into the Session data in Redis. Instead, Policies are applied dynamically during request processing. When a client makes a request, Tyk retrieves their Session from Redis (or the local cache). Tyk then looks up the linked Policies and overlays their rules onto the Session on the fly. This dynamic application is what makes Policies so powerful: updating a Policy immediately affects all existing Sessions linked to it. The next time a client makes a request, Tyk will apply the newly updated Policy rules.

​
Applying Multiple Policies

Tyk allows you to link more than one Policy to a single Session. This is incredibly useful for combining base access tiers with specific feature add-ons. When multiple Policies are applied to a Session, Tyk must merge their rules to determine the final access rights. For example Tyk uses the following merging logic:
  • Rate Limits: Tyk applies the most permissive rate limit settings. If Policy A allows 10 requests per second, and Policy B allows 100 requests per second, the Session will be allowed 100 requests per second.
  • Access Rights: Tyk combines the allowed URLs and methods from all policies. If Policy A allows GET /users and Policy B allows POST /reports, the Session will be allowed to do both.

​
JWT Scope-to-Policy Mapping

For token-based authentication methods such as JWT and OAuth 2.0, Tyk offers a powerful feature called Scope-to-Policy Mapping. Instead of assigning a Policy to a client’s Session statically, you can configure Tyk to inspect the claims within the token (such as the scope claim) and dynamically map those scopes to specific Tyk Policies. For example, if an Identity Provider issues a JWT with the scopes read:data and admin, Tyk can automatically apply the “Read-Only Policy” and the “Admin Policy” to the dynamically generated Session. This allows you to drive Tyk’s granular access controls directly from your centralized Identity Provider.