Manage Policies

Security policies control rate limits, quotas, and API access for your consumers. The CLI lets you author policies as human-friendly YAML files and sync them to your Tyk Dashboard.

Requires Tyk Dashboard v5.12.0+. The policy commands rely on the Dashboard’s id field for direct lookups. Earlier versions only resolve the _id (MongoDB ObjectID) in API paths, so friendly IDs will not work.

Quick start

# Scaffold a new policy
tyk policy init --id gold --name "Gold Plan"

# Edit policies/gold.yaml, then apply
tyk policy apply -f policies/gold.yaml

# Verify
tyk policy list
tyk policy get gold

Policy YAML schema

Policies use a CLI schema that is converted to Dashboard wire format on apply. Durations are human-readable (30d, 1h, 60s) and APIs are referenced by name, listen path, or tags instead of raw IDs.

id: gold
name: Gold Plan
tags:
  - paid
  - gold
rateLimit:
  requests: 1000
  per: 1m              # 1000 requests per minute
quota:
  limit: 100000
  period: 30d          # 100k requests per 30 days
keyTTL: "0"            # 0 = keys never expire
access:
  - name: users-api    # Match by API name
    versions: [v1]
  - listenPath: /orders/  # Match by listen path
    versions: [v1, v2]
  - tags: [public, v1]    # Match ALL tags, expands to all matching APIs
    versions: [Default]
  - id: abc123def456       # Match by exact API ID

Friendly IDs

The id field is a human-readable identifier that you choose. Use short, descriptive names:

id: gold           # Good
id: free-tier      # Good
id: rate-limit-v2  # Good

Format rules:

Lowercase letters, numbers, dots, hyphens, and underscores only
Must start with a letter or number
Maximum 64 characters
Must not look like a MongoDB ObjectID (24-character hex strings are rejected)

The CLI passes this value directly into the Dashboard’s wire id field — no prefix, no transformation. Starting in Dashboard v5.12.0+, the id field is a first-class identifier used for all API lookups (GET, PUT, DELETE). The Dashboard handles the internal _id (MongoDB ObjectID) invisibly; you only work with the friendly name.

Durations

Format	Meaning
`30d`	30 days
`24h`	24 hours
`1m`	1 minute
`60s`	60 seconds
`60`	60 seconds (plain integer)
`0`	Disabled / no expiry

API selectors

Each entry in access uses exactly one selector to identify APIs:

Selector	Behaviour
`name`	Exact match on API name. Must resolve to exactly one API.
`listenPath`	Exact match on listen path. Must resolve to exactly one API.
`id`	Exact match on API ID. Must resolve to exactly one API.
`tags`	Match ALL specified tags. Expands to every API that has all tags.

If a name or listen path matches zero APIs, the CLI suggests the 3 closest matches.

Commands

`tyk policy list`

List policies in a paginated table. The ID column shows the id field, or the internal _id for policies that have no id set (e.g. created outside the CLI).

tyk policy list              # Table with ID, Name, APIs, Tags
tyk policy list --page 2     # Page 2
tyk policy list --json       # JSON to stdout

Example output:

ID                          Name                      APIs        Tags
---                         ---                       ---         ---
gold                        Gold Plan                 3           gold, paid
free-tier                   Free Tier                 1           free

`tyk policy get <policy-id>`

Retrieve a policy, convert from wire format to CLI schema, and output as YAML.

tyk policy get gold          # YAML to stdout, summary to stderr
tyk policy get gold --json   # JSON to stdout

The CLI reverse-resolves API IDs back to name selectors where possible. If an API ID cannot be resolved (e.g. the API was deleted), it falls back to an id selector.

`tyk policy apply -f <file>`

Apply a policy with idempotent upsert semantics: creates the policy if the friendly ID is not found on the server, updates if it exists.

tyk policy apply -f policies/gold.yaml
tyk policy apply -f -        # Read from stdin

The apply pipeline:

Parse YAML and validate schema (required fields, duration format, selector format, friendly ID format)
Resolve selectors against the live API list
Parse durations to seconds
Convert CLI schema to wire format
Look up the policy by friendly ID (single API call, O(1))
Create (if new) or update (if existing) the policy

On create, the CLI omits the internal _id and lets the Dashboard generate it. On update, the CLI uses the friendly id directly in the API call. The _id is handled invisibly by the Dashboard.

Validation and resolution errors return exit code 2 with all errors listed so you can fix them in one pass.

`tyk policy delete <policy-id>`

Delete a policy by ID. Fetches the policy first to show its name in the confirmation prompt.

tyk policy delete gold       # Interactive confirmation
tyk policy delete gold --yes # Skip confirmation
tyk policy delete gold --yes --json  # JSON result to stdout

Exit codes: 0 = success or cancelled, 3 = policy not found.

`tyk policy init`

Generate a scaffold YAML file with sensible defaults. No Dashboard connectivity required.

tyk policy init --id gold --name "Gold Plan"
tyk policy init --id silver --name "Silver Plan" --dir ./project

Creates policies/{id}.yaml relative to --dir (default: current directory). Refuses to overwrite an existing file.

GitOps workflow

Policies are designed for version control. A typical workflow:

# One-time: scaffold
tyk policy init --id gold --name "Gold Plan"

# Edit in your editor
vim policies/gold.yaml

# Apply to dev
tyk config use dev
tyk policy apply -f policies/gold.yaml

# Commit
git add policies/gold.yaml && git commit -m "Add gold policy"

# Apply to staging
tyk config use staging
tyk policy apply -f policies/gold.yaml

Backward compatibility

Policies created before the friendly ID feature (via the Dashboard UI or older CLI versions) may have an empty id field. These policies still appear in tyk policy list with their internal _id shown in the ID column.

To manage an existing policy with a friendly ID, re-apply it with a policy file that has the desired id. This creates a new CLI-managed policy – it does not modify the original.

Exit codes

Code	Meaning
`0`	Success
`1`	Network or server error
`2`	Validation error (bad input, unresolved selectors)
`3`	Resource not found