Dashboard Configuration

Introduction

The Tyk Dashboard is a powerful web-based interface that serves as the central management hub for your API ecosystem. It provides a user-friendly Graphical User Interface (GUI) for configuring, monitoring, and analyzing your APIs managed by Tyk.

The Dashboard also exposes a REST API, allowing for programmatic control and integration with other tools and workflows.

This page introduces general features of dashboard and how to configure them. If you are looking for global configurations of the Dashboard deployment refer this config file.

We will delve into the following key topics:

1. Exploring the Dasbhoard UI: A tour of the Dashboard UI.

2. Exploring the Dasbhoard API: Explore the Dashboard APIs, including their classification, authentication methods, and usage examples with Swagger and Postman collections.

3. API Management using API Endpoint Designer: A graphical environment for configuring your Tyk APIs.

4. Monitoring and Traffic Analytics: Exploration of Tyk’s traffic analytics capabilities, including logging mechanisms, error tracking, endpoint analysis, and various activity type measurements.

5. API Governance using API Templates and API Categories

6. System Management: Detailed overview of Tyk’s system management capabilities, including Admin API functionalities, organization management and configuting audit logs.

7. Supported Database: We will examine Dashboard’s storage requirement, compatible database versions and how to configure them.

8. Exploring Data Storage Solution: We will explore Dashboard’s multi-layered storage architecture and understand how to configure each storage tier effectively.

Exploring the Dashboard UI

To get a tour of the Dashboard UI, refer to this document.

Exploring the Dashboard API

The Dashboard is a large, granular REST API with a thin-client web front-end, and if being deployed as part of a Tyk install, serves as the main integration point instead of the Gateway API.

The Dashboard API is a superset of the Gateway API, providing the same functionality, with additional features (anything that can be done in the Dashboard has an API endpoint), and offers some additional advantages:

• The Dashboard API has a granular structure, you can create separate clients easily.
• The API features read/write permissions on a per-endpoint level to have extra control over integrations.
• The API enforces a schema that can be modified and hardened depending on your usage requirements.

Types of Dashboard API

The Dashboard exposes two APIs:

• Dashboard API: Is used for operational management of Tyk resources (APIs, policies, keys, etc.). This API offers granular permissions based on user roles.

  To know more about Dashboard APIs, refer the following documents:

  • Postman / Swagger / Open API specification
  • Dashboard API Usage Examples

• Dashboard Admin API: Is used for system-level administration and initial setup tasks like managing organizations, initial user creation, backups/migrations and SSO setup.

  To know more about Dashboard Admin APIs, refer the following documents:

  • Postman / Swagger / Open API specification
  • Dashboard Admin API Usage Examples

Authenticating with Dashboard APIs

Dashboard API

The Tyk Dashboard API is secured using an Authorization header that must be added to each request that is made. The Tyk Dashboard API Access Credentials Authorization key can be found within the Dashboard UI at the bottom of the Edit User section for a user.

Dashboard Admin API

The Tyk Dashboard Admin API is secured using a shared secret that is set in the tyk_analytics.conf file. Calls to the Admin API require the admin-auth header to be provided, to differentiate the call from a regular Dashboard API call.

Dashboard API Resources and Usage

Overview

The Tyk Dashboard API is a superset of the Tyk Gateway API, enabling (almost) all of the core features and adding many more. The Dashboard API is also more granular and supports Role Based Access Control (RBAC) on both a multi-tenant, and user basis.

Using the Dashboard API it is possible to set Read / Write / ReadWrite / Deny access to sections of the API on a user by user basis, and also segregate User / Key / API Ownership by organization.

The availability of RBAC varies depending on the license or subscription. For further information, please check our price comparison or consult our sales and expert engineers Contact us

Pagination

Selected Dashboard APIs can be paginated.

You can select the number of result pages to return by adding a parameter p which starts at 1. At the default page size, this returns items 1-10. Setting p to 2 returns items 11-20 and so on. Alternatively, passing 0 or lower as a parameter will return all items.

The default page size is 10. You can overwrite the default page size in your tyk_analytics.conf using the page_size key. It’s suggested you do not modify it as it will affect the performance of the Dashboard.

Sample Request:

GET /api/apis/?p=1 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response:

{
  "apis": [
    { ... },
    { ... },
    { ... }
  ],
  "pages": 1
}

Manage APIs - API Definition

Get List of APIs

Sample Request

GET /api/apis?p=0 HTTP/1.1
Host: localhost:3000
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "apis": [
    {
      "api_model": {},
      "api_definition": {
        "id": "54b53e47eba6db5c70000002",
        "name": "Nitrous Test",
        "api_id": "39d2c98be05c424371c600bd8b3e2242",
        "org_id": "54b53d3aeba6db5c35000002",
        "use_keyless": false,
        "use_oauth2": false,
        "oauth_meta": {
          "allowed_access_types": [],
          "allowed_authorize_types": [
            "token"
          ],
            "auth_login_redirect": ""
        },
        "auth": {
          "auth_header_name": "authorization"
        },
        "use_basic_auth": false,
        "notifications": {
          "shared_secret": "",
          "oauth_on_keychange_url": ""
        },
        "enable_signature_checking": false,
        "definition": {
          "location": "header",
          "key": ""
        },
        "version_data": {
          "not_versioned": true,
          "versions": {
            "Default": {
              "name": "Default",
              "expires": "",
              "paths": {
                "ignored": [],
                "white_list": [],
                "black_list": []
              },
              "use_extended_paths": false,
              "extended_paths": {
                "ignored": [],
                "white_list": [],
                "black_list": []
              }
            }
          }
        },
        "proxy": {
          "listen_path": "/39d2c98be05c424371c600bd8b3e2242/",
          "target_url": "http://tyk.io",
          "strip_listen_path": true
        },
        "custom_middleware": {
          "pre": null,
          "post": null
        },
        "session_lifetime": 0,
        "active": true,
        "auth_provider": {
          "name": "",
          "storage_engine": "",
          "meta": null
        },
        "session_provider": {
          "name": "",
          "storage_engine": "",
          "meta": null
        },
        "event_handlers": {
          "events": {}
        },
        "enable_batch_request_support": false,
        "enable_ip_whitelisting": false,
        "allowed_ips": [],
        "expire_analytics_after": 0
      },
      "hook_references": []
    }
    ...
  ],
  "pages": 0
}

Search APIs by name

Sample Request

GET /api/apis?q=Some+Name HTTP/1.1
Host: localhost:3000
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

Similar to API list response

Retrieve a single API by ID

Sample request

GET /api/apis/54c24242eba6db1c9a000002 HTTP/1.1
Host: localhost
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "api_model": {},
  "api_definition": {
    "id": "54c24242eba6db1c9a000002",
    "name": "Test",
    "api_id": "bc2f8cfb7ab241504d9f3574fe407499",
    "org_id": "54b53d3aeba6db5c35000002",
    "use_keyless": false,
    "use_oauth2": false,
    "oauth_meta": {
      "allowed_access_types": [],
      "allowed_authorize_types": [
          "token"
      ],
      "auth_login_redirect": ""
    },
    "auth": {
      "auth_header_name": "authorization"
    },
    "use_basic_auth": false,
    "notifications": {
      "shared_secret": "",
      "oauth_on_keychange_url": ""
    },
    "enable_signature_checking": false,
    "definition": {
      "location": "header",
      "key": ""
    },
    "version_data": {
        "not_versioned": true,
        "versions": {
          "Default": {
            "name": "Default",
            "expires": "",
            "paths": {
              "ignored": [],
              "white_list": [],
              "black_list": []
            },
            "use_extended_paths": true,
            "extended_paths": {
              "ignored": [
                  {
                    "path": "/test-path/",
                    "method_actions": {
                      "GET": {
                        "action": "no_action",
                        "code": 200,
                        "data": "",
                        "headers": {}
                      }
                    }
                  },
                  {
                    "path": "/test-path/reply",
                    "method_actions": {
                      "GET": {
                        "action": "reply",
                        "code": 200,
                        "data": "{\"foo\":\"bar\"}",
                        "headers": {
                          "x-test": "test"
                        }
                      }
                    }
                  }
              ],
              "white_list": [],
              "black_list": []
            }
          }
        }
      },
      "proxy": {
        "listen_path": "/bc2f8cfb7ab241504d9f3574fe407499/",
        "target_url": "http://httpbin.org/",
        "strip_listen_path": true
      },
      "custom_middleware": {
        "pre": [],
        "post": []
      },
      "session_lifetime": 0,
      "active": true,
      "auth_provider": {
        "name": "",
        "storage_engine": "",
        "meta": null
      },
      "session_provider": {
        "name": "",
        "storage_engine": "",
        "meta": null
      },
      "event_handlers": {
        "events": {
          "QuotaExceeded": [
            {
              "handler_name": "eh_web_hook_handler",
              "handler_meta": {
                "_id": "54be6c0beba6db07a6000002",
                "event_timeout": 60,
                "header_map": {
                    "x-tyk-test": "123456"
                },
                "method": "POST",
                "name": "Test Post",
                "org_id": "54b53d3aeba6db5c35000002",
                "target_path": "http://httpbin.org/post",
                "template_path": ""
              }
            }
          ]
        }
      },
      "enable_batch_request_support": true,
      "enable_ip_whitelisting": true,
      "allowed_ips": [
        "127.0.0.1"
      ],
      "expire_analytics_after": 0
  },
  "hook_references": [
    {
        "event_name": "QuotaExceeded",
        "event_timeout": 60,
        "hook": {
          "api_model": {},
          "id": "54be6c0beba6db07a6000002",
          "org_id": "54b53d3aeba6db5c35000002",
          "name": "Test Post",
          "method": "POST",
          "target_path": "http://httpbin.org/post",
          "template_path": "",
          "header_map": {
            "x-tyk-test": "123456"
          },
          "event_timeout": 0
      }
    }
  ]
}

Delete API by ID

Sample Request

DELETE /api/apis/54c24242eba6db1c9a000002 HTTP/1.1
Host: localhost
Authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{"Status":"OK","Message":"API deleted","Meta":null}

Create API Definition

Creating API definitions is slightly different to the core API, API definitions are wrapped inside an api_definition field and event handlers, such as webhooks are not embedded in the main api_defintion object (though they can be), webhooks are instead appended as references into the hook_references field, the API will embed the correct webhook data into the event handler interface.

Please note that ID’s (both id and api_id) are auto-generated by Tyk and cannot be set by the user. In Self-Managed installations api_id can be overwritten with a call to the Update API Definition endpoint, but this is currently not possible when the Dashboard resides in Tyk Cloud.

Sample Request

