The Tyk Dashboard API is a superset of the Gateway API providing programmatic access to a centralized database of API definitions, keys, policies, users, and organizations. It is the primary integration point for managing multi-team Tyk deployments and is authenticated via an access credentials header.
openapi: 3.0.3
info:
contact:
email: [email protected]
name: Tyk Technologies
url: https://tyk.io/contact
description: >
## <a name="introduction"></a> Introduction
The Tyk Dashboard API offers granular, programmatic access to a centralised
database of resources that your Tyk nodes can pull from. This API has a
dynamic user administrative structure which means the secret key that is
used to communicate with your Tyk nodes can be kept secret and access to the
wider management functions can be handled on a user-by-user and
organisation-by-organisation basis.
A common question around using a database-backed configuration is how to
programmatically add API definitions to your Tyk nodes, the Dashboard API
allows much more fine-grained, secure and multi-user access to your Tyk
cluster, and should be used to manage a database-backed Tyk node.
The Tyk Dashboard API works seamlessly with the Tyk Dashboard (and the two
come bundled together).
## <a name="security-hierarchy"></a> Security Hierarchy
The Dashboard API provides a more structured security layer to managing Tyk
nodes.
### Organisations, APIs and Users
With the Dashboard API and a database-backed Tyk setup, (and to an extent
with file-based API setups - if diligence is used in naming and creating
definitions), the following security model is applied to the management of
Upstream APIs:
* **Organisations**: All APIs are *owned* by an organisation, this is
designated by the 'OrgID' parameter in the API Definition.
* **Users**: All users created in the Dashboard belong to an organisation
(unless an exception is made for super-administrative access).
* **APIs**: All APIs belong to an Organisation and only Users that belong to
that organisation can see the analytics for those APIs and manage their
configurations.
* **API Keys**: API Keys are designated by organisation, this means an API
key that has full access rights will not be allowed to access the APIs of
another organisation on the same system, but can have full access to all
APIs within the organisation.
* **Access Rights**: Access rights are stored with the key, this enables a
key to give access to multiple APIs, this is defined by the session object
in the core Tyk API.
In order to use the Dashboard API, you'll need to get the 'Tyk Dashboard API
Access Credentials' secret from your user profile on the Dashboard UI.
The secret you set should then be sent along as a header with each Dashboard
API Request in order for it to be successful:
authorization: <your-secret>
license:
name: Mozilla Public License Version 2.0
url: https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md
title: Tyk Dashboard API
version: 5.7.1
servers:
- url: https://{tenant}
variables:
tenant:
default: localhost:8080
description: Your dashboard host
security:
- bearerAuth: []
tags:
- description: >-
Use the endpoints under this tag to manage your certificates. You can add,
delete and list certificates using these endpoints.
name: Certificates
- description: >-
The Tyk Dashboard provides a full set of analytics functions and graphs
that you can use to segment and view your API traffic and activity.
externalDocs:
description: Traffic Analytics.
url: https://tyk.io/docs/tyk-dashboard-analytics/
name: Analytics
- description: Use the endpoints in this tag to manage OAuth flow.
externalDocs:
description: OAuth Documentation
url: >-
https://tyk.io/docs/basic-config-and-security/security/authentication-authorization/oauth-2-0/
name: Oauth
- description: >
An API template is an asset managed by Tyk Dashboard that is used as the
starting point - a blueprint - from which you can create a new Tyk OAS API
definition. <br/>
Templates are used only during the creation of an API, they cannot be
applied later.
[Read more about API template assets
here](https://tyk.io/docs/product-stack/tyk-dashboard/advanced-configurations/templates/template-overview/)
externalDocs:
description: API Templates full documentation.
url: >-
https://tyk.io/docs/product-stack/tyk-dashboard/advanced-configurations/templates/template-overview/
name: Assets
- description: >
The Tyk Dashboard permission system can be extended by writing custom
rules using an Open Policy Agent (OPA). The rules engine works on top of
your Dashboard API, which means you can control not only access rules, but
also behaviour of all Dashboard APIs (except your public developer
portal) <br/>
By default the Dashboard OPA engine is turned off, and you need to
explicitly enable it via your Dashboard tyk_analytics.conf file. <br/>
You can use OPA rule to accomplish tasks like: <br/>
1. Prevent users from creating keyless APIs.
2. Assign specific categories to APIs created to certain user groups or
users.
3. Control access for individual fields. For example, do not allow
changing the API active status (e.g. deploy), unless you have a specific
permission set.
4. And many more <br/>
[Read more about Tyk Open Policy Agent
here](https://tyk.io/docs/tyk-dashboard/open-policy-agent/)
externalDocs:
description: Tyk Open Policy Agent Full Documentation.
url: https://tyk.io/docs/tyk-dashboard/open-policy-agent/
name: Open Policy Agent
- description: >
These APIs helps you get,add and delete (CRUD) a list of additional
(custom) permissions for your Dashboard users. You can use the created
additional permissions with Open Policy Agent (OPA). <br/>
Once created, a custom permission will be added to standard list of user permissions. <br/>
You can also configure these custom permissions in the
security.additional_permissions map in the Tyk Dashboard configuration
file.
You can check the [full documentation
here](https://tyk.io/docs/tyk-dashboard-api/org/permissions/).
externalDocs:
description: Additional Permissions full documentation.
url: https://tyk.io/docs/tyk-dashboard-api/org/permissions/
name: Additional Permissions
- description: Get OAS schema.
name: Schema
- description: >
Webhooks are a great way to let external applications know about the
status of a user, an API or an event that has occurred in the Tyk gateway
<br/>
You can create webhooks that you can then re-use in your API definitions
and assign to different Tyk Events such as quota violations or
rate-limiting violations.<br/>
Each webhook require a target_path (which is an absolute URL that should
be targeted by the webhook e.g https://httpbin.org/expired-keys) and a
method which can be any of GET, PUT, POST, PATCH or DELETE.<br/>
Request types that do not support an encoded body will not have the event
metadata encoded as part of the request. We would advise using POST where
possible.
name: Webhooks
- description: >-
Policies are a template that enable you to create access rules, usage
quota and rate limits that can be applied to multiple keys. They are a
useful way to manage large groups of users, and to enforce quota changes
on a global scale across any number of keys that are using a policy. When
used in conjunction with the portal, developers that enroll for API access
will be given a key that is attached to a specific policy. The policy
settings are refreshed every time a key attempts access, meaning that
updating a policy will have an effect across any keys that are attached to
it.
externalDocs:
description: Security Policies Documentation.
url: >-
https://tyk.io/docs/basic-config-and-security/security/security-policies/
name: Policies
- description: >-
When you have a large number of users and teams with different access
requirements, instead of setting permissions per user, you can create a
user group and configure the permissions for all users in the group. Note
that a user can only belong to one group.
externalDocs:
description: Manage Tyk Dashboard User Groups.
url: >-
https://tyk.io/docs/basic-config-and-security/security/dashboard/create-user-groups/
name: UserGroup
- description: >-
Users have twofold access to the dashboard: they can access both the
Dashboard API and the Dashboard itself, it is possible to generate users
that have read-only access to certain sections of the dashboard and the
underlying API. Use the endpoints in this tag to manage users.
externalDocs:
description: Manage Tyk Dashboard Users.
url: >-
https://tyk.io/docs/basic-config-and-security/security/dashboard/create-users/
name: Users
- 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.
externalDocs:
description: API Key Management.
url: https://tyk.io/docs/tyk-apis/tyk-dashboard-api/api-keys/
name: Keys
- description: >-
An API request made using Basic Authentication will have an Authorization
header that contains the API key. The value of the Authorization header
will be in the form:</br>
`Basic base64Encode(username:password)`.
externalDocs:
description: Basic Authentication.
url: >-
https://tyk.io/docs/basic-config-and-security/security/authentication-authorization/basic-auth/
name: Basic Authentication
- description: >-
Tyk allows you to work with APIs that you ve designed with the OpenAPI
Specification version 3.0.x, making it even easier to get your API up and
running. Use the endpoints in this tag to create,delete,import and update
OAS APIs.
externalDocs:
description: Tyk OAS Documentation.
url: https://tyk.io/docs/getting-started/key-concepts/high-level-concepts/
name: OAS APIs
- description: >-
Use the endpoints under this tags to update,add ,delete and fetch the
classic APIs.
name: APIs
- description: >-
The Dashboard SSO API allows you to implement custom authentication
schemes for the Dashboard and Portal. Our Tyk Identity Broker (TIB)
internally also uses this API. The Dashboard exposes the /api/sso
Dashboard API which allows you to generate a temporary authentication
token, valid for 60 seconds.
externalDocs:
description: Dashboard API Single Sign On.
url: https://tyk.io/docs/tyk-apis/tyk-dashboard-api/sso/
name: Single Sign On
- description: System API.
name: System
paths:
/api/activity/keys/{keyHash}/{startDay}/{startMonth}/{startYear}/{EndDay}/{EndMonth}/{EndYear}:
get:
description: >-
It returns analytics of the endpoints of all APIs called a key between
start and end date.
operationId: getAnalyticsOfApiKey
parameters:
- description: Day to start querying the analytics from.
example: '15'
in: path
name: startDay
required: true
schema:
type: string
- description: Month to start querying the analytics from.
example: '1'
in: path
name: startMonth
required: true
schema:
type: string
- description: Year to start querying the analytics from.
example: '2024'
in: path
name: startYear
required: true
schema:
type: string
- description: End date of analytics to query.
example: '20'
in: path
name: EndDay
required: true
schema:
type: string
- description: End month of analytics to query.
example: '6'
in: path
name: EndMonth
required: true
schema:
type: string
- description: End year of analytics to query.
example: '2025'
in: path
name: EndYear
required: true
schema:
type: string
- description: Hash of your API key.
in: path
name: keyHash
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
aggregateAnalytics:
$ref: '#/components/examples/aggregateAnalytics'
schema:
$ref: '#/components/schemas/AggregateAnalyticsData'
description: >-
Returns analytics of all endpoints called using the given key
between the given time range.
'400':
content:
application/json:
example:
Message: Key could not be decoded.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Bad Request
'401':
content:
application/json:
example:
Message: Not authorised
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Unauthorized
'403':
content:
application/json:
example:
Message: User does not have access to the API with ID.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Forbidden
'500':
content:
application/json:
example:
Message: Failed to fetch analytics.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Internal server error.
summary: Analytics of API Key.
tags:
- Analytics
/api/activity/oauthid/{OAuthClientID}/{startDay}/{startMonth}/{startYear}/{EndDay}/{EndMonth}/{EndYear}:
get:
description: >-
Returns activity of all endpoints which used the given OAuth client
between the given time range.
operationId: getAnalyticsOfOauthClientId
parameters:
- description: Day to start querying the analytics from.
example: '15'
in: path
name: startDay
required: true
schema:
type: string
- description: Month to start querying the analytics from.
example: '1'
in: path
name: startMonth
required: true
schema:
type: string
- description: Year to start querying the analytics from.
example: '2024'
in: path
name: startYear
required: true
schema:
type: string
- description: End date of analytics to query.
example: '20'
in: path
name: EndDay
required: true
schema:
type: string
- description: End month of analytics to query.
example: '6'
in: path
name: EndMonth
required: true
schema:
type: string
- description: End year of analytics to query.
example: '2025'
in: path
name: EndYear
required: true
schema:
type: string
- description: OAuthClientID
in: path
name: OAuthClientID
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
aggregateAnalytics:
$ref: '#/components/examples/aggregateAnalytics'
schema:
$ref: '#/components/schemas/AggregateAnalyticsData'
description: Fetched analytics successfully.
'401':
content:
application/json:
example:
Message: Not authorised
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Unauthorized
'403':
content:
application/json:
example:
Message: User does not have access to the API with ID.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Forbidden
'500':
content:
application/json:
example:
Message: Failed to fetch analytics.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Internal server error.
summary: Analytics of Oauth Client ID.
tags:
- Analytics
/api/apis:
get:
description: >-
Get List of APIs.By default the returned apis will be sorted by
created_at field in descending order but this can be changed via sort
query parameter.The apis returned are paginated
operationId: getApis
parameters:
- allowEmptyValue: true
deprecated: true
description: Return smaller API list payload.
example: '1'
in: query
name: compressed
required: false
schema:
enum:
- '1'
type: string
- description: API Type, internal or external.
example: rest
in: query
name: api_type
required: false
schema:
enum:
- tcp
- rest
- graphql
- udg
- subgraph
- supergraph
- internal
type: string
- description: Comma separated list of categories you want to filter Apis by.
in: query
name: category
required: false
schema:
type: string
- description: >-
Comma separated list of authentication type you want to filter apis
by.
example: keyless,authToken
in: query
name: auth_type
required: false
schema:
type: string
- allowEmptyValue: true
description: >-
For versioned APIs, return only the base versions.If any value is
sent in this query parameter only the base version will be returned
example: '1'
in: query
name: base_apis
required: false
schema:
type: string
- description: >-
Query string for search/filtering.This will return all apis whose
names matches the given pattern
example: Rate Limit Path API 1
in: query
name: q
required: false
schema:
type: string
- description: >-
Use p query parameter to say which page you want returned. Send
number less than 0 to return all items.
example: 1
in: query
name: p
required: false
schema:
type: integer
- description: |-
* 'name' - Sort by name in ascending order.
* '-name' - Sort by name in descending order.
* 'updated_at' - Sort by updated_at in ascending order.
* '-updated_at' - Sort by updated_at in descending order.
* 'created_at' - Sort by created_at in ascending order.
* '-created_at' - Sort by created_at in descending order.
example: name
in: query
name: sort
required: false
schema:
enum:
- name
- '-name'
- created_at
- '-created_at'
- updated_at
- '-updated_at'
type: string
responses:
'200':
content:
application/json:
examples:
paginatedApiExample:
$ref: '#/components/examples/paginatedApiExample'
schema:
$ref: '#/components/schemas/ApiDefinitionsResponse'
description: List of API definitions.
'400':
content:
application/json:
example:
Message: Could not retrieve APIs.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Bad Request
'401':
content:
application/json:
example:
Message: Not authorised
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Unauthorized
'403':
content:
application/json:
example:
Message: 'access denied: You do not have permission to access /api/apis'
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Forbidden
'500':
content:
application/json:
example:
Message: Failed to marshal data for APIs.
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Internal server error.
summary: Get List of APIs
tags:
- APIs
post:
description: |-
Create an API Definition in Tyk Classic API format.
Note that the response includes the newly created Tyk Classic API Definition containing the unique identifier for the APIs (`api_id`). You can provide a value for the `api_id` in the request body, otherwise Tyk will automatically generate a value for you.
The `ID` field within the Tyk Classic API Definition is a proprietary field used by Tyk to identify the API within the database and cannot be chosen or modified by the user.
operationId: postApis
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_definition:
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/ApiDefinitionWrapper'
responses:
'200':
content:
application/json:
example:
ID: 284acad18f44f3d4e9a0832ccf5fd1
Message: API created
Meta: 663cd8615715ec1405aafbea
Status: OK
schema:
$ref: '#/components/schemas/ApiResponse'
description: API created
'400':
content:
application/json:
example:
Message: version name header should be set with base API ID
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Bad Request
'401':
content:
application/json:
example:
Message: Not authorised
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Unauthorized
'403':
content:
application/json:
example:
Message: 'access denied: You do not have permission to access /api/apis'
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Forbidden
'409':
content:
application/json:
example:
Message: Found API with the same ID
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: if API with given API ID already exist
summary: Create API Definition
tags:
- APIs
/api/apis/{apiID}/access:
get:
description: >-
This will return APIAccessManagementPayload that has two lists
containing users and user groups that have access to an API.
operationId: getApiAccessRights
parameters:
- description: The API ID
example: b84fe1a04e5648927971c0557971565c
in: path
name: apiID
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
userGroupIds:
- 663a4ed6b6be920001b191aa
- 663a4ed6b6be920001b191ab
userIds:
- 663b2a835715ecb6edef24e3
- 663a5bbf5715ec8040251f2a
schema:
$ref: '#/components/schemas/AccessManagementPayload'
description: >-
APIAccessManagementPayload represents two lists containing users and
user groups that have access to an API
'401':
content:
application/json:
example:
Message: Not authorised
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Unauthorized
'403':
content:
application/json:
example:
Message: >-
access denied: You do not have permission to access
/api/apis/{apiID}/access
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Forbidden
'404':
content:
application/json:
example:
Message: API not found
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: API with this ID does not exist
'500':
content:
application/json:
example:
Message: failed to marshal ownership payload
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Internal server error.
summary: Get API access rights (users and userGroups)
tags:
- APIs
put:
description: >-
This will update the user group and users that have access to an API.The
userIds and userGroup sent will entirely replace the existing userIds
IDs and userGroup ids.
operationId: updateApiAccessRights
parameters:
- description: The API ID
example: b84fe1a04e5648927971c0557971565c
in: path
name: apiID
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
userGroupIds:
- 663a4ed6b6be920001b191aa
- 663a4ed6b6be920001b191ab
userIds:
- 663a5bbf5715ec8040251f2a
schema:
$ref: '#/components/schemas/AccessManagementPayload'
responses:
'200':
content:
application/json:
example:
Message: API access updated
Meta: null
Status: OK
schema:
$ref: '#/components/schemas/ApiResponse'
description: API access updated
'401':
content:
application/json:
example:
Message: Not authorised
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Unauthorized
'403':
content:
application/json:
example:
Message: >-
access denied: You do not have permission to access
/api/apis/{apiID}/access
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Forbidden
'404':
content:
application/json:
example:
Message: API not found
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: API with ID not found
'500':
content:
application/json:
example:
Message: failed to unmarshal categories payload
Meta: null
Status: Error
schema:
$ref: '#/components/schemas/ApiResponse'
description: Internal server error.
summary: Update API access rights (users and userGroups)
tags:
- APIs
/api/apis/{apiID}/keys:
get:
description: Lists keys that grant access to the API with the ID {apiID}.
operationId: listApiKeys
parameters:
- description: >-
Use p query parameter to say which page you want returned. Send
number less than 0 to return all items.
example: 1
in: query
name: p
required: false
schema:
type: integer
- description: ID of the API.
example: 663a4ed9b6be920001b191ae
in: path
name: apiID
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
data:
keys:
- 5e9d9544a1dcd60001d0ed20a28c495beff140a4a6d8c272a1956b99
- 5e9d9544a1dcd60001d0ed20e7f75f9e03534825b7aef9df749582e5
- 5e9d9544a1dcd60001d0ed2060ff87c0deab4a508dd2ac18ccb8b664
pages: 1
schema:
$ref: '#/components/schemas/Keys'
description: Pagina
# --- truncated at 32 KB (424 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tyk/refs/heads/main/openapi/tyk-dashboard-api-openapi.yml