Secrets Management

Introduction

Secrets Management lets you keep sensitive values, such as passwords, API keys and certificates, out of your API definitions and the configuration of Tyk Gateway and other components. Instead of writing a secret value directly into a config field, you register a secret store and write a reference to a key within that store. The component resolves the reference to the real value. This keeps sensitive values in one place you control access to, lets the same API definition move between environments (development, staging, production) unchanged, and means the people editing API definitions don’t need to see the secrets those definitions use. Available from Tyk Gateway and Tyk Dashboard 5.15.0, Tyk Portal 1.19.0, Tyk MDCB 2.13.0, and Tyk Pump 1.17.0. Earlier versions only support the legacy syntax, which continues to work unchanged alongside this on all newer versions too.

Supported Secret Stores

Each store is registered under a name you choose, with a type that selects which backend it talks to:

Store Type	Availability	Reads From
`env`	All users	Environment variables
`inline`	All users	A literal key/value map written directly into the component’s configuration
`file`	All users	Local files, including Kubernetes Secrets mounted as files
`hashicorp_vault`	All users	A HashiCorp Vault instance
`hashicorp_consul`	All users	A HashiCorp Consul instance
`aws_secrets_manager`	Enterprise Edition	AWS Secrets Manager
`azure_key_vault`	Enterprise Edition	Azure Key Vault
`gcp_secret_manager`	Enterprise Edition	GCP Secret Manager

See Secret Store Providers for how to configure each type.

How It Works

There are three parts to using Secrets Management:

Register a store. Add an entry under the kv.stores section of the component’s configuration, naming the store and giving it a type from the table above and whatever connection details that type needs. A store can also be marked required. See Error Handling below for what that changes. Stores are not shared between components: each component only sees the stores registered in its own configuration, so a Vault instance you want both Tyk Gateway and Tyk Dashboard to read from needs registering separately in each.
Write a reference to it. Anywhere a config value would normally be written, use one of two equivalent notations instead:
Notation Form Use when
Whole-value reference kv://<store>/<path> The entire field is the secret.
Inline token $kv{<store>:<path>} The secret is part of a larger string, such as a hostname embedded in a URL.
The component resolves it. Exactly when this happens depends on the component and where the reference sits. See When References Are Resolved for details. What happens if a reference can’t be resolved is explained in Error Handling.

Notation	Form	Use when
Whole-value reference	`kv://<store>/<path>`	The entire field is the secret.
Inline token	`$kv{<store>:<path>}`	The secret is part of a larger string, such as a hostname embedded in a URL.

Getting Started

This example registers an inline store, a literal key/value map written directly into the config, and references it from a component’s configuration field. tyk.conf:

{
  "kv": {
    "stores": {
      "myvals": {
        "type": "inline",
        "config": {
          "data": {
            "token": "xyz"
          }
        }
      }
    }
  }
}

Any API definition string field, and the supported fields in a component’s configuration file, can now reference it. For example, a token used to authenticate with the upstream:

{
  "api_token": "kv://myvals/token"
}

api_token resolves to the value registered under the token key in the myvals store, so it ends up with the value xyz:

{
  "api_token": "xyz"
}

The inline-token form resolves the same store but only replaces part of the value, for example a token embedded in a URL:

{
  "upstream_url": "https://api.example.com/v1?token=$kv{myvals:token}"
}

which resolves to:

{
  "upstream_url": "https://api.example.com/v1?token=xyz"
}

When References Are Resolved

Exactly when a reference is resolved, and what happens if it can’t be, depends on the component, and on where in that component’s configuration the reference sits:

Location	Scope	When Resolved
API definition fields	Any string field	On load, and on every reload
Tyk Gateway’s configuration file	A fixed set of fields (see below)	Mostly at startup; three fields also on every hot reload
Other Tyk components’ configuration files	Any string field	At startup

Tyk Gateway Two things are different about tyk.conf compared to the other components above. First, it only supports a reference on a fixed, named set of fields. A reference written into any other field is never resolved:

Field	When Resolved
`secret`	At startup
`node_secret`	At startup
`storage.password`	At startup
`cache_storage.password`	At startup
`security.private_certificate_encoding_secret`	At startup
`db_app_conf_options.connection_string`	At startup
`policies.policy_connection_string`	At startup
`slave_options.api_key`	At startup
`external_services.oauth.mtls.cert_file`	At startup, and again on every hot reload
`external_services.oauth.mtls.key_file`	At startup, and again on every hot reload
`external_services.oauth.mtls.ca_file`	At startup, and again on every hot reload

Second, the three external_services.oauth.mtls file paths are re-resolved on every subsequent Gateway hot reload to support certificate rotation.