POST /api/apis HTTP/1.1
Host: localhost:3000
Connection: keep-alive
Content-Type: application/json
Content-Length: 1356
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "api_definition": {
      "name": "Test",
      "auth": {
          "auth_header_name": "authorization"
      },
      "definition": {
          "location": "header",
          "key": ""
      },
      "proxy": {
          "target_url": "http://httpbin.org/"
      },
      "version_data": {
        "use_extended_paths": true,
        "not_versioned": true,
        "versions": {
          "Default": {
              "expires": "",
              "name": "Default",
              "paths": {
                "ignored": [],
                "white_list": [],
                "black_list": []
              },
              "extended_paths": {
                "ignored": [
                  {
                    "path": "/test-path/",
                    "method_actions": {
                      "GET": {
                        "action": "no_action",
                        "code": 200,
                        "data": "",
                        "headers": {}
                      }
                    }
                  },
                    {
                      "path": "/test-path/reply",
                      "method_actions": {
                        "GET": {
                          "action": "reply",
                          "code": 200,
                          "data": "{\"foo\":\"bar\"}",
                          "headers": {
                            "x-test": "test"
                          }
                        }
                      }
                    }
                ],
                  "white_list": [],
                  "black_list": []
              },
              "use_extended_paths": true
          }
        }
      },
      "use_oauth2": false,
      "oauth_meta": {
        "auth_login_redirect": "",
        "allowed_access_types": [],
        "allowed_authorize_types": [
          "token"
        ]
      },
      "notifications": {
        "shared_secret": "",
        "oauth_on_keychange_url": ""
      },
      "enable_ip_whitelisting": true,
      "allowed_ips": [
        "127.0.0.1"
      ],
      "use_keyless": false,
      "enable_signature_checking": false,
      "use_basic_auth": false,
      "active": true,
      "enable_batch_request_support": true
  },
  "hook_references": [
    {
      "event_name": "QuotaExceeded",
      "hook": {
        "api_model": {},
        "id": "54be6c0beba6db07a6000002",
        "org_id": "54b53d3aeba6db5c35000002",
        "name": "Test Post",
        "method": "POST",
        "target_path": "http://httpbin.org/post",
        "template_path": "",
        "header_map": {
          "x-tyk-test": "123456"
        },
        "event_timeout": 0
      },
      "event_timeout": 60
    }
  ]
}

Sample Response

{
  "Status": "OK",
  "Message": "API created",
  "Meta": "54c24242eba6db1c9a000002"
}

Please note that Tyk matches the Ignored paths in the order in which they are specified in the ignored array. Subpaths of a route are matched automatically and so should be placed above parent routes if they need to be matched individually.

Update API Definition

APIs that are created using the advanced Dashboard API are referenced by their internal ID instead of their API-ID.

Please note that whilst api_id can be updated for Self-Managed installations, this is currently not possible when the Dashboard resides in Tyk Cloud. Updates to api_id in Tyk Cloud will be ignored.

Sample Request

PUT /api/apis/54c24242eba6db1c9a000002 HTTP/1.1
Host: localhost:3000
Connection: keep-alive
Content-Type: application/json
Content-Length: 1356
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "api_definition": {
      "id": "54c24242eba6db1c9a000002",
      "api_id": "bc2f8cfb7ab241504d9f3574fe407499",
      "name": "Test",
      "auth": {
        "auth_header_name": "authorization"
      },
      "definition": {
        "location": "header",
        "key": ""
      },
      "proxy": {
          "target_url": "http://httpbin.org/"
      },
      "version_data": {
        "use_extended_paths": true,
        "not_versioned": true,
        "versions": {
          "Default": {
            "expires": "",
            "name": "Default",
            "paths": {
              "ignored": [],
              "white_list": [],
              "black_list": []
            },
            "extended_paths": {
              "ignored": [
                  {
                    "path": "/test-path/",
                    "method_actions": {
                      "GET": {
                        "action": "no_action",
                        "code": 200,
                        "data": "",
                        "headers": {}
                      }
                    }
                  },
                  {
                    "path": "/test-path/reply",
                    "method_actions": {
                      "GET": {
                        "action": "reply",
                        "code": 200,
                        "data": "{\"foo\":\"bar\"}",
                        "headers": {
                            "x-test": "test"
                        }
                      }
                    }
                  }
              ],
              "white_list": [],
              "black_list": []
              },
            "use_extended_paths": true
          }
        }
      },
        "use_oauth2": false,
        "oauth_meta": {
          "auth_login_redirect": "",
          "allowed_access_types": [],
          "allowed_authorize_types": [
            "token"
          ]
        },
        "notifications": {
          "shared_secret": "",
          "oauth_on_keychange_url": ""
        },
        "enable_ip_whitelisting": true,
        "allowed_ips": [
          "127.0.0.1"
        ],
        "use_keyless": false,
        "enable_signature_checking": false,
        "use_basic_auth": false,
        "active": true,
        "enable_batch_request_support": true
    },
    "hook_references": [
      {
        "event_name": "QuotaExceeded",
        "hook": {
          "api_model": {},
          "id": "54be6c0beba6db07a6000002",
          "org_id": "54b53d3aeba6db5c35000002",
          "name": "Test Post",
          "method": "POST",
          "target_path": "http://httpbin.org/post",
          "template_path": "",
          "header_map": {
            "x-tyk-test": "123456"
          },
          "event_timeout": 0
        },
        "event_timeout": 60
      }
    ]
}

Sample Response

{
  "Status": "OK",
  "Message": "Api updated",
  "Meta": ""
}

Data Graphs API

Currently /api/data-graphs/ has only one endpoint called /data-sources with only a POST HTTP method.

The Dashboard exposes the /api/data-graphs/data-sources/import endpoint which allows you to import an AsyncAPI or OpenAPI document.

Supported AsyncAPI versions

• 2.0.0
• 2.1.0
• 2.2.0
• 2.3.0
• 2.4.0

Supported OpenAPI versions

• 3.0.0

Import a document from a remote resource

The fetched document can be an OpenAPI or AsyncAPI document. The format will be detected automatically. The data source import API only checks the fetched data and tries to determine the document format, the status codes are ignored. It returns an error if it fails to determine the format and the document type. HTTP 500 is returned if a programming or network error occurs. If the fetched request body is malformed then HTTP 400 is returned.

Import an OpenAPI document

The data source import API supports importing OpenAPI documents. The document can be used as a request body.

The document can be in JSON or YAML format. The import API can determine the type and parse it.

Import an AsyncAPI document

The data source import API supports importing AsyncAPI documents. The document can be used as a request body.

The document can be in JSON or YAML format. The import API can determine the type and parse it.

Response Structure

The response structure is consistent with other endpoints, as shown in the table below:

Sample Response

{
    "Status": "OK",
    "Message": "Data source imported",
    "Meta": "64102568f2c734bd2c0b8f99"
}

Analytics API

Analytics of API Key

It returns analytics of the endpoints of all APIs called using KEY between start and end date.

Sample Request To get analytics of all endpoints called using the key 7f3c3ca87376cabe between October 13th 2020 and October 14th 2020, make the following call:

GET api/activity/keys/endpoint/7f3c3ca87376cabe/13/10/2020/14/10/2020 HTTP/1.1
Host: localhost:3000
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
    "data": [
        {
            "id": {
                "day": 0,
                "month": 0,
                "year": 0,
                "hour": 0,
                "code": 0,
                "path": "/anything",
                "key": "",
                "alias": "",
                "url": "",
                "iso_country": "",
                "api_id": "41351a6a94094da05f75146a695a16f6",
                "api_name": ""
            },
            "hits": 1,
            "success": 1,
            "error": 0,
            "last_hit": "2020-10-13T13:22:49.667+05:30",
            "request_time": 0,
            "latency": 217,
            "upstream_latency": 217,
            "max_upstream_latency": 217,
            "min_upstream_latency": 217,
            "max_latency": 217,
            "min_latency": 217
        },
        {
            "id": {
                "day": 0,
                "month": 0,
                "year": 0,
                "hour": 0,
                "code": 0,
                "path": "/anything",
                "key": "",
                "alias": "",
                "url": "",
                "iso_country": "",
                "api_id": "1793db2cbb724ad54da582ce3191d383",
                "api_name": ""
            },
            "hits": 1,
            "success": 1,
            "error": 0,
            "last_hit": "2020-10-13T13:22:20.534+05:30",
            "request_time": 568,
            "latency": 568,
            "upstream_latency": 568,
            "max_upstream_latency": 568,
            "min_upstream_latency": 568,
            "max_latency": 568,
            "min_latency": 568
        },
    ],
    "pages": 1
}

Analytics of OAuth Client

It returns analytics of the all endpoints called using the given OAuth Client ID.

Sample Request To get activity of all endpoints which used OAuth client 27b35a9ed46e429eb2361e440cc4005c between October 13th 2020 and October 14th 2020, make the following call:

GET /api/activity/oauthid/endpoint/27b35a9ed46e429eb2361e440cc4005c/13/10/2020/14/10/2020 HTTP/1.1
Host: localhost:3000
authorization: 7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
    "data": [
        {
            "id": {
                "day": 0,
                "month": 0,
                "year": 0,
                "hour": 0,
                "code": 0,
                "path": "/get",
                "key": "",
                "alias": "",
                "url": "",
                "iso_country": "",
                "api_id": "79fc7cb80df940cc5089772200bd4926",
                "api_name": ""
            },
            "hits": 2,
            "success": 1,
            "error": 1,
            "last_hit": "2020-10-13T14:48:51.582+05:30",
            "request_time": 498,
            "latency": 498,
            "upstream_latency": 497.5,
            "max_upstream_latency": 747,
            "min_upstream_latency": 248,
            "max_latency": 748,
            "min_latency": 248
        },
        {
            "id": {
                "day": 0,
                "month": 0,
                "year": 0,
                "hour": 0,
                "code": 0,
                "path": "/post",
                "key": "",
                "alias": "",
                "url": "",
                "iso_country": "",
                "api_id": "79fc7cb80df940cc5089772200bd4926",
                "api_name": ""
            },
            "hits": 1,
            "success": 1,
            "error": 0,
            "last_hit": "2020-10-13T14:49:31.541+05:30",
            "request_time": 0,
            "latency": 241,
            "upstream_latency": 239,
            "max_upstream_latency": 239,
            "min_upstream_latency": 239,
            "max_latency": 241,
            "min_latency": 241
        }
    ],
    "pages": 1
}

Users API

List Users

Sample Request

GET /api/users HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "users": [
    {
      "api_model": {},
      "first_name": "John",
      "last_name": "Smith",
      "email_address": "[email protected]",
      "password": "$2a$10$mRVfrAf72N66anVNhA1KVuYaOwOrXhFzxyg6bwgZemUeVo2MNOpIa",
      "org_id": "54b53d3aeba6db5c35000002",
      "active": true,
      "id": "54b53d4bf25b920f09361526",
      "access_key": "0cf5e6c37add465a406f19807c081765",
      "user_permissions": {
                "IsAdmin": "admin",
                "ResetPassword": "admin"
      }
    },
    {
      "api_model": {},
      "first_name": "Test",
      "last_name": "User",
      "email_address": "[email protected]",
      "password": "",
      "org_id": "54b53d3aeba6db5c35000002",
      "active": true,
      "id": "54bd0ad9ff4329b88985aafb",
      "access_key": "f81ee6f0c8f2467d539c132c8a422346",
      "user_permissions": {
                "user_groups": "read",
                "users": "read"
      }
    }
  ],
  "pages": 0
}

Get User

Sample Request

GET /api/users/54bd0ad9ff4329b88985aafb HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "api_model": {},
  "first_name": "Test",
  "last_name": "User",
  "email_address": "[email protected]",
  "password": "",
  "org_id": "54b53d3aeba6db5c35000002",
  "active": true,
  "id": "54bd0ad9ff4329b88985aafb",
  "access_key": "f81ee6f0c8f2467d539c132c8a422346"
}

