Creating a Custom Developer Portal

Why Build a Custom Developer Portal?

The Tyk Dashboard includes portal functionality by default, but in some cases it is required to use custom logic or, for example, embed the portal into an existing platform. Thankfully Tyk is flexible enough to provide an easy way of integrating the portal to any platform and language using a few API calls.

The source code is available from the following GitHub repo - https://github.com/TykTechnologies/tyk-custom-portal

A video covering the process of building a custom portal is available to view here:

Building Blocks

Before starting work on implementing a custom developer portal, let’s understand the basic building blocks.

Obtaining a Dashboard API Key

To run queries against the Tyk Dashboard API you need to obtain credentials from the Users screen.

1. Select Users from the System Management section.
2. In the Users list, click Edit for your user.
3. The API key is the Tyk Dashboard API Access Credentials, copy this somewhere you can refer to it.

API Key Location

Let’s save it to the environment variable to simplify code examples in this guide. All the commands should be run in your terminal.

Creating a Developer

Request

curl https://admin.cloud.tyk.io/api/portal/developers \
  -X POST \
  -H "authorization: $TYK_API_KEY" \
  -d \
'{
  "email": "[email protected]",
  "password": "supersecret",
  "fields": {
      "Name": "John Snow"
  }
}'

Response

{"Status":"OK","Message":"598d4a33ac42130001c1257c","Meta":null}

Where Message contains the developer internal ID., You do not have to remember it, since you can find a developer by his email, using the API.

Developer by Email

Request

curl https://admin.cloud.tyk.io/api/portal/developers/email/apidev%40example.com \
  -X GET \
  -H "authorization: $TYK_API_KEY"

Response

{"id":"598d4a33ac42130001c1257c","email":"[email protected]","date_created":"2017-08-11T06:09:55.654Z","inactive":false,"org_id":"59368a6b5eeba30001786baf","api_keys":{},"subscriptions":{},"fields":{"Name":"John Snow","source":"google search"},"nonce":"","sso_key":""}

Developer Validation

By default, the Tyk Developer portal automatically accepts all developer registrations, if they are not completely disabled in the portal configuration.

If you want to allow developer registration but add an additional layer of verification, you can use the developer inactive attribute to handle it. By default, it is false, and you can set it to true if additional verification is needed. To make this work, you need to add additional logic to your custom portal code.

Updating a Developer. Example: Adding Custom Fields

Let’s say we want to add new custom “field” to the developer, to store some internal meta information. Tyk so far does not support PATCH semantics, e.g. you cannot update only single field, you need to provide the full modified record.

Lets created an updated developer record, based on the example response provided in Developer by Email section. Let’s add new “traffic_source” custom field.

Request

curl https://admin.cloud.tyk.io/api/portal/developers/598d4a33ac42130001c1257c \
  -X PUT \
  -H "authorization: $TYK_API_KEY" \
  -d \
  '{
    "id":"598d4a33ac42130001c1257c",
    "email":"[email protected]",
    "date_created":"2017-08-11T06:09:55.654Z",
    "inactive":false,
    "org_id":"59368a6b5eeba30001786baf",
    "api_keys":{},
    "subscriptions":{},
    "fields":{
      "Name":"John Snow",
      "traffic_source":"google search"
    }
  }'

Response

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

Note that all non-empty custom fields are shown in the Tyk Dashboard Developer view. All the keys created for this developer inherit his custom fields, if they are specified in the Portal settings Signup fields list.

Login Workflow: Checking User Credentials

If you need to implement own login workflow, you need be able to validate user password.

Request

    curl https://admin.cloud.tyk.io/api/portal/developers/verify_credentials \
    -X POST \
    -H "authorization: $TYK_API_KEY" \
    -d \
    '{
        "username": "<developer-email>",
        "password": "<developer-password>"
    }'

If the user credentials are verified, the HTTP response code will be 200, otherwise credentials do match and a 401 error will be returned.

Listing Available APIs

