The Tyk Gateway API provides a RESTful interface for managing API definitions, keys, certificates, and health checks directly on a Tyk Gateway node. It is used to configure and operate the gateway programmatically in self-managed and open-source deployments.
openapi: 3.0.3
info:
contact:
email: [email protected]
name: Tyk Technologies
url: https://tyk.io/contact
description: >+
The Tyk Gateway API is the primary means for integrating your application
with the Tyk API Gateway system. This API is very small, and has no granular
permissions system. It is intended to be used purely for internal automation
and integration.
**Warning: Under no circumstances should outside parties be granted access
to this API.**
The Tyk Gateway API is capable of:
* Managing session objects (key generation).
* Managing and listing policies.
* Managing and listing API Definitions (only when not using the Tyk
Dashboard).
* Hot reloads / reloading a cluster configuration.
* OAuth client creation (only when not using the Tyk Dashboard).
In order to use the Gateway API, you'll need to set the **secret** parameter
in your tyk.conf file.
The shared secret you set should then be sent along as a header with each
Gateway API Request in order for it to be successful:
**x-tyk-authorization: <your-secret>***
<br/>
<b>The Tyk Gateway API is subsumed by the Tyk Dashboard API in Pro
installations.</b>
license:
name: Mozilla Public License Version 2.0
url: https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md
title: Tyk Gateway API
version: 5.7.1
servers:
- url: https://{tenant}
variables:
tenant:
default: localhost:8080
description: Your gateway host
security:
- api_key: []
tags:
- description: >
Tyk supports batch requests, so a client makes a single request to the API
but gets a compound response object back.
This is especially handy if clients have complex requests that have
multiple synchronous dependencies and do not wish to have the entire
request / response cycle running for each event.
To enable batch request support, set the `enable_batch_request_support`
value to `true`
Batch requests that come into Tyk are *run through the whole Tyk
machinery* and *use a relative path to prevent spamming*. This means that
a batch request to Tyk for three resources with the same API key will have
three requests applied to their session quota and request limiting could
become active if they are being throttled.
Tyk reconstructs the API request based on the data in the batch request.
This is to ensure that Tyk is not being used to proxy requests to other
hosts outside of the upstream API being accessed.
Batch requests are created by POSTING to the `/{listen_path}/tyk/batch/`
endpoint. These requests **do not require a valid key**, but their request
list does.
<h3>Sample Request</h3>
```{json}
{
"requests": [
{
"method": "GET",
"headers": {
"x-tyk-test": "1",
"x-tyk-version": "1.2",
"authorization": "1dbc83b9c431649d7698faa9797e2900f"
},
"body": "",
"relative_url": "get"
},
{
"method": "GET",
"headers": {
"x-tyk-test": "2",
"x-tyk-version": "1.2",
"authorization": "1dbc83b9c431649d7698faa9797e2900f"
},
"body": "",
"relative_url": "get"
}
],
"suppress_parallel_execution": false
}
```
The response will be a structured reply that encapsulates the responses
for each of the outbound requests. If `suppress_parallel_execution` is set
to `true`, requests will be made synchronously. If set to `false` then
they will run in parallel and the response order is not guaranteed.
<h3>Sample Response</h3>
```
[
{
"relative_url": "get",
"code": 200,
"headers": {
"Access-Control-Allow-Credentials": [
"true"
],
"Access-Control-Allow-Origin": [
"*"
],
"Content-Length": [
"497"
],
"Content-Type": [
"application/json"
],
"Date": [
"Wed, 12 Nov 2014 15:32:43 GMT"
],
"Server": [
"gunicorn/18.0"
],
"Via": [
"1.1 vegur"
]
},
"body": "{
"args": {},
"headers": {
"Accept-Encoding": "gzip",
"Authorization": "1dbc83b9c431649d7698faa9797e2900f",
"Connect-Time": "2",
"Connection": "close",
"Host": "httpbin.org",
"Total-Route-Time": "0",
"User-Agent": "Go 1.1 package http",
"Via": "1.1 vegur",
"X-Request-Id": "6a22499a-2776-4aa1-80c0-686581a8be4d",
"X-Tyk-Test": "2",
"X-Tyk-Version": "1.2"
},
"origin": "127.0.0.1, 62.232.114.250",
"url": "http://httpbin.org/get"
}"
},
{
"relative_url": "get",
"code": 200,
"headers": {
"Access-Control-Allow-Credentials": [
"true"
],
"Access-Control-Allow-Origin": [
"*"
],
"Content-Length": [
"497"
],
"Content-Type": [
"application/json"
],
"Date": [
"Wed, 12 Nov 2014 15:32:43 GMT"
],
"Server": [
"gunicorn/18.0"
],
"Via": [
"1.1 vegur"
]
},
"body": "{
"args": {},
"headers": {
"Accept-Encoding": "gzip",
"Authorization": "1dbc83b9c431649d7698faa9797e2900f",
"Connect-Time": "7",
"Connection": "close",
"Host": "httpbin.org",
"Total-Route-Time": "0",
"User-Agent": "Go 1.1 package http",
"Via": "1.1 vegur",
"X-Request-Id": "1ab61f50-51ff-4828-a7e2-17240385a6d2",
"X-Tyk-Test": "1",
"X-Tyk-Version": "1.2"
},
"origin": "127.0.0.1, 62.232.114.250",
"url": "http://httpbin.org/get"
}"
}
]
```
With the body for each request string encoded in the `body` field.
* `expire_analytics_after`: If you are running a busy API, you may want to
ensure that your MongoDB database does not overflow with old data. Set the
`expire_analytics_after` value to the number of seconds you would like the
data to last for. Setting this flag to anything above `0` will set an
`expireAt` field for each record that is written to the database.
**Important:** Tyk will not create the expiry index for you. In order to
implement data expiry for your analytics data, ensure that the index is
created This is easily achieved using the [MongoDB command line
interface](https://docs.mongodb.com/getting-started/shell/client/).
* `dont_set_quota_on_create`: This setting defaults to `false`, but if set
to `true`, when the API is used to edit, create or add keys, the quota
cache in Redis will not be re-set. By default, all updates or creates to
Keys that have Quotas set will re-set the quota (This has been the default
behaviour since 1.0).
This behaviour can be bypassed on a case-by-case basis by using the `suppress_reset` parameter when making a REST API request. This is the advised mode of operation as it allows for manual, granular
control over key quotas and reset timings.
* `cache_options`: This section enables you to configure the caching
behaviour of Tyk and to enable or disable the caching middleware for your
API.
* `cache_options.enable_cache`: Set this value to `true` if the cache
should be enabled for this endpoint, setting it to false will stop all
caching behaviour.
* `cache_options.cache_timeout`: The amount of time, in seconds, to keep
cached objects, defaults to `60` seconds.
* `cache_options.cache_all_safe_requests`: Set this to `true` if you want
all *safe* requests (GET, HEAD, OPTIONS) to be cached. This is a blanket
setting for APIs where caching is required but you don't want to set
individual paths up in the definition.
* `cache_options.enable_upstream_cache_control`: Set this to `true` if you
want your application to control the cache options for Tyk (TTL and
whether to cache or not). See
[Caching](/docs/basic-config-and-security/reduce-latency/caching/) for
more details.
* `response_processors`: Response processors need to be specifically
defined so they are loaded on API creation, otherwise the middleware will
not fire. In order to have the two main response middleware components
fire, the following configuration object should be supplied.
```{json}
"response_processors": [
{
"name": "header_injector",
"options": {
"add_headers": {"name": "value"},
"remove_headers": ["name"]
}
},
{
"name": "response_body_transform",
"options": {}
}
]
```
The options for the `header_injector` are global, and will apply to all
outbound requests.
name: Batch Requests
- description: >
Sometimes a cache might contain stale data, or it may just need to be
cleared because of an invalid configuration. This call will purge all keys
associated with a cache on an API-by-API basis.
name: Cache Invalidation
- description: >-
Use the endpoints under this tag to manage your certificates. You can add,
delete and list certificates using these endpoints.
name: Certs
- name: CertsTag
- name: Debug
- description: |
Check health status of the Tyk Gateway and loaded APIs.
name: Health Checking
- description: |
Force restart of the Gateway or whole cluster.
name: Hot Reload
- description: >
All keys that are used to access services via Tyk correspond to a session
object that informs Tyk about the context of this particular token, like
access rules and rate/quota allowance.
name: Keys
- description: |
Manage OAuth clients, and manage their tokens
name: OAuth
- description: >
It is possible to force API quota and rate limit across all keys that
belong to a specific organisation ID. Rate limiting at an organisation
level is useful for creating tiered access levels and trial accounts.<br
/>
The Organisation rate limiting middleware works with both Quotas and Rate
Limiters. In order to manage this functionality, a simple API has been put
in place to manage these sessions. <br />
Although the Organisation session-limiter uses the same session object,
all other security keys are optional as they are not used. <br />
<h3>Managing active status</h3> <br />
To disallow access to an entire group of keys without rate limiting the
organisation, create a session object with the "is_inactive" key set to
true. This will block access before any other middleware is executed. It
is useful when managing subscriptions for an organisation group and access
needs to be blocked because of non-payment. <br />
name: Organisation Quotas
- description: >
A Tyk security policy incorporates several security options that can be
applied to an API key. It acts as a template that can override individual
sections of an API key (or identity) in Tyk.
name: Policies
- name: Schema
- description: |+
**Note: Applies only to Tyk Gateway Community Edition** <br/>
name: Tyk OAS APIs
paths:
/hello:
get:
description: >-
From v2.7.5 you can now rename the `/hello` endpoint by using the
`health_check_endpoint_name` option.
operationId: hello
responses:
'200':
content:
application/json:
example:
description: Tyk GW
details:
redis:
componentType: datastore
status: pass
time: '2020-05-19T03:42:55+01:00'
status: pass
version: v5.5.0-dev
schema:
$ref: '#/components/schemas/HealthCheckResponse'
description: Success.
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
'405':
content:
application/json:
example:
message: Method Not Allowed
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Method Not Allowed
summary: Check the Health of the Tyk Gateway.
tags:
- Health Checking
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/tyk/apis:
get:
description: List APIs from Tyk Gateway
operationId: listApis
responses:
'200':
content:
application/json:
example:
- api_id: b84fe1a04e5648927971c0557971565c
auth:
auth_header_name: authorization
definition:
key: version
location: header
name: Tyk Test API
org_id: 664a14650619d40001f1f00f
proxy:
listen_path: /tyk-api-test/
strip_listen_path: true
target_url: https://httpbin.org
use_oauth2: true
version_data:
not_versioned: true
versions:
Default:
name: Default
schema:
items:
$ref: '#/components/schemas/APIDefinition'
type: array
description: List of API definitions.
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
summary: Tyk Get List of Apis
tags: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
description: >-
Create API. A single Tyk node can have its API Definitions queried,
deleted and updated remotely. This functionality enables you to remotely
update your Tyk definitions without having to manage the files manually.
operationId: createApi
parameters:
- description: The base API which the new version will be linked to.
example: 663a4ed9b6be920001b191ae
in: query
name: base_api_id
required: false
schema:
type: string
- description: >-
The version name of the base API while creating the first version.
This doesn't have to be sent for the next versions but if it is set,
it will override base API version name.
example: Default
in: query
name: base_api_version_name
required: false
schema:
type: string
- description: The version name of the created version.
example: v2
in: query
name: new_version_name
required: false
schema:
type: string
- description: If true, the new version is set as default version.
example: true
in: query
name: set_default
required: false
schema:
type: boolean
requestBody:
content:
application/json:
example:
api_id: b84fe1a04e5648927971c0557971565c
auth:
auth_header_name: authorization
definition:
key: version
location: header
name: Tyk Test API
org_id: 664a14650619d40001f1f00f
proxy:
listen_path: /tyk-api-test/
strip_listen_path: true
target_url: https://httpbin.org
use_oauth2: true
version_data:
not_versioned: true
versions:
Default:
name: Default
schema:
$ref: '#/components/schemas/APIDefinition'
responses:
'200':
content:
application/json:
example:
action: added
key: b84fe1a04e5648927971c0557971565c
status: ok
schema:
$ref: '#/components/schemas/ApiModifyKeySuccess'
description: API created.
'400':
content:
application/json:
example:
message: Request malformed
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Bad Request
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
'500':
content:
application/json:
example:
message: file object creation failed, write error
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Internal server error.
summary: Tyk Creat an Api
tags: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/tyk/apis/{apiID}:
delete:
description: >-
Deleting an API definition will remove the file from the file store, the
API definition will NOT be unloaded, a separate reload request will need
to be made to disable the API endpoint.
operationId: deleteApi
parameters:
- description: The API ID.
example: 1bd5c61b0e694082902cf15ddcc9e6a7
in: path
name: apiID
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
action: deleted
key: 1bd5c61b0e694082902cf15ddcc9e6a7
status: ok
schema:
$ref: '#/components/schemas/ApiModifyKeySuccess'
description: API deleted.
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
'404':
content:
application/json:
example:
message: API not found
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: API not found.
'500':
content:
application/json:
example:
message: Delete failed
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Internal server error.
summary: Tyk Deleting an Api Definition With Id.
tags: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
get:
description: Get API definition from Tyk Gateway.
operationId: getApi
parameters:
- description: The API ID.
example: keyless
in: path
name: apiID
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
api_id: b84fe1a04e5648927971c0557971565c
auth:
auth_header_name: authorization
definition:
key: version
location: header
name: Tyk Test API
org_id: 664a14650619d40001f1f00f
proxy:
listen_path: /tyk-api-test/
strip_listen_path: true
target_url: https://httpbin.org
use_oauth2: true
version_data:
not_versioned: true
versions:
Default:
name: Default
schema:
$ref: '#/components/schemas/APIDefinition'
description: API definition.
headers:
x-tyk-base-api-id:
description: ID of the base API if the requested API is a version.
schema:
type: string
style: simple
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
'404':
content:
application/json:
example:
message: API not found.
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: API not found.
summary: Tyk Get Api Definition With It's Id.
tags: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
description: >-
Updating an API definition uses the same signature and object as a
`POST`, however it will first ensure that the API ID that is being
updated is the same as the one in the object being `PUT`.
Updating will completely replace the file descriptor and will not change
an API Definition that has already been loaded, the hot-reload endpoint
will need to be called to push the new definition to live.
operationId: updateApi
parameters:
- description: The API ID.
example: 1bd5c61b0e694082902cf15ddcc9e6a7
in: path
name: apiID
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
api_id: b84fe1a04e5648927971c0557971565c
auth:
auth_header_name: authorization
definition:
key: version
location: header
name: Update the API name sample
org_id: 664a14650619d40001f1f00f
proxy:
listen_path: /update-listen-path
strip_listen_path: true
target_url: https://tyk.io/api
use_oauth2: true
version_data:
not_versioned: true
versions:
Default:
name: Default
schema:
$ref: '#/components/schemas/APIDefinition'
responses:
'200':
content:
application/json:
example:
action: modified
key: 1bd5c61b0e694082902cf15ddcc9e6a7
status: ok
schema:
$ref: '#/components/schemas/ApiModifyKeySuccess'
description: API updated.
'400':
content:
application/json:
example:
message: Request malformed
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Bad Request
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
'404':
content:
application/json:
example:
message: API not found
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: API not found.
'500':
content:
application/json:
example:
message: File object creation failed, write error.
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Internal server error.
summary: Tyk Updating an Api Definition With Its Id.
tags: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/tyk/apis/{apiID}/versions:
get:
description: Listing versions of an API.
operationId: listApiVersions
parameters:
- description: The API ID.
example: keyless
in: path
name: apiID
required: true
schema:
type: string
- $ref: '#/components/parameters/SearchText'
- $ref: '#/components/parameters/AccessType'
responses:
'200':
content:
application/json:
example:
apis:
- expirationDate: ''
id: keyless
internal: false
isDefaultVersion: false
name: Tyk Test Keyless API
versionName: ''
- expirationDate: ''
id: 1f20d5d2731d47ac9c79fddf826eda00
internal: false
isDefaultVersion: true
name: Version three Api
versionName: v2
status: success
schema:
$ref: '#/components/schemas/VersionMetas'
description: API version metas.
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
'404':
content:
application/json:
example:
message: API not found
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: API not found.
summary: Tyk Listing Versions of an Api.
tags: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/tyk/apis/oas:
get:
description: List all APIs in Tyk OAS API format, from Tyk Gateway.
operationId: listApisOAS
parameters:
- description: >-
By default mode is empty which means it will return the Tyk API OAS
spec including the x-tyk-api-gateway part.
When mode=public, the Tyk OAS API spec will exclude the x-tyk-api-gateway part in the response.
example: public
in: query
name: mode
required: false
schema:
enum:
- public
type: string
responses:
'200':
content:
application/json:
examples:
oasExampleList:
$ref: '#/components/examples/oasExampleList'
schema:
items:
allOf:
- $ref: >-
https://raw.githubusercontent.com/TykTechnologies/tyk/refs/heads/master/apidef/oas/schema/3.0.json
- $ref: '#/components/schemas/XTykAPIGateway'
type: array
description: List of API definitions in Tyk OAS format.
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing key!
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Forbidden
summary: List All Apis in Tyk Oas Api Format.
tags:
- Tyk OAS APIs
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
description: Create an API with Tyk OAS API format on the Tyk Gateway.
operationId: createApiOAS
parameters:
- description: The base API which the new version will be linked to.
example: 663a4ed9b6be920001b191ae
in: query
name: base_api_id
required: false
schema:
type: string
- description: >-
The version name of the base API while creating the first version.
This doesn't have to be sent for the next versions but if it is set,
it will override base API version name.
example: Default
in: query
name: base_api_version_name
required: false
schema:
type: string
- description: The version name of the created version.
example: v2
in: query
name: new_version_name
required: false
schema:
type: string
- description: If true, the new version is set as default version.
example: true
in: query
name: set_default
required: false
schema:
type: boolean
requestBody:
content:
application/json:
example:
components:
securitySchemes:
bearerAuth:
description: The API Access Credentials
scheme: bearer
type: http
info:
description: This is a sample OAS.
title: OAS Sample
version: 1.0.0
openapi: 3.0.3
paths:
/api/sample/users:
get:
operationId: getUsers
responses:
'200':
content:
application/json:
schema:
items:
properties:
name:
type: string
type: object
type: array
description: fetched users
summary: Get users
tags:
- users
security:
- bearerAuth: []
servers:
- url: https://localhost:8080
x-tyk-api-gateway:
info:
name: user
state:
active: true
server:
listenPath:
strip: true
value: /user-test/
upstream:
url: https://localhost:8080
schema:
allOf:
- $ref: >-
https://raw.githubusercontent.com/TykTechnologies/tyk/refs/heads/master/apidef/oas/schema/3.0.json
- $ref: '#/components/schemas/XTykAPIGateway'
responses:
'200':
content:
application/json:
example:
action: added
key: e30bee13ad4248c3b529a4c58bb7be4e
status: ok
schema:
$ref: '#/components/schemas/ApiModifyKeySuccess'
description: API created.
'400':
content:
application/json:
example:
message: the payload should contain x-tyk-api-gateway
status: error
schema:
$ref: '#/components/schemas/ApiStatusMessage'
description: Bad Request
'403':
content:
application/json:
example:
message: Attempted administrative access with invalid or missing k
# --- truncated at 32 KB (262 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tyk/refs/heads/main/openapi/tyk-gateway-api-openapi.yml