Add User

You need to have the users Permission object set to write to use Add User.

If you do set a password, you need to keep a record of it, to enable the password to be reset in the future.

Sample Request

POST /api/users HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "first_name": "Jason",
  "last_name": "Jasonson",
  "email_address": "[email protected]",
  "active": true,
  "password": "thisisatest",
  "user_permissions": { "IsAdmin": "admin" }
}

Sample Response

{
  "Status": "OK",
  "Message": "User created",
  "Meta": ""
}

Set User Password

If a user is created with a blank password, you will need to add a password in a second API call to set a password. In this scenario, the current_password field is not required. To change an current password, you need to know the existing password set in Add User.

You need to have the users Permission object set to read to use Set User Password.

Sample Request

POST /api/users/54c25e845d932847067402e2/actions/reset HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "current_password": "12345",
  "new_password":"test123456",
  "user_permissions": { "IsAdmin": "admin" }
}

Sample Response

{
  "Status": "OK",
  "Message": "User password updated",
  "Meta": ""
}

Allow Reset Password

Sample Request

PUT -H "admin-auth: <your secret>" http://<dashboard>/admin/users/{USER_ID}/actions/allow_reset_passwords

Sample Response

{
  "Status": "OK",
  "Message": "User updated",
  "Meta": 
    { …user object payload …}
}

Disallow Reset Password

Sample Request

PUT -H "admin-auth: <your secret>" http://<dashboard>/admin/users/{USER_ID}/actions/disallow_reset_passwords

Sample Response

{
  "Status": "OK",
  "Message": "User updated",
  "Meta": 
    { …user object payload …}
}

Update User

You need to have the users Permission object set to write to use Update User.

Sample Request

PUT /api/users/54c25e845d932847067402e2 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "first_name": "Jason",
  "last_name": "File",
  "email_address": "[email protected]",
  "active": true,
  "user_permissions": { "IsAdmin": "admin" }
}

Sample Response

{
  "Status": "OK",
  "Message": "User updated",
  "Meta": null
}

Reset User Session

This call allows you to reset a user’s current Dashboard session.

You need to have the users Permission object set to write to use this call.

Sample Request

PUT /api/users/54c25e845d932847067402e2/actions/key/reset HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
{
  "userId":"{USER_ID}"
}

Sample Response

{
  "Status":"OK",
  "Message":"User session renewed",
  "Meta":null
}

Delete User

Sample Request

DELETE /api/users/54c25e845d932847067402e2 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "Status": "OK",
  "Message": "User deleted",
  "Meta": ""
}

User Groups API

List User Groups

Sample Request

GET /api/usergroups HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "groups": [
    {
      "org_id": "54b53d3aeba6db5c35000002",
      "id": "54b53d4bf25b920f09361526",
      "name": "Analytics team",
      "description": "Only access to analytics pages",
      "active": true,
      "user_permissions": { "analytics": "read" }
    },
    {
      "org_id": "54b53d3aeba6db5c35000003",
      "id": "54b53d4bf25b920f09361527",
      "name": "Certificates team",
      "description": "Team to manage certificates",
      "active": true,
      "user_permissions": { "certificates": "write" }
    }
  ],
  "pages": 0
}

Get User Group

Sample Request

GET /api/usergroups/54bd0ad9ff4329b88985aafb HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "org_id": "54b53d3aeba6db5c35000002",
  "id": "54b53d4bf25b920f09361526",
  "name": "Certificates team",
  "description": "Team to manage certificates",
  "active": true,
  "user_permissions": { "certificates": "write" }  
}

Add User Group

Sample Request

POST /api/usergroups HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "name": "Logs team",
  "description": "Logs team description",
  "user_permissions": { "logs": "read" }
}

Sample Response

{
  "Status": "OK",
  "Message": "User group created",
  "Meta": ""
}

Update User Group

Sample Request

PUT /api/usergroups/54c25e845d932847067402e2 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "name": "Certificates Team 2",
  "description": "Another certificates team",
}

Sample Response

{
  "Status": "OK",
  "Message": "User group updated",
  "Meta": null
}

Delete User Group

Sample Request

DELETE /api/usergroups/54c25e845d932847067402e2 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "Status": "OK",
  "Message": "User group deleted",
  "Meta": ""
}

Additional Permissions API

List Additional Permissions

This API returns by default the initial set of additional permissions defined in your Tyk Dashboard configuration, under security.additional_permissions.

Once you update the permissions via the API, they will be stored at organization level.

Sample Request

GET /api/org/permissions HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "additional_permissions": {
    "api_developer": "API Developer",
    "api_manager": "API Manager"
  }
}

Add/Delete/Update Additional Permission

Sample Request

Let’s imagine we have already defined two additional permissions: api_developer and api_manager. In order to add a new permission to this list, just send an updated list of permissions by appending the values you want. In this example we will add a custom_permission permission.

PUT /api/org/permissions HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "additional_permissions": {
    "api_developer": "API Developer",
    "api_manager": "API Manager",
    "custom_permission": "Custom Permission"
  }
}

Sample Response

{
  "Status": "OK",
  "Message": "Additional Permissions updated in org level",
  "Meta": null
}

Access Keys Management API

Get a list of Keys

Note: This will not work with a hashed key set.

Sample Request:

GET /api/apis/39d2c98be05c424371c600bd8b3e2242/keys HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response:

{
  "data": {
    "keys": [
      "54b53d3aeba6db5c3500000289a8fbc2bbba4ebc4934bb113588c792",
      "54b53d3aeba6db5c3500000230459d8568ec4bbf675bda2ff05e9293",
      "54b53d3aeba6db5c35000002ec9a2b1aca7b495771273a0895cb3627",
      "54b53d3aeba6db5c3500000272d97a10538248e9523ca09e425090b8",
      "54b53d3aeba6db5c3500000252b5c56c61ad42fe765101f6d70cf9c6"
    ]
  },
  "pages": 0
}

Get a specific key

Sample Request

GET /api/apis/39d2c98be05c424371c600bd8b3e2242/keys/54b53d3aeba6db5c3500000289a8fbc2bbba4ebc4934bb113588c792 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response:

{
  "api_model": {},
  "key_id": "54b53d3aeba6db5c3500000289a8fbc2bbba4ebc4934bb113588c792",
  "data": {
    "last_check": 1421674410,
    "allowance": 1000,
    "rate": 1000,
    "per": 60,
    "expires": 1423684135,
    "quota_max": -1,
    "quota_renews": 1421164189,
    "quota_remaining": -1,
    "quota_renewal_rate": 60,
    "access_rights": {
      "39d2c98be05c424371c600bd8b3e2242": {
        "api_name": "Nitrous Test",
        "api_id": "39d2c98be05c424371c600bd8b3e2242",
        "versions": [
          "Default"
        ]
      }
    },
    "org_id": "54b53d3aeba6db5c35000002",
    "oauth_client_id": "",
    "basic_auth_data": {
      "password": ""
    },
    "hmac_enabled": true,
    "hmac_string": ""
  }
}

Create a custom key

Sample Request

POST /api/keys/my-custom-key HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
    "apply_policies": ["5ecc0b91081ac40001ed261c"],
    "org_id" : "5eb06f441fe4c4000147476e",
    
    // Below gets overwritten by the Policy, required nonetheless
    "expires": 0,
    "allowance": 0,
    "per": 0,
    "quota_max": 0,
    "rate": 0,
    "access_rights": {
        "b742100081764ff06b00f75733145614": {
            "api_name": "",
            "api_id": "b742100081764ff06b00f75733145614",
            "versions": [
                "Default"
            ]
        }
    }
}

You might be wondering why access_rights is necessary, as we are adding a security policy and inheriting the access rights from there. That’s because of legacy functionality. We need to add any APIs api_id to the key of the access_rights map, as well as the api_id value of that key. This will all get overwritten by the policy, but we need to add it.

Sample Response:

{
    "api_model": {},
    "key_id": "eyJvcmciOiI1ZTlkOTU0NGExZGNkNjAwMDFkMGVkMjAiLCJpZCI6ImhlbGxvLXdvcmxkIiwiaCI6Im11cm11cjY0In0=",
    "data": {
       ...
    },
    "key_hash": "567b9a5419c3a9ef"
}

You can now use my-custom-key as a key to access the API. Furthermore, you can use it to lookup the key in the Dashboard as well as the generated key_hash in the response.

Let’s try curling it:

$ curl localhost:8080/my-api/users/1 --header "Authorization: my-custom-key"
{
  "response" : "hello world"
}

Generate a key

Sample Request

POST /api/keys HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "last_check": 0,
  "allowance": 1000,
  "rate": 1000,
  "per": 60,
  "expires": 0,
  "quota_max": 10000,
  "quota_renews": 1424543479,
  "quota_remaining": 10000,
  "quota_renewal_rate": 2520000,
  "access_rights": {
    "bc2f8cfb7ab241504d9f3574fe407499": {
      "api_id": "bc2f8cfb7ab241504d9f3574fe407499",
      "api_name": "Test",
      "versions": [
        "Default"
      ]
    }
  }
}

Sample Response:

{
  "api_model": {},
  "key_id": "54b53d3aeba6db5c3500000216d056646b4b4ffe4e54f5b07d658f8a",
  "data": {
    "last_check": 0,
    "allowance": 1000,
    "rate": 1000,
    "per": 60,
    "expires": 0,
    "quota_max": 10000,
    "quota_renews": 1424543479,
    "quota_remaining": 10000,
    "quota_renewal_rate": 2520000,
    "access_rights": {
      "bc2f8cfb7ab241504d9f3574fe407499": {
        "api_name": "Test",
        "api_id": "bc2f8cfb7ab241504d9f3574fe407499",
        "versions": [
          "Default"
        ]
      }
    },
    "org_id": "54b53d3aeba6db5c35000002",
    "oauth_client_id": "",
    "basic_auth_data": {
      "password": ""
    },
    "hmac_enabled": false,
    "hmac_string": ""
  }
}

Update a key

Sample Request

PUT /api/apis/39d2c98be05c424371c600bd8b3e2242/keys/54b53d3aeba6db5c3500000272d97a10538248e9523ca09e425090b8 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "last_check": 0,
  "allowance": 1000,
  "rate": 1000,
  "per": 60,
  "expires": 1422113671,
  "quota_max": -1,
  "quota_renews": 1421675253,
  "quota_remaining": -1,
  "quota_renewal_rate": 60,
  "access_rights": {
    "39d2c98be05c424371c600bd8b3e2242": {
      "api_id": "39d2c98be05c424371c600bd8b3e2242",
      "api_name": "Nitrous Test",
      "versions": [
        "Default"
      ]
    }
  },
  "org_id": "54b53d3aeba6db5c35000002",
  "oauth_client_id": "",
  "basic_auth_data": {
    "password": ""
  },
  "hmac_enabled": false,
  "hmac_string": ""
}

Sample Response:

{
  "Status": "OK",
  "Message": "Key updated",
  "Meta": ""
}

Delete a key

Sample Request

DELETE /api/apis/39d2c98be05c424371c600bd8b3e2242/keys/54b53d3aeba6db5c3500000272d97a10538248e9523ca09e425090b8 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response:

{
  "Status": "OK",
  "Message": "Key deleted succesfully",
  "Meta": ""
}

Graphql API

Presently, the Tyk Dashboard uses the GraphQL API for keys.

Basic Authentication API

Basic Auth users are essentially a form of API token, just with a customized, pre-set organization-specific ID instead of a generated one. To interact with basic auth users, you can use the API Token API calls (list, get delete etc.)

Create a user

Sample Request

POST /api/apis/keys/basic/test-user HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "last_check": 0,
  "allowance": 1000,
  "rate": 1000,
  "per": 60,
  "expires": 0,
  "quota_max": 10000,
  "quota_renews": 1424543479,
  "quota_remaining": 10000,
  "quota_renewal_rate": 2520000,
  "access_rights": {
    "bc2f8cfb7ab241504d9f3574fe407499": {
      "api_id": "bc2f8cfb7ab241504d9f3574fe407499",
      "api_name": "Test",
      "versions": [
          "Default"
      ]
    }
  },
  "basic_auth_data": {
    "password": "test123"
  }
}

Sample Response

{
  "api_model": {},
  "key_id": "54b53d3aeba6db5c3500000test-user",
  "data": {
    "last_check": 0,
    "allowance": 1000,
    "rate": 1000,
    "per": 60,
    "expires": 0,
    "quota_max": 10000,
    "quota_renews": 1424543479,
    "quota_remaining": 10000,
    "quota_renewal_rate": 2520000,
    "access_rights": {
      "bc2f8cfb7ab241504d9f3574fe407499": {
        "api_name": "Test",
        "api_id": "bc2f8cfb7ab241504d9f3574fe407499",
        "versions": [
          "Default"
        ]
      }
    },
    "org_id": "54b53d3aeba6db5c35000002",
    "oauth_client_id": "",
    "basic_auth_data": {
        "password": ""
    },
    "hmac_enabled": false,
    "hmac_string": ""
  }
}

OAuth Key Management API

Create a new OAuth2.0 Client

Any OAuth keys must be generated under an API in the Dashboard. Any POST requests made should contain the API’s ID in the URL.

Sample Request

  curl -vX POST -H "Authorization: {{API Access Credentials}}" \
    -H "Content-Type: application/json" \
    -d '{"redirect_uri": "", "policy_id": "{{policy_id}}"}' http://{{dasboard-hostname}}/api/apis/oauth/{{api-id}}

Sample Response

{
  "client_id": "72083e90e9b044c57e2667d49effff78",
  "secret": "YWUxZTM2ODItOTJjYS00MmIyLTQxZGEtZTE0M2MzNmYwMDI2",
  "redirect_uri": "",
  "policy_id": "57f7b07647e0800001aa2320"
}

List OAuth Clients

Sample Request

curl -vX GET -H "Authorization: {{API Access Credentials}}" \
  -H "Content-Type: application/json" \
  http://{{dashboard-hostname}}/api/apis/oauth/{{api-id}}

Sample Response

{
  "apps": [
    {
     "client_id": "7dce7fc297424fd65596b51c214666a4",
     "secret":"Yzg0ZDRjZTctMzUxNy00YmQ5LTRkM2UtMDdmODQ3MTNjNWM5",
     "redirect_uri": "/cats",
     "policy_id": "57f7b07647e0800001aa2320"
   },
   {
     "client_id": "72083e90e9b044c57e2667d49effff78",
     "secret": "YWUxZTM2ODItOTJjYS00MmIyLTQxZGEtZTE0M2MzNmYwMDI2",
     "redirect_uri": "",
     "policy_id": "57f7b07647e0800001aa2320"
    }
  ],
  "pages":0
}

Get an OAuth2.0 Client

Sample Request

curl -vX GET -H "Authorization: {{API Access Credentials}}" \
  -H "Content-Type: application/json" \
  http://localhost:3000/api/apis/oauth/{{api-id}}/{{client_id}}

Sample Response

{
  "client_id": "7dce7fc297424fd65596b51c214666a4",
  "secret": "Yzg0ZDRjZTctMzUxNy00YmQ5LTRkM2UtMDdmODQ3MTNjNWM5",
  "redirect_uri": "/cats",
  "policy_id": "57f7b07647e0800001aa2320"
}

Delete OAuth Client

You can delete an OAuth client using a simple DELETE method. Please note that tokens issued with the client ID will still be valid until they expire.

Sample Request

curl -vX DELETE -H "Authorization: {{API Access Credentials}}" \
  -H "Content-Type: application/json" \
  http://{{dashboard-hostname}}/api/apis/oauth/{{api-id}}/{{client_id}}

Sample Response

{
  "Status": "OK",
  "Message": "OAuth Client deleted successfully",
  "Meta":null
}

Retrieve All Current Tokens for Specified OAuth2.0 Client

This endpoint allows you to retrieve a list of all current tokens and their expiry date for a provided API ID and OAuth-client ID in the following format. This endpoint will work only for newly created tokens.

Sample Request

GET /api/apis/oauth/528a67c1ac9940964f9a41ae79235fcc/25348e8cf157409b52e39357fd9578f1/tokens HTTP/1.1
Host: localhost:3000
Authorization: {{API Access Credentials}}
Cache-Control: no-cache

Sample Response

[
  {
    "code": "5a7d110be6355b0c071cc339327563cb45174ae387f52f87a80d2496",
    "expires": 1518158407
  },
  {
    "code": "5a7d110be6355b0c071cc33988884222b0cf436eba7979c6c51d6dbd",
    "expires": 1518158594
  },
  {
    "code": "5a7d110be6355b0c071cc33990bac8b5261041c5a7d585bff291fec4",
    "expires": 1518158638
  },
  {
    "code": "5a7d110be6355b0c071cc339a66afe75521f49388065a106ef45af54",
    "expires": 1518159792
  }
]

You can control how long you want to store expired tokens in this list using oauth_token_expired_retain_period which specifies retain period for expired tokens stored in Redis. By default expired token not get removed. See here for more details.

Revoke a Single OAuth Client Token

Sample Request

POST /api/apis/oauth/411f0800957c4a3e81fe181141dbc22a/revoke
Host: localhost
Authorization 64c8e662f6924c4f55e94a873d75e44d
Body: {
  "token":"eyJvcmciOiI1ZTIwOTFjNGQ0YWVmY2U2MGMwNGZiOTIiLCJpZCI6IjIyODQ1NmFjNmJlMjRiMzI5MTIyOTdlODQ5NTc4NjJhIiwiaCI6Im11cm11cjY0In0=",
  "token_type_hint":"access_token"
}

Sample Response

{
  "Status": "OK",
  "Message": "token revoked successfully",
  "Meta": null
}

Revoke all OAuth Client Tokens

Sample Request

POST /api/apis/oauth/411f0800957c4a3e81fe181141dbc22a/revoke_all
Host: localhost
Authorization: 64c8e662f6924c4f55e94a873d75e44d
Body: {
  "client_secret":"MzUyNDliNzItMDhlNy00MzM3LTk1NWUtMWQyODMyMjkwZTc0"
}

Sample Response

{
  "Status": "OK",
  "Message": "tokens revoked successfully",
  "Meta": null
}

OAuth2.0 Authorization Code

This endpoint is used in the Authorization Code Grant flow, generating an authorization code that can be used by the client to request an access token.

• api_id: Unlike the other requests on this page, this must be the api_id value and NOT the API’s id value.
• response_type: Should be provided by requesting client as part of authorization request, this should be either code or token depending on the methods you have specified for the API.
• client_id: Should be provided by requesting client as part of authorization request. The Client ID that is making the request.
• redirect_uri: Should be provided by requesting client as part of authorization request. Must match with the record stored with Tyk.
• key_rules: A string representation of a Session Object (form-encoded). This should be provided by your application in order to apply any quotas or rules to the key.

Note that in the following example, the policy_id isn’t included in the request as these are optional. OAuth2.0 Flow also supports callbacks which can be added to the key_rules in the payload in requests that don’t include the policy_id.

Sample Request

curl -vX POST -H "Authorization: {{API Access Credentials}}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'response_type=code&client_id={{client_id}}&redirect_uri=http%3A%2F%2Foauth.com%2Fredirect&key_rules=%7B+++++%22allowance%22%3A+999%2C+++++%22rate%22%3A+1000%2C+++++%22per%22%3A+60%2C+++++%22expires%22%3A+0%2C+++++%22quota_max%22%3A+-1%2C+++++%22quota_renews%22%3A+1406121006%2C+++++%22quota_remaining%22%3A+0%2C+++++%22quota_renewal_rate%22%3A+60%2C+++++%22access_rights%22%3A+%7B+++++++++%22528a67c1ac9940964f9a41ae79235fcc%22%3A+%7B+++++++++++++%22api_name%22%3A+%22{{api_name}}%22%2C+++++++++++++%22api_id%22%3A+%{{api_id}}%22%2C+++++++++++++%22versions%22%3A+%5B+++++++++++++++++%22Default%22+++++++++++++%5D+++++++++%7D+++++%7D%2C+++++%22org_id%22%3A+%22{{org_id}}%22+%7D'
http://{{dashboard-hostname}}/api/apis/oauth/{{api_id}}/authorize-client

Sample Response

{
  "code": "MWY0ZDRkMzktOTYwNi00NDRiLTk2YmQtOWQxOGQ3Mjc5Yzdk",
  "redirect_to": "http://localhost:3000/oauth-redirect/?code=MWY0ZDRkMzktOTYwNi00NDRiLTk2YmQtOWQxOGQ3Mjc5Yzdk"
}

Single Sign On API

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.

Generate authentication token

The Dashboard exposes the /api/sso Dashboard API which allows you to generate a temporary authentication token, valid for 60 seconds.

You should provide JSON payload with the following data:

• ForSection - scope with possible values of "dashboard" or "portal" only.
• OrgID - organization id
• EmailAddress - user email
• GroupID - user group id ( it is the mongo id and you can can find it in the url when opening a user group via Tyk- Dashboard UI or if you call Tyk-Dashboard REST API /api/usergroups )

Sample Request

POST /api/sso HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8
    
{
  "ForSection": "dashboard",
  "OrgID": "588b4f0bb275ff0001cc7471",
  "EmailAddress": "[email protected]",
  "GroupID": ""
}

Sample Response:

{"Status":"OK","Message":"SSO Nonce created","Meta":"YTNiOGUzZjctYWZkYi00OTNhLTYwODItZTAzMDI3MjM0OTEw"}

See Single Sign On documentation for how to use this token and more details.

Web Hooks API

List web hooks

Sample Request

GET /api/hooks HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "hooks": [
    {
      "api_model": {},
      "id": "54be6c0beba6db07a6000002",
      "org_id": "54b53d3aeba6db5c35000002",
      "name": "Test Post",
      "method": "POST",
      "target_path": "http://httpbin.org/post",
      "template_path": "",
      "header_map": {
        "x-tyk-test": "123456"
      },
      "event_timeout": 0
    }
  ],
  "pages": 0
}

Get single web hook

Sample Request

GET /api/hooks/54be6c0beba6db07a6000002 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "api_model": {},
  "id": "54be6c0beba6db07a6000002",
  "org_id": "54b53d3aeba6db5c35000002",
  "name": "Test Post",
  "method": "POST",
  "target_path": "http://httpbin.org/post",
  "template_path": "",
  "header_map": {
    "x-tyk-test": "123456"
  },
  "event_timeout": 0
}

Add hook

Sample Request

POST /api/hooks HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "name": "New Post Test",
  "method": "POST",
  "target_path": "http://httpbin.org/post",
  "header_map": {
    "x-test": "y-answer"
  }
}    

Sample Response

{
  "Status": "OK",
  "Message": "Webhook created",
  "Meta": ""
}

Update hook

Sample Request

PUT /api/hooks/54c2617aeba6db1edc000003 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "api_model": {},
  "id": "54c2617aeba6db1edc000003",
  "org_id": "54b53d3aeba6db5c35000002",
  "name": "New Post Test",
  "method": "PUT",
  "target_path": "http://httpbin.org/post",
  "template_path": "",
  "header_map": {
    "x-test": "y-answer"
  },
  "event_timeout": 0
} 

Sample Response

{
  "Status": "OK",
  "Message": "Webhook updated",
  "Meta": ""
}

Delete web hook

Sample Request

DELETE /api/hooks/54c2617aeba6db1edc000003 HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "Status": "OK",
  "Message": "Webhook deleted",
  "Meta": ""
}

Open Policy Agent API

For more information on how to configure OPA see Open Policy Agent.

List OPA rules and settings

This endpoint returns by defaul the initial set of OPA rules defined in your Tyk Dashboard, which are located in schema/dashboard.rego (accessible in Self-Managed installations).

Once you update the rules via the API, the OPA rules will be stored at the organization level.

Sample Request

GET /api/org/opa HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

Sample Response

{
  "open_policy": {
    "enabled": true,
    "rules": "default hello = false\r\n\r\nhello {\r\n    m := input.message\r\n    m == \"world\"\r\n}"
  }
}

Update OPA rules and settings

Sample Request

PUT /api/org/opa HTTP/1.1
Host: localhost:3000
authorization:7a7b140f-2480-4d5a-4e78-24049e3ba7f8

{
  "open_policy": {
    "enabled": false,
    "rules": "default hello = false\r\n\r\nhello {\r\n    m := input.message\r\n    m == \"world\"\r\n}"
  }
}

Sample Response

{
    "Status": "OK",
    "Message": "OPA rules has been updated on org level",
    "Meta": null
}

Dashboard Admin API Resources and Usage

API Usage Instructions

For the official Tyk Dashboard Admin API Reference, please visit our API Documentation.

Organizations API

Retrieve a single Organization

Sample Request

GET /admin/organisations/{ORG_ID} HTTP/1.1
Host: localhost:3000
admin-auth: 12345

Sample Response

{
    "id": "5cc03283d07e7f00019404b3",
    "owner_name": "TestOrg5 Ltd.",
    "owner_slug": "testorg",
    "cname_enabled": true,
    "cname": "www.tyk-portal-test.com",
    "apis": [
        {
            "api_human_name": "First API #Test",
            "api_id": "5508bd9429434d5768c423a04db259ea"
        }
    ],
    "developer_quota": 0,
    "developer_count": 0,
    "event_options": {},
    "hybrid_enabled": false,
    "ui": {
        "languages": {},
        "hide_help": false,
        "default_lang": "",
        "login_page": {},
        "nav": {},
        "uptime": {},
        "portal_section": {},
        "designer": {},
        "dont_show_admin_sockets": false,
        "dont_allow_license_management": false,
        "dont_allow_license_management_view": false,
        "cloud": false
    },
    "org_options_meta": {}
}

Retrieve all Organizations

Sample Request

GET /admin/organisations/ HTTP/1.1
Host: localhost:3000
admin-auth: 12345

Sample Response

{
    "organisations": [
        {
            "id": "5cc03283d07e7f00019404b3",
            "owner_name": "TestOrg5 Ltd.",
            "owner_slug": "testorg",
            "cname_enabled": true,
            "cname": "www.tyk-portal-test.com",
            "apis": [
                {
                    "api_human_name": "First API #Test",
                    "api_id": "5508bd9429434d5768c423a04db259ea"
                }
            ],
            "developer_quota": 0,
            "developer_count": 0,
            "event_options": {},
            "hybrid_enabled": false,
            "ui": {
                "languages": {},
                "hide_help": false,
                "default_lang": "",
                "login_page": {},
                "nav": {},
                "uptime": {},
                "portal_section": {},
                "designer": {},
                "dont_show_admin_sockets": false,
                "dont_allow_license_management": false,
                "dont_allow_license_management_view": false,
                "cloud": false
            },
            "org_options_meta": {}
        },
        {
            "id": "5ccae84aa402ce00018b5435",
            "owner_name": "Jively",
            "owner_slug": "",
            "cname_enabled": true,
            "cname": "jive.ly",
            "apis": [],
            "developer_quota": 0,
            "developer_count": 0,
            "event_options": {},
            "hybrid_enabled": false,
            "ui": {
                "languages": {},
                "hide_help": false,
                "default_lang": "",
                "login_page": {},
                "nav": {},
                "uptime": {},
                "portal_section": {},
                "designer": {},
                "dont_show_admin_sockets": false,
                "dont_allow_license_management": false,
                "dont_allow_license_management_view": false,
                "cloud": false
            },
            "org_options_meta": {}
        }
    ],
    "pages": 0
}

Create an Organization

Sample Request

POST /admin/organisations/ HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "owner_name": "Jively",
  "cname": "jive.ly",
  "cname_enabled": true
}

Sample response

{
  "Status":"OK",
  "Message":"Org created",
  "Meta":"54b53d3aeba6db5c35000002"
}

Update an Organization

Sample Request

PUT /admin/organisations/54b53d3aeba6db5c35000002 HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "owner_name": "Jively",
  "cname": "jive.ly",
  "cname_enabled": true
}

Sample Response

{
  "Status":"OK",
  "Message":"Org updated",
  "Meta":""
}

Delete an Organization

Sample Request

DELETE /admin/organisations/54b53d3aeba6db5c35000002 HTTP/1.1
Host: localhost:3000
admin-auth: 12345

Sample Response

{
  "Status":"OK",
  "Message":"Org deleted",
  "Meta":""
}

Users API

Get User

Sample Request

GET /admin/users/54bd0ad9ff4329b88985aafb HTTP/1.1
Host: localhost:3000
admin-auth: 12345

Sample Response

{
  "api_model": {},
  "first_name": "Test",
  "last_name": "User",
  "email_address": "[email protected]",
  "password": "",
  "org_id": "54b53d3aeba6db5c35000002",
  "active": true,
  "id": "54bd0ad9ff4329b88985aafb",
  "access_key": "f81ee6f0c8f2467d539c132c8a422346"
}

Add user

When you add a new user, they are created without a password being set. After adding a user, you need to use the Set Password call to set a password using the user-id created.

Sample Request

POST /admin/users HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "org_id": "5d15d3068ba30a0001621bfe",
  "first_name": "Jason",
  "last_name": "Jasonson",
  "email_address": "[email protected]",
  "active": true,
  "user_permissions": { "IsAdmin": "admin" }
}

Sample Response

{
  "Status": "OK",
  "Message": "e5485fa02e12425974e1220e1636e4d0",
  "Meta": {
    "api_model": {},
    "first_name": "Jason",
    "last_name": "user",
    "email_address": "[email protected]",
    "org_id": "",
    "active": true,
    "id": "5d55378edd4b9e9c308e87da",
    "access_key": "e5485fa02e12425974e1220e1636e4d0",
    "user_permissions": {
      "IsAdmin": "admin"
    },
    "group_id": "",
    "password_max_days": 0,
    "password_updated": "0001-01-01T00:00:00Z",
    "PWHistory": [],
    "created_at": "2019-08-15T10:44:30.784Z"
  }
}

Update User

You need to have the users Permission object set to write to use Update User.

Sample Request

PUT /admin/users/54c25e845d932847067402e2 HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "access_key": "3a8c1cea90af485575bb5455c2e9fb68",
  "first_name": "Jason",
  "last_name": "File",
  "email_address": "[email protected]",
  "active": true,
  "password": "plaintext_password",
  "user_permissions": { "IsAdmin": "admin" }
}

Sample Response

{
  "Status": "OK",
  "Message": "User updated",
  "Meta": ""
}

Single Sign On API

The Dashboard Admin SSO API endpoint allows you to implement custom authentication schemes for the Dashboard and Portal. Our Tyk Identity Broker (TIB) internally also uses this API. See Single Sign On for more details.

Generate authentication token

The Dashboard exposes the /admin/sso Admin API which allows you to generate a temporary authentication token, valid for 60 seconds.

You should provide JSON payload with the following data:

• ForSection - scope with possible values of "dashboard" or "portal"
• OrgID - with your organization id.
• GroupID - the group id
• EmailAddress - user email

Sample Request

POST /admin/sso HTTP/1.1
Host: localhost:3000
admin-auth: 12345
    
{
  "ForSection": "dashboard",
  "OrgID": "588b4f0bb275ff0001cc7471",
  "EmailAddress": "[email protected]",
  "GroupID": ""
}

Sample Response:

{"Status":"OK","Message":"SSO Nonce created","Meta":"YTNiOGUzZjctYWZkYi00OTNhLTYwODItZTAzMDI3MjM0OTEw"}

See Single Sign On documentation for how to use this token and more details.

URL Reload API

Since the Dashboard can have multiple URLs associated with it. It is possible to force a URL reload by calling an API endpoint of the Dashboard API.

Reload the Dashboard URLs

Sample Request

GET /admin/system/reload HTTP/1.1
Host: localhost:3000
admin-auth:12345

Sample Response

{
  "status": "ok"
}

Export Assets API

To make Tyk installations more portable, the Export API enables you to export key configuration objects required to back-up and re-deploy a basic Tyk Pro installation.

Export Organizations

The organization object is the most fundamental object in a Tyk setup, all other ownership properties hang off the relationship between an organization and its APIs, Policies and API Tokens.

Sample Request

GET /admin/organisations/54bd0ad9ff4329b88985aafb HTTP/1.1
Host: localhost:3000
admin-auth: 12345

Sample Response

{
  "id": "53ac07777cbb8c2d53000002",
  "owner_name": "Test",
  "owner_slug": "test",
  "cname_enabled": true,
  "cname": "my.domain.com",
  "apis": [{
    "api_human_name": "API 2",
    "api_id": "5fa2db834e07444f760b7ceb314209fb"
  }, {
    "api_human_name": "API 1",
    "api_id": "7a6ddeca9244448a4233866938a0d6e2"
  }, {
    "api_human_name": "API 3",
    "api_id": "109eacaa50b24b64651a1d4dce8ec385"
  }],
  "developer_quota": 123,
  "developer_count": 21,
  "event_options": {
    "key_event": {
      "webhook": "",
      "email": "",
      "redis": true
    },
    "key_request_event": {
      "webhook": "",
      "email": "",
      "redis": false
    }
  },
  "hybrid_enabled": false,
  "ui": {
    "languages": {},
    "hide_help": false,
    "default_lang": "",
    "login_page": {},
    "nav": {},
    "uptime": {},
    "portal_section": {},
    "designer": {},
    "dont_show_admin_sockets": false,
    "dont_allow_license_management": false,
    "dont_allow_license_management_view": false
  }
}