Multiple Store Instances

You can register more than one store of the same type, for example separate Vault instances for different environments or teams. Each gets its own name, and references disambiguate by store name:

{
  "kv": {
    "stores": {
      "vault-prod": {
        "type": "hashicorp_vault",
        "config": { "address": "https://vault-prod.internal:8200" }
      },
      "vault-staging": {
        "type": "hashicorp_vault",
        "config": { "address": "https://vault-staging.internal:8200" }
      }
    }
  }
}

kv://vault-prod/secret/db/password and kv://vault-staging/secret/db/password will read the value stored as password from two independent Vault instances.

Referencing Fields From JSON Secrets

If a secret’s value is a JSON document, append #<pointer> to the path to extract one field from it instead of resolving the whole document. The pointer follows JSON Pointer notation: segments separated by /, with ~1 and ~0 used to escape a literal / or ~ within a key. For example, suppose a store named myvault holds the following JSON value at the path secrets/db:

{
  "user": "admin",
  "credentials": { "pass": "s3cret" },
  "replicas": ["db-a", "db-b"]
}

The path (secrets/db) selects which secret to fetch from the store; the #fragment then addresses a field within that secret’s own JSON value, including array elements by index:

Reference	Resolves To
`kv://myvault/secrets/db#user`	`admin`
`kv://myvault/secrets/db#credentials/pass`	`s3cret`
`kv://myvault/secrets/db#replicas/0`	`db-a`

Multiple #field extractions from the same underlying secret only fetch that secret from the store once.

Error Handling

There are two independent things that can go wrong with a secret store, and Tyk treats them differently: the store itself can fail to initialize, before any reference is ever resolved against it, or a specific reference can fail to resolve against a store that initialized fine. The rest of this section covers each in turn.

Failed Store Initialization

Marking a store required controls what happens if the store itself fails to initialize (unreachable, bad credentials, an unsupported type). This is a different failure to a single reference not resolving, covered next.

required left unset, or false (the default): a failed store logs a warning and is skipped. The component keeps starting; any reference to that store then fails when something tries to resolve it, following whichever behavior applies to that location (see below).
required: true: a failed store is reported as an error, and the component refuses to start.

Set required: true on any store that provides secrets essential to secure operation, such as authentication credentials or TLS material. With the default false, a component can start and keep serving traffic even though a security-critical secret silently failed to load.

Failed References

An unresolvable reference (an unknown store, a missing key, a malformed reference) in a component’s configuration file is treated as a fatal configuration error at startup: the component logs the failure and refuses to start. The three external_services.oauth.mtls fields on Tyk Gateway are the one exception, since they’re also re-resolved on every hot reload rather than only at startup. If one of these references fails to resolve during a hot reload, an error is logged and the previous value is used. An unresolvable reference in an API definition field is different: it is logged as an error but does not stop the API loading. What this means in practice depends on the field: an unresolved reference in target_url, for example, still parses as a syntactically valid URL, so the API loads and only fails when a request tries to reach that upstream, returning a 500. A reference left unresolved in a header added by transformation middleware is not an error at all: the literal reference string is just sent as the header’s value.

An unresolved reference string sent as a header or body value (for example kv://my-store/db/password) can reveal your store names and secret paths to whatever receives it: an upstream service, or the client, if the field is echoed back in a response. Treat an unresolved reference found in a live environment as a configuration bug to fix immediately, not a benign fallback.

Legacy Key-Value Syntax

If you have existing API definitions or Tyk Gateway configuration using the older vault://, consul://, env://, secrets://, file:// or $secret_* notation, they continue to work unchanged alongside this. See Legacy Key-Value Syntax for details.

Getting Started

Deploy Tyk

Design & Create APIs

Secure APIs

Control Traffic

Routing Traffic

Transform Traffic

Observe APIs

Maintain APIs

Use Cases

Guides

Reference

Developer Support

Introduction

Supported Secret Stores

How It Works

Getting Started

When References Are Resolved

Multiple Store Instances

Referencing Fields From JSON Secrets

Error Handling

Failed Store Initialization

Failed References

Legacy Key-Value Syntax

​Introduction

​Supported Secret Stores

​How It Works

​Getting Started

​When References Are Resolved

​Multiple Store Instances

​Referencing Fields From JSON Secrets

​Error Handling

​Failed Store Initialization

​Failed References

​Legacy Key-Value Syntax

Introduction

Supported Secret Stores

How It Works

Getting Started

When References Are Resolved

Multiple Store Instances

Referencing Fields From JSON Secrets

Error Handling

Failed Store Initialization

Failed References

Legacy Key-Value Syntax