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

While standard Session fields handle access rights, rate limits, and quotas, Tyk also provides a flexible key-value store attached directly to the Session object known as Session Metadata (meta_data).
Key vs. SessionWhile Tyk’s APIs and UI often refer to adding metadata to a “Key”, the metadata is actually stored on the underlying Session. The Key is simply the credential or identifier used by the client to look up this Session.
Metadata allows you to store custom, user-specific, or application-specific context. This data persists with the Session and is loaded into memory whenever the Key is used to authenticate a request, making it instantly available during the request lifecycle.

​
Use Cases

Metadata is primarily used to make user-specific data available to Tyk middleware when handling a request without requiring additional database lookups. Common use cases include:
  • Identity Propagation: Storing a user_id, tenant_id, or account_id in the Session metadata and injecting it into upstream headers so your backend service knows exactly who is making the request.
  • Dynamic Routing: Using metadata values in URL Rewrites to route users to specific backend shards, geographic regions, or pricing tiers.
  • Custom Plugin Logic: Passing custom attributes (like user roles, subscription levels, or feature flags) to custom plugins to make dynamic authorization or transformation decisions.

​
Where it can be modified

Session metadata can be set or updated in several locations:
  • Session creation and update: You can directly update the meta_data field (a JSON object) in the Session object when creating or updating a Session
    • via the Dashboard API
    • via the Gateway API
    • via the Dashboard UI
  • Applying Policies Sessions can inherit metadata from Policies.
  • Dynamic plugins: Custom plugins (JSVM, Coprocess/gRPC) can dynamically modify the metadata during the request lifecycle. If a plugin modifies the metadata, Tyk automatically saves the updated Session back to the Redis store.
  • OAuth flow: When generating an OAuth token, any meta_data configured on the OAuth Client is automatically copied into the generated Session’s meta_data.

​
Where it can be accessed

Metadata stored in the Session can be accessed dynamically during the request lifecycle in several ways:
  • Middleware: Some middleware have access to Session metadata using the $tyk_meta.KEY_NAME variable syntax. This is evaluated in the same way as request context variables, with the Gateway replacing this reference with the corresponding value from the Session metadata in the following middleware:
  • Go Templates: In Body Transform and Response Body Transform middleware, if EnableSession is true, metadata is injected into the template context and can be accessed using {{ ._tyk_meta.KEY_NAME }}.
  • JSVM Plugins & Virtual Endpoints: The session object is passed as a JSON argument to your JavaScript functions. Metadata is accessible via session.meta_data.
  • Custom Go Plugins: Go plugins can extract the session state from the request context (post-authentication) and directly read from or write to the MetaData map.
  • Coprocess Plugins (gRPC, Python, etc.): The session object is passed within the Coprocess request object, and metadata is accessible via Session.Metadata.