Export APIs and Policies

To export APIs and Policies you should use the standard GET APIS endpoint and GET POLICIES list endpoints. The output from these endpoints can be used by the Import API.

Import Assets API

The import API enables you to add Organizations, APIs and Policies back into a Tyk installation while retaining their base IDs so that they work together.

Import Organization

The Organization object is the most fundamental object in a Tyk setup, all other ownership properties hang off the relationship between an Organization and its APIs, Policies and API Tokens.

Sample Request

POST /admin/organisations/import HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "id": "53ac07777cbb8c2d53000002",
  "owner_name": "Test",
  "owner_slug": "test",
  "cname_enabled": true,
  "cname": "my.domain.com",
  "apis": [{
    "api_human_name": "API 2",
    "api_id": "5fa2db834e07444f760b7ceb314209fb"
  }, {
    "api_human_name": "API 1",
    "api_id": "7a6ddeca9244448a4233866938a0d6e2"
  }, {
    "api_human_name": "API 3",
    "api_id": "109eacaa50b24b64651a1d4dce8ec385"
  }],
  "developer_quota": 123,
  "developer_count": 21,
  "event_options": {
    "key_event": {
      "webhook": "",
      "email": "",
      "redis": true
    },
      "key_request_event": {
        "webhook": "",
        "email": "",
        "redis": false
    }
  },
  "hybrid_enabled": false,
  "ui": {
    "languages": {},
    "hide_help": false,
    "default_lang": "",
    "login_page": {},
    "nav": {},
    "uptime": {},
    "portal_section": {},
    "designer": {},
    "dont_show_admin_sockets": false,
    "dont_allow_license_management": false,
    "dont_allow_license_management_view": false
  }
}

Import APIs

The import APIs operates on lists of APIs.

Sample Request

POST /admin/apis/import HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "apis": [{
    "api_model": {},
    "api_definition": {...},
    "hook_references": [],
    "is_site": false,
    "sort_by": 0
}, {
    "api_model": {},
    "api_definition": {...},
    "hook_references": [],
    "is_site": false,
    "sort_by": 0
}]
}

Import Policies

The import Policies operates on lists of Policies.

Sample Request

POST /admin/policies/import HTTP/1.1
Host: localhost:3000
admin-auth: 12345

{
  "Data": [{
    "_id": "57ed12fc30c55e6b890d37d8",
    "access_rights": {
      "5fa2db834e07444f760b7ceb314209fb": {
        "allowed_urls": [],
        "api_id": "5fa2db834e07444f760b7ceb314209fb",
        "api_name": "New API 1",
        "versions": ["Default"]
      },
      "7a6ddeca9244448a4233866938a0d6e2": {
        "allowed_urls": [],
        "api_id": "7a6ddeca9244448a4233866938a0d6e2",
        "api_name": "API1",
        "versions": ["Default"]
      }
    },
      "active": true,
      "date_created": "0001-01-01T00:00:00Z",
      "hmac_enabled": false,
      "is_inactive": false,
      "key_expires_in": 0,
      "last_updated": "1478791603",
      "name": "Default",
      "org_id": "53ac07777cbb8c2d53000002",
      "partitions": {
        "acl": false,
        "quota": false,
        "rate_limit": false
      },
      "per": 60,
      "quota_max": -1,
      "quota_renewal_rate": 3600,
      "rate": 1000,
      "tags": []
  }, {
    "_id": "5824343b30c55e52d5e6cfde",
    "access_rights": {
      "7a6ddeca9244448a4233866938a0d6e2": {
        "allowed_urls": [],
        "api_id": "7a6ddeca9244448a4233866938a0d6e2",
        "api_name": "API 1",
        "versions": ["Default"]
      }
    },
      "active": true,
      "date_created": "0001-01-01T00:00:00Z",
      "hmac_enabled": false,
      "is_inactive": false,
      "key_expires_in": 0,
      "last_updated": "1478791761",
      "name": "Test Policy",
      "org_id": "53ac07777cbb8c2d53000002",
      "partitions": {
        "acl": false,
        "quota": false,
        "rate_limit": false
      },
      "per": 1,
      "quota_max": 100,
      "quota_renewal_rate": 90000,
      "rate": 10,
      "tags": []
  }, {
    "_id": "58172a2330c55e22afcd59af",
    "access_rights": {
      "109eacaa50b24b64651a1d4dce8ec385": {
        "allowed_urls": [],
        "api_id": "109eacaa50b24b64651a1d4dce8ec385",
        "api_name": "API 3",
        "versions": ["Default"]
      },
      "5fa2db834e07444f760b7ceb314209fb": {
        "allowed_urls": [],
        "api_id": "5fa2db834e07444f760b7ceb314209fb",
        "api_name": "API 2",
        "versions": ["Default"]
      },
      "7a6ddeca9244448a4233866938a0d6e2": {
        "allowed_urls": [],
        "api_id": "7a6ddeca9244448a4233866938a0d6e2",
        "api_name": "API 1",
        "versions": ["Default"]
      },
      "d023576f836a4e407153009e8d95cf73": {
        "allowed_urls": [],
        "api_id": "d023576f836a4e407153009e8d95cf73",
        "api_name": "Test API",
        "versions": ["Default"]
      }
  },
    "active": true,
    "date_created": "0001-01-01T00:00:00Z",
    "hmac_enabled": false,
    "is_inactive": false,
    "key_expires_in": 2592000,
    "last_updated": "1477913123",
    "name": "Big Policy",
    "org_id": "53ac07777cbb8c2d53000002",
    "partitions": {
      "acl": false,
      "quota": false,
      "rate_limit": false
  },
  "per": 1,
  "quota_max": 6000,
  "quota_renewal_rate": 3600,
  "rate": 10,
  "tags": ["TEST-1", "TEST-2"]
}],
  "Pages": 0
}

Exploring API Endpoint Designer

Classic APIs

Tyk Dashboard’s Endpoint Designer provides a graphical environment for the creation and update of your Tyk Classic APIs.

The Endpoint Designer allows to configure all elements of your Tyk Classic API and consists of several tabs, plus a Raw Definition view which allows you to directly edit the Tyk Classic API Definition (in JSON format). Note that

Core Settings

The Core Settings tab provides access to configure basic settings for the API:

• Detailed logging
• API Settings including
  • Listen path
  • API Categories
• Upstream settings including
  • Upstream service (target) URL
  • Service Discovery
• API Ownership
• API level rate limiting
• Authentication

Versions

The Versions tab allows you to create and manage API versioning for the API.

At the top of the Endpoint Designer, you can see which version you are currently editing. If you have more than one option, selecting it from the drop-down will load its endpoint configuration into the editor.

Endpoint Designer

The Endpoint Designer is where you can define endpoints for your API so that you can enable and configure Tyk middleware to perform checks and transformations on the API traffic.

In some cases, you will want to set global settings that affect all paths that are managed by Tyk. The Global Version Settings section will enable you to configure API-level request and response header transformation.

Advanced Options

The Advanced Options tab is where you can configure Tyk’s other powerful features including:

• Upstream certificate management
• API-level caching including a button to invalidate (flush) the cache for the API
• CORS
• Add custom attributes to the API definition as config data that can be accessed by middleware
• Enable context variables so that they are extracted from requests and made available to middleware
• Manage segment tags if you are working with sharded gateways
• Manage client IP address allow and block lists
• Attach webhooks that will be triggered for different events

Uptime Tests

In the Uptime Tests tab you can configure Tyk’s Uptime Test functionality

Debugging

The Debugging tab allows you to test your endpoints before you publish or update them. You can also use it for testing any middleware plugins you have implemented. Any debugging you create will persist while still in the current API, enabling you to make changes in the rest of the API settings without losing the debugging scenario.

The Debugging tab consists of the following sections:

• Request
• Response
• Logs

Request

In this section, you can enter the following information:

• Method - select the method for your test from the drop-down list
• Path - your endpoint to test
• Headers/Body - enter any header information, such as Authorization, etc. Enter any body information. For example, entering user information if creating/updating a user.

Once you have entered all the requested information, click Run. Debugging Response and Log information will be displayed:

Response

The Response section shows the JSON response to your request.

Logs

The debugging level is set to debug for the request. This outputs all logging information in the Endpoint Designer. In the Tyk Gateway logs you will see a single request. Any Error messages will be displayed at the bottom of the Logs output.

Traffic Analytics

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. The Dashboard offers a great way for you to debug your APIs and quickly pin down where errors might be cropping up and for which clients.

How does Tyk capture and process Traffic Analytics?

When a client makes a request to the Tyk Gateway, the details of the request and response are captured and stored in a temporary Redis list. This list is read (and then flushed) every 10 seconds by the Tyk Pump. The Pump processes the records that it has read from Redis and forwards them to the required data sinks using the pumps configured in your system. You can set up multiple pumps and configure them to send different analytics to different data sinks.

The Mongo Aggregate and SQL Aggregate pumps perform aggregation of the raw analytics records before storing the aggregated statistics in the MongoDB or SQL database respectively.

Minimal pump configuration for Tyk Dashboard analytics

For the Tyk Dashboard’s analytics functionality to work, you must configure both per request and aggregated pumps for the database platform that you are using

• if you are using MongoDB, you must configure mongo and mongo_aggregate pumps
• if you are using SQL, you must configure sql and sql_aggregate pumps

Per-request (raw) analytics

The transaction records contain information about each request and response, such as path or status. The fields captured in each analytics record are included in the Tyk Pump documentation.

It is also possible to enable detailed request logging in the Gateway so that Tyk will log the requests and responses (including payloads) in wire format as base64 encoded data.

These data are displayed in the Log Browser, on the Activity logs screen in the Tyk Dashboard.

Aggregated analytics

The Mongo Aggregate and SQL Aggregate pumps will collate statistics from the analytics records, aggregated by hour, for the following keys:

Analyzing API Traffic Activity

API Activity Dashboard

The first screen (and main view) of the Tyk Dashboard will show you an overview of the aggregate usage of your APIs, this view includes the number of hits, the number of errors and the average latency over time for all of your APIs as an average:

You can toggle the graphs by clicking the circular toggles above the graph to isolate only the stats you want to see.

Use the Start and End dates to set the range of the graph, and the version drop-down to select the API and version you wish to see traffic for.

You can change the granularity of the data by selecting the granularity drop down (in the above screenshot: it is set to “Day”).

The filter by tag option, in a graph view, will enable you to see the graph filtered by any tags you add to the search.

Below the aggregate graph, you’ll see an error breakdown and endpoint popularity chart. These charts will show you the overall error type (and code) for your APIs as an aggregate and the popularity of the endpoints that are being targeted by your clients:

Activity Logs

When you look through your Dashboard and your error breakdown statistics, you’ll find that you will want to drill down to the root cause of the errors. This is what the Log Browser is for.

The Log Browser will isolate individual log lines in your analytics data set and allow you to filter them by:

• API Name
• Token ID (hashed)
• Errors Only
• By Status Code

You will be presented with a list of requests, and their metadata:

Click a request to view its details.

Self-Managed Installations Option

In an Self-Managed installation, if you have request and response logging enabled, then you can also view the request payload and the response if it is available. To enable request and response logging, please take a look at useful debug modes .

A warning on detailed logging: This mode generates a very large amount of data, and that data exponentially increases the size of your log data set, and may cause problems with delivering analytics in bulk to your MongoDB instances. This mode should only be used to debug your APIs for short periods of time.

Activity by API

To get a tabular view of how your API traffic is performing, you can select the Activity by API option in the navigation and see a tabular view of your APIs. This table will list out your APIs by their traffic volume and you’ll be able to see when they were last accessed:

You can use the same range selectors as with the Dashboard view to modify how you see the data. However, granularity and tag views will not work since they do not apply to a tabulated view.

If you select an API name, you will be taken to the drill-down view for that specific API, here you will have a similar Dashboard as you do with the aggregate API Dashboard that you first visit on log in, but the whole view will be constrained to just the single API in question:

You will also see an error breakdown and the endpoint popularity stats for the API:

Tyk will try to normalize endpoint metrics by identifying IDs and UUIDs in a URL string and replacing them with normalized tags, this can help make your analytics more useful. It is possible to configure custom tags in the configuration file of your Tyk Self-Managed or Multi-Cloud installation.

Activity by Key

You will often want to see what individual keys are up to in Tyk, and you can do this with the Activity per Key section of your analytics Dashboard. This view will show a tabular layout of all keys that Tyk has seen in the range period and provide analytics for them:

You’ll notice in the screenshot above that the keys look completely different to the ones you can generate in the key designer (or via the API), this is because, by default, Tyk will hash all keys once they are created in order for them to not be snooped should your key-store be breached.

This poses a problem though, and that is that the keys also no longer have any meaning as analytics entries. You’ll notice in the screenshot above, one of the keys is appended by the text TEST_ALIAS_KEY. This is what we call an Alias, and you can add an alias to any key you generate and that information will be transposed into your analytics to make the information more human-readable.

The key 00000000 is an empty token, or an open-request. If you have an API that is open, or a request generates an error before we can identify the API key, then it will be automatically assigned this nil value.

If you select a key, you can get a drill down view of the activity of that key, and the errors and codes that the token has generated:

(The filters in this view will not be of any use except to filter by API Version).

Activity by endpoint

To get a tabular view of how your API traffic is performing at the endpoint level, you can select the Activity by Endpoint option in the navigation and see a tabular view of your API endpoints. This table will list your API endpoints by their traffic volume and you’ll be able to see when they were last accessed:

Controlling which endpoints appear in the analytics data

The aggregate pumps have an option to track_all_paths which will ensure that all analytics records generated by the Tyk Gateway will be included in the aggregated statistics on the Endpoint Popularity screen. Set this to true to capture all endpoints in the aggregated data and subsequently on the Dashboard page.

You can alternatively select only a subset of the endpoints to include in the aggregated data by setting track_all_paths to false and identifying specific endpoints to be “tracked”. These are identified by the TrackPath flag being set to true in the record. In this configuration, the Pump will only include transaction records from “tracked” endpoints in the aggregated data.

Tyk Gateway will set TrackPath to true in transaction records generated for endpoints that have the track endpoint middleware enabled.

Selecting Tyk OAS APIs endpoints to be tracked

The design of the Tyk OAS API Definition takes advantage of the operationId defined in the OpenAPI Document that declares both the path and method for which the middleware should be added. The path can contain wildcards in the form of any string bracketed by curly braces, for example {user_id}. These wildcards are so they are human readable and do not translate to variable names. Under the hood, a wildcard translates to the “match everything” regex of: (.*).

The track endpoint middleware (trackEndpoint) can be added to the operations section of the Tyk OAS Extension (x-tyk-api-gateway) in your Tyk OAS API Definition for the appropriate operationId (as configured in the paths section of your OpenAPI Document).

The trackEndpoint object has the following configuration:

• enabled: enable the middleware for the endpoint

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

{
    "components": {},
    "info": {
        "title": "example-track-endpoint",
        "version": "1.0.0"
    },
    "openapi": "3.0.3",
    "paths": {
        "/anything": {
            "get": {
                "operationId": "anythingget",
                "responses": {
                    "200": {
                        "description": ""
                    }
                }
            }
        }
    },
    "x-tyk-api-gateway": {
        "info": {
            "name": "example-track-endpoint",
            "state": {
                "active": true
            }
        },
        "upstream": {
            "url": "http://httpbin.org/"
        },
        "server": {
            "listenPath": {
                "value": "/example-track-endpoint/",
                "strip": true
            }
        },
        "middleware": {
            "operations": {
                "anythingget": {
                    "trackEndpoint": {
                        "enabled": true
                    }               
                }
            }
        }
    }
}

In this example the track endpoint middleware has been configured for requests to the GET /anything endpoint. These requests will appear in the Endpoint Popularity analytics screen, located within the API Usage section of Tyk Dashboard.

The configuration above is a complete and valid Tyk OAS API Definition that you can import into Tyk to try out the track endpoint middleware.

Configuring the middleware in the API Designer

Adding the track endpoint middleware to your API endpoints is easy when using the API Designer in the Tyk Dashboard, simply follow these steps:

1. Add an endpoint

   From the API Designer add an endpoint that matches the path and method to which you want to apply the middleware.

   

   

   

2. Select the Track Endpoint middleware

   Select ADD MIDDLEWARE and choose the Track Endpoint middleware from the Add Middleware screen.

   

3. Save the API

   Select SAVE API to apply the changes to your API.

Selecting Tyk Classic API endpoints to be tracked

If you are working with Tyk Classic APIs then you must add a new track_endpoints object to the extended_paths section of your API definition.

The track_endpoints object has the following configuration:

• path: the endpoint path
• method: the endpoint HTTP method

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "extended_paths": {
        "track_endpoints": [
            {
                "disabled": false,
                "path": "/anything",
                "method": "GET",
            }
        ]
    }
}

In this example the track endpoint middleware has been configured for HTTP GET requests to the /anything endpoint. These requests will appear in the Endpoint Popularity analytics screen, located within the API Usage section of Tyk Dashboard.

Configuring the middleware in the API Designer

You can use the API Designer in the Tyk Dashboard to configure the track endpoint middleware for your Tyk Classic API by following these steps.

1. Add an endpoint for the path and select the plugin

   From the Endpoint Designer add an endpoint that matches the path for which you want to allow access. Select the Track endpoint plugin.

   

2. Save the API

   Use the save or create buttons to save the changes and activate the middleware for the selected endpoint.

Activity by Location

Tyk will attempt to record GeoIP based information based on your inbound traffic. This requires a MaxMind IP database to be available to Tyk and is limited to the accuracy of that database.

You can view the overview of what the traffic breakdown looks like per country, and then drill down into the per-country traffic view by selecting a country code from the list:

MaxMind Settings

To use a MaxMind database, see MaxMind Database Settings in the Tyk Gateway Configuration Options.

Activity by Error

The error overview page limits the analytics down to errors only, and gives you a detailed look over the range of the number of errors that your APIs have generated. This view is very similar to the Dashboard, but will provide more detail on the error types:

Activity by Oauth Client

Traffic statistics are available on a per OAuth Client ID basis if you are using the OAuth mode for one of your APIs. To get a breakdown view of traffic aggregated to a Client ID, you will need to go to the System Management -> APIs section and then under the OAuth API, there will be a button called OAuth API. Selecting an OAuth client will then show its aggregate activity

In the API list view – an OAuth Clients button will appear for OAuth enabled APIs, use this to browse to the Client ID and the associated analytics for that client ID:

You can view the analytics of individual tokens generated by this Client ID in the regular token view.

Governance using API Categories

API categorization is a governance feature provided within the Tyk Dashboard that helps you to manage a portfolio of APIs. You can filter the list of APIs visible in the Dashboard UI or to be returned by the Dashboard API by category. You can assign an API to any number of categories and any number of APIs to a category. All category names are entirely user defined.

When to use API categories

Managing a large portfolio of APIs

As a platform manager looking after a large portfolio of APIs, if I need to make changes to a sub-set of APIs, it’s cumbersome having to identify which APIs they are and then to find them one-by-one in the list. If I have assigned categories to my APIs then I can filter quickly and easily to work with that sub-set. What’s really powerful is that an API can appear in as many different categories as I like.

Multi-tenant deployment

Multi-tenant deployments with role-based access control enabled allows an admin user to give different users or groups access to a sub-set of the entire API portfolio. Categories can be aligned with the API ownership rules that you have deployed to allow filtering the list of APIs for those visible to each separate user group/team.

How API categories work

API categories with Tyk are a very simple concept - you can define any string as a category and then tag the relevant APIs with that string.

Categories might refer to the API’s general focus (e.g. ‘weather’ or ‘share prices’); they might relate to geographic location (e.g. ‘APAC’ or ‘EMEA’); they might refer to technical markers (e.g. ‘dev’, ’test’); or anything else you might need. It’s completely up to you.

Categories can be defined, added to and removed from APIs without limitation.

Tyk OAS APIs

When a Tyk OAS API is assigned to a category, the category name (string) is appended to a list in the database object where the API definition is stored by Tyk Dashboard. No change is made to the API definition itself.

Tyk Classic APIs

When a Tyk Classic API is assigned to a category, the category name (string) is appended to the name field in the API definition using a # qualifier. For example, let’s say you have an API with this (partial) API definition:

{
    "name": "my-classic-api"  
}

You can add it to the global and staging categories by updating the API definition to:

{
    "name": "my-classic-api #global #staging"  
}

When a Tyk Classic API is migrated from one environment to another using Tyk Sync, it will retain any category labels that it has been assigned.

Using API categories

API categories can be added and removed from APIs within the API Designer, via the Tyk Dashboard API, or via Tyk Operator.

API Designer

The API Designer in the Tyk Dashboard UI provides a simple method for assigning APIs to categories, removing categories and filtering the API list by category.

Managing categories with Tyk OAS APIs

When working with Tyk OAS APIs, the API Designer has a separate Access tab where you can configure the categories to which the API is assigned.

You can choose existing categories from the drop-down or define new categories simply by typing in the box. You can also remove the API from a category by clicking on the x or deleting the category from the box.

Managing categories with Tyk Classic APIs

When working with Tyk Classic APIs, the API Designer has a box in the API Settings section where you can configure the categories to which the API is assigned.

You can choose existing categories from the list that appears when you click in the box or you can define new categories simply by typing in the box. You can also remove the API from a category by clicking on the x or deleting the category from the box.

Filtering the API list

When you have APIs assigned to categories, you can choose to view only the APIs in a specific category by using the FILTER BY API CATEGORY drop-down on the Created APIs screen.

Tyk Dashboard API

The Tyk Dashboard API provides endpoints to manage categories directly, if you are not using the API Designer.

When working with Tyk OAS APIs, you can manage categories for an API using these endpoints:

When working with Tyk Classic APIs, you manage categories for an API by modifying the name field in the API definition and then updating the API in Tyk with that using these endpoints:

These endpoints will return information for categories across all APIs in the system (both Tyk OAS and Tyk Classic):

Tyk Operator

You can manage categories using Tyk Operator custom resources. Please refer to Tyk Operator documentation to see how to manage API categories for Tyk OAS APIs and Tyk Classic APIs.