Inside the admin dashboard in the portal menu, you can define catalogues with the list of APIs available to developers. Each defined API is identified by its policy id field.

Request

curl https://admin.cloud.tyk.io/api/portal/catalogue \
-X GET \
-H "authorization: $TYK_API_KEY"

Response

{
 "id":"5940e3d29ba5330001647b21",
 "org_id":"59368a6b5eeba30001786baf",
 "apis":[
  {
   "name":"asdasd",
   "short_description":"",
   "long_description":"",
   "show":true,
   "api_id":"",
   "policy_id":"59527b8c375f1e000146556b",
   "documentation":"",
   "version":"v2"
  },
  {
   "name":"asdaszczxczx",
   "short_description":"",
   "long_description":"",
   "show":true,
   "api_id":"",
   "policy_id":"5944267f8b8e5500013082a5",
   "documentation":"",
   "version":"v2"
  }
 ]
}

Issuing Keys

To generate a key for the developer, first he should send a request to the administrator of the API, and if needed provide details of the key usage. By default, all keys requests are approved automatically, and the user immediately receives his API key, but you can turn on the Review all key requests before approving them option in the portal settings, to add additional verification step, and approve all keys manually. Once a key is issued, the user receives an email with the key details.

Request

curl https://admin.cloud.tyk.io/api/portal/requests \
-X POST \
-H "authorization: $TYK_API_KEY" \
-d \
'{
  "by_user":"<developer-id>",
  "for_plan": "<api-policy-id>"
  "version": "v2",
  "fields":{
      "custom_field":"value",
  }
}'

Response

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

Checking User Subscriptions and Keys

The Developer object contains the subscriptions field with information about user API keys, and associtated API’s (policies). For Example:

Request

"subscriptions":{"<policy-id-1>": "<api-key-1>", "<policy-id-2>": "<api-key-2>"},

Analytics

You can get aggregate statistics for 1 key or all developer keys (need to specify a list of all keys). Also, you can group by day (hour or month), and by API (policy id).

API Endpoint: /api/activity/keys/aggregate/#{keys}/#{from}/#{to}?p=-1&res=day

• keys should be specified separated by ‘,’ delimiter.
• from and to values must be in // format.
• resolution specified res attribute: ‘day’, ‘hour’ or ‘month’
• api_id - policy id associated with developer portal API. If ommited return stats for all APIs.

Request

curl "https://admin.cloud.tyk.io/api/activity/keys/aggregate/add2b342,5f1d9603,/5/8/2017/13/8/2017?api_id=8e4d983609c044984ecbb286b8d25cd9&api_version=Non+Versioned&p=-1&res=day" \
-X GET \
-H "authorization: $TYK_API_KEY"

Response

{ "data":[
  {
    "id":{"day":9,"month":8,"year":2017,"hour":0,"code":200},
    "hits":13,
    "success":10,
    "error":3,
    "last_hit":"2017-08-09T12:31:02Z"
  },
  ...
],"pages":0}

In example above add2b342,5f1d9603, is 2 users keys. Note that this example shows hashed key values as described here. Key hashing is turned on for the Cloud, but for Multi-Cloud and Self-Managed installations you can also turn it off. Hashed keys mean that the API administrator does not have access to real user keys, but they can still use the hashed values for showing analytics.

Building a Portal

This guide includes the implementation of a full featured developer portal written in Ruby in just 250 lines of code. This portal implementation does not utilise any database and uses our Tyk Dashboard API to store and fetch all the data.

To run it, you need to have Ruby 2.3+ (latest version). Older versions may work but have not been tested.

First, you need to install dependencies by running gem install sinatra excon --no-ri in your terminal.

Then run it like this: TYK_PORTAL_PORT=8080 TYK_API_KEY=<your-api-key-here> ruby portal.rb

You can also specify the TYK_DASHBOARD_URL if you are trying this portal with an Self-Managed installation. By default, it is configured to work with Cloud or Multi-Cloud.