Governance using API Templates

API Templates are an API governance feature provided to streamline the process of creating Tyk OAS APIs. 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.

The default template is a blank API definition; your custom templates will contain some configuration, for example cache configuration or default endpoints with pre-configured middleware. When you create a new API using a custom template, whether importing an OpenAPI document or building the API from scratch in the Tyk API Designer, those elements of the API configuration included in the template will be pre-configured for you.

When to use API templates

Gateway agnostic API design

When working with OpenAPI described upstream service APIs, your service developers do not need to learn about Tyk. You can create and maintain a suitable suite of templates that contain the Tyk-specific configuration (x-tyk-api-gateway) that you require for your externally published API portfolio. Creating an API on Tyk is as simple as importing the OpenAPI document and selecting the correct template. Tyk will combine the OpenAPI description with the template to produce a valid Tyk OAS API.

Standardizing API configuration

If you have specific requirements for your external facing APIs - for example authentication, caching or even a healthcheck endpoint - you can define the appropriate API templates so that when APIs are created on Tyk these fields are automatically and correctly configured.

How API templating works

An API template is a blueprint from which you can build new APIs - it is an incomplete JSON representation of a Tyk OAS API definition that you can use as the starting point when creating a new API on Tyk. There is no limit to how much or how little of the API definition is pre-configured in the template (such that when you choose to create a new API without choosing a template, the blank API definition that you start from is itself a template).

Templates are used only during the creation of an API, they cannot be applied later. Before you can use a template as the basis for an API, you must register the template with Tyk Dashboard.

Structure of an API template

An API template asset has the following structure:

• id: a unique string type identifier for the template
• kind: the asset type, which is set to oas-template
• name: human-readable name for the template
• description: a short description of the template, that could be used for example to indicate the configuration held within the template
• data: a Tyk OAS API definition, the content of which will be used for templating APIs
• _id: a unique identifier assigned by Tyk when the template is registered in the Dashboard database

Creating an API from a template

When you use a template during the creation of an API, the fields configured in data will be pre-set in your new API. You are able to modify these during and after creation of the template. No link is created between the API and the template, so changes made to the API will not impact the template.

Merging with an OpenAPI description or Tyk OAS API definition

When you use a template during the creation of an API where you import the OpenAPI document or a full Tyk OAS API definition, the template is combined with the imported OAS description. If the x-tyk-api-gateway extension exists in the template, it will be applied to the newly created API.

Where there are clashes between configuration in the OpenAPI description and the template:

• for maps, such as paths and components, new keys will be added alongside any existing ones from the template
  • if a key in the OpenAPI description matches one in the template, the OpenAPI description takes precedence
• for array properties, such as servers and tags, values in the OpenAPI description will replace those in the template

If you’re using the API Designer in the Tyk Dashboard UI, then you can find details and examples of how to work with API templates here.

If you’re using the Tyk Dashboard API, then you can find details and examples of how to work with API templates here.

Working with API Templates using the Template Designer

API Templates are an API governance feature provided to streamline the process of creating Tyk OAS APIs. 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.

The Tyk Dashboard UI provides the following functionality to support working with API templates:

• Creating templates
  • new template
  • from an existing API
• Using templates
  • when creating an API
  • when importing an OpenAPI description or API definition
• Managing templates

API Templates can be found in the API Templates section of the API Management menu in the Tyk Dashboard. This screen lists all the templates currently registered with Tyk and displays their names and short descriptions. It also gives access to options to create and manage templates.

Creating templates

API templates can be created starting from a blank template or from an existing API

Creating a new API template

To create a template, simply visit the API Templates section of the Tyk Dashboard and select ADD TEMPLATE.

This will take you to the Create API Template screen, where you can configure all aspects of the template.

The template does not need to be a complete or valid API definition however as a minimum:

• you must give the template a Name
• you must give the template a Description

In this example, we have configured just the Name, Description, Gateway Status and Access settings:

When you have configured all of the API-level and endpoint-level settings you require, select SAVE TEMPLATE to create and register the template with Tyk.

Returning to the API Template screen you will see your new template has been added to the list and assigned a unique id that can be used to access the template from the Tyk Dashboard API:

Creating a template from an existing API

You can use an existing API deployed on Tyk as the basis for a new API template - this is a great way to build up a portfolio of standardized APIs once you’ve got your first one correctly configured.

From the Created APIs screen within the APIs section of the Tyk Dashboard, select the API that you wish to use as your starting point. In the ACTIONS drop-down select the CREATE API TEMPLATE option.

This will take you to the Create API Template screen, where you can configure all aspects of the template.

The template does not need to be a complete or valid API definition however as a minimum:

• you must give the template a Name
• you must give the template a Description

In this example, we have configured the Name and Description. The base API included response header transformation middleware on the /anything endpoint and API-level cache configuration, all of which will be configured within the template.

When you have configured all of the API-level and endpoint-level settings you require, select SAVE TEMPLATE to create and register the template with Tyk.

Returning to the API Template screen you will see your new template has been added to the list and assigned a unique id that can be used to access the template from the Tyk Dashboard API.

Using templates

API templates are used as the starting point during the creation of a new API. They can be applied in all of the methods supported by Tyk for creating new APIs.

Using a template when creating a new API

There are two ways to base a new API, created entirely within the Tyk Dashboard’s API Designer, on a template that you’ve created and registered with Tyk.

You can go from the API Template screen - for the template you want to use, select CREATE API FROM TEMPLATE from the ACTIONS menu:

Or, from the Created APIs screen, select ADD NEW API as normal and then select the template you want to use from the API Template section:

Both of these routes will take you through to the API Designer, where the settings from your API template will be pre-configured.

In this example, we applied “My first template” that we created here. You can see that the Gateway Status and Access fields have been configured:

Using a template when importing an OpenAPI description or API definition

From the Import API screen, if you select the OpenAPI type then you can create an API from an OpenAPI description or Tyk OAS API definition; choose the appropriate method to provide this to the Dashboard:

• paste the JSON into the text editor
• provide a plain text file containing the JSON
• provide a URL to the JSON

  

After pasting the JSON or locating the file, you can select the template you want to use from the API Template section:

In this example we used this simple OpenAPI description and selected “My second template” that we created here:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "components": {},
  "info": {
    "title": "my-open-api-document",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "http://httpbin.org"
    }
  ],
  "paths": {
    "/xml": {
      "get": {
        "operationId": "xmlget",
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  }
}

The API that is created has both /xml and /anything endpoints defined, with API-level caching configured. You can see the API definition here.

Managing templates

The Dashboard UI allows you to edit and delete templates after they have been created and registered with the Tyk Dashboard

Editing a template

You can make changes to a template that has been registered with Tyk from the API Templates screen. For the template that you want to modify, simply select EDIT TEMPLATE from the ACTIONS menu:

This will take you to the API Template Details screen where you can view the current template configuration. If you want to make changes, simply select EDIT to make the fields editable:

Alternatively you can view and modify the raw JSON for the template by selecting VIEW RAW TEMPLATE from the ACTIONS menu:

You’ll need to select SAVE TEMPLATE to apply your changes from either screen.

Deleting a template

You can delete a template from your Tyk Dashboard from the API Template Details screen. This screen can be accessed by selecting the template from the API Templates screen (either by clicking on the template name, or selecting EDIT TEMPLATE from the ACTIONS menu):

From the API Template Details screen you can select DELETE TEMPLATE from the ACTIONS menu:

Working with API Templates using the Dashboard API

API Templates are an API governance feature provided to streamline the process of creating Tyk OAS APIs. 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.

The Tyk Dashboard API provides the following functionality to support working with API templates:

• registering a template with Tyk Dashboard
• applying a template when creating an API from an OpenAPI document
• applying a template when creating an API from a Tyk OAS API definition

Structure of an API template

An API template asset has the following structure:

• id: a unique string type identifier for the template
• kind: the asset type, which is set to oas-template
• name: human-readable name for the template
• description: a short description of the template, that could be used for example to indicate the configuration held within the template
• data: a Tyk OAS API definition, the content of which will be used for templating APIs
• _id: a unique identifier assigned by Tyk when the template is registered in the Dashboard database

Registering a template with Tyk Dashboard

To register an API template with Tyk, you pass the asset in the body of a POST request to the dashboard’s /api/assets endpoint.

For example, if you send this command to the endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

curl --location 'http://localhost:3000/api/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d9957aff302b4f5e5596c86a685e63d8' \
--data '{
  "kind": "oas-template",
  "name": "my-template",
  "description": "My first template",
  "id": "my-unique-template-id",
  "data": {
    "info": {
      "title": "",
      "version": ""
    },
    "openapi": "3.0.3",
    "paths": {
      "/anything": {
        "post": {
          "operationId": "anythingpost",
          "responses": {
            "200": {
              "description": ""
            }
          }
        }
      }
    },
    "x-tyk-api-gateway": {
      "middleware": {
        "global": {
          "cache": {
            "enabled": true,
            "timeout": 5,
            "cacheAllSafeRequests": true
          }
        },
        "operations": {
          "anythingpost": {
            "requestSizeLimit": {
              "enabled": true,
              "value": 100
            }
          }
        }
      }
    }
  }
}'

Tyk will respond with HTTP 201 Created and will provide this payload in response:

{
    "Status": "success",
    "Message": "asset created",
    "Meta": "65e8c352cb71918520ff660c",
    "ID": "my-unique-template-id"
}

Here Meta contains the database ID (where the asset has been registered in the persistent storage) and ID contains the unique identifier for the template. This unique identifier will be automatically generated by Tyk if none was provided in the id of the template asset provided in the curl request.

Applying a template when creating an API from an OpenAPI document

When creating an API on Tyk using an OpenAPI document describing your upstream service, you can use the /apis/oas/import endpoint to import the OpenAPI description and apply it to your API.

If you have a template registered with your Dashboard, you can use this as the starting point for your new API. Tyk will combine the OpenAPI document with the template, automating the configuration of any element in the Tyk OAS API definition as defined in your chosen template.

You’ll need to identify the template to be used during the import. You can use either its unique id or the database ID that was assigned when the template was registered with Tyk Dashboard. You provide either the id or _id in the templateID query parameter in the call to /oapis/oas/import.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

curl --location 'http://localhost:3000/api/apis/oas/import?templateID=my-unique-template-id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <DASHBOARD_SECRET>' \
--data '{
  "components": {},
  "info": {
    "title": "my-open-api-document",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "http://httpbin.org"
    }
  ],
  "paths": {
    "/xml": {
      "get": {
        "operationId": "xmlget",
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  }
}'

Tyk will respond with HTTP 200 OK and will provide this payload in response:

{
    "Status": "OK",
    "Message": "API created",
    "Meta": "65e8c4f4cb71918520ff660d",
    "ID": "970560005b564c4755f1db51ca5660e6"
}

Here Meta contains the database ID (where the API has been registered in the persistent storage) and ID contains the unique identifier for the API. This unique identifier will be automatically generated by Tyk as none was provided in the id field of the x-tyk-api-gateway.info field provided in the curl request.

The new Tyk OAS API will have this definition, combining the OpenAPI description provided in the body of the curl request with the template with Id my-unique-template-id:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81