Get Started With Tyk API Gateway
Tyk offers various products to manage APIs and services. The heart of its product palette is its open-source API Gateway. It is completely developed in Go and can serve as a proxy for REST, GraphQL, and other services. This guide describes how to run the API Gateway with Docker.
What You’ll Need
- A REST client — I’ll use HTTPie in my examples, but any client works
Run Tyk Gateway With Docker
1. Configure a Network
$ docker network create tyk
2. Pull and Run Redis
I’m using Redis 5.0.10 instead of the latest version because this is the latest supported version according to the Tyk docs. Please note, that running Redis like this is not the preferred way for production environments. There Redis should be highly available and deployed as a cluster.
$ docker pull redis:5.0.10
$ docker run -itd --rm --name redis --network tyk -p 6379:6379 redis:5.0.10
3. Create Tyk Configuration
Create a new directory, which will hold your configuration and API definitions. Additionally, create a new file that contains the following JSON. I’d suggest
tyk.conf as the name for this file. As we are using the Tyk API Gateway without any other (enterprise) products, this config is based on the
tyk.standalone.conf in this repository. I removed some attributes, that isn’t important for now. The most important change I made is removing the
secret as we will set this via an environment variable to not expose it in the configuration.
Most values are quite self-explanatory. Head over to Tyk’s documentation to learn more about them.
4. Pull and Run Tyk Gateway
Now it‘s time to run the API Gateway. Execute the below-printed commands to pull the Docker image for the API Gateway and to run it.
$ docker pull tykio/tyk-gateway:latest
$ docker run -d \
--name tyk_gateway \
--network tyk \
-p 8080:8080 \
-e TYK_GW_SECRET=[YOUR-SECRET] \
-v $(pwd)/tyk.conf:/opt/tyk-gateway/tyk.conf \
-v $(pwd)/apps:/opt/tyk-gateway/apps \
Below the arguments of the
run command is explained:
--name tyk_gateway: Sets the name of the container.
--network tyk: Connects the container to the network
-p 8080:8080: Exposes port 8080 of the container to port 8080 of your system.
-e TYK_GW_SECRET=[YOUR-SECRET]: Sets the environment variable that holds your secret.
-v $(pwd)/tyk.conf:/opt/tyk-gateway/tyk.conf: Bind mounts the configuration we created in the previous step to the configuration file inside the container.
-v $(pwd)/apps:/opt/tyk-gateway/apps: Bind mounts the app directory in our current folder to the directory
opt/tyk-gateway/appsinside the container.
5. Verify Everything Is Set Up Correctly
To verify that the API Gateway is up and running, you can simply send a
GET request to
/hello. The answer should look similar to the below printed JSON.
Edit Tyk’s Configuration
Editing your configuration is quite easy. As we created a bind mount for the configuration, you can simply edit the configuration file we created earlier to make config changes.
NOTE: Vim doesn’t save a file directly, but creates a new file and copies it into place. Therefore the inode of the file is being changed and saving the file breaks the bind mount. To avoid this, you need to set
set backupcopy=yesin vim. If you want to make this setting permanent, you need to add it to the file
~/.vimrc. If this file doesn’t exist, you can simply create it and vim will take notice of it.
Now all that’s left to do is reloading the API Gateway. This can be achieved with a
GET call to
Add an API
Now, that the API Gateway is up and running, it’s time to add an API to it. You can either add an API by making a request to the REST API of the API Gateway or by adding the API definition to the folder
/opt/tyk-gateway/apps, which we mounted to the
./apps directory earlier. I’ll use the second option in this guide, as I prefer to have configurable files. If you opt for the first possibility you can simply send a
POST request to
/tyk/apis that contains the API definition in its body. Please don’t forget to set the
x-tyk-authorization header in this request.
We’ll add an API that is available at
/httpbin and proxies requests to
https://httpbin.org. The minimal configuration for this API can be found in the below Gist. Again, a description of all attributes can be found in Tyk’s documentation.
Navigate to the
./apps directory Docker created for you and create a new file
httpbin.json that contains the above-shown JSON.
The last step, to add a new endpoint, is to reload the API Gateway with the following request.
$ http :8080/tyk/reload 'x-tyk-authorization:[YOUR-SECRET]'
That’s it. As you can see in the Gist below, requests to
localhost:8080/httpbin are proxied to
Authentication With Tyk
There are several ways to implement authentication for APIs. Tyk supports the following methods to authenticate. Since Tyk version 2.3, it’s also possible to chain authentication middleware.
- Basic Authentication
- Bearer Token
- HMAC Request Signing
- JSON Web Token
- OpenID Connect
Tyk also provides support for OAuth 2.0 and can even serve as a provider for authorization and access tokens.
As this guide aims to get you started with Tyk, this section doesn’t cover all authentication and authorization methods. To provide a rough understanding of how authentication works, Bearer Token and Basic Authentication are explained in the next subsections.
Bearer Token authentication is the default way of securing APIs with Tyk. In the definition of the API we added earlier, we set the
use_keyless attribute to
true to expose the API without authentication. Below you can see an API definition, with Bearer Token authentication. It is very similar to the definition we used above. The values for
id changed and
use_keyless has been removed.
If you reload your API Gateway, requests to
/httpbin are still working as before, because they belong to the previously created API. If you make a request to
/httpbin/bearer the API Gateway will return
401 Unauthorized, with the error
Authorization field missing. After setting the
Authorization header to any value (we’ll issue a token in a second), the gateway will return
403 Forbidden —
Access to this API has been disallowed.
The API is ready now, therefore we need to issue a token to access it. To do so, we need to define a session object. Below a minimal definition is shown. It grants access to the API with ID 2 (the one we just created) in organization 1. With a session object like the one below, you can configure lots of things. Check out the official documentation to learn more about that.
Now send the session object with a POST request to
/tyk/keys to issue an authentication token.
Your token is contained in the
key field of the response. It needs to be sent in the
Authorization header of all requests to
To configure Basic Authentication we will create a new API. The definition looks similar to the ones you already know, but
listen_path changed. The most important change is that the field
use_basic_auth is added and set to
true. This tells Tyk to secure this endpoint with Basic Auth instead of Bearer Tokens. You don’t need to configure anything else, as Tyk knows how to handle the Basic Auth standard.
After reloading the API Gateway, requests to
httpbin/basic will fail if no or an invalid user is passed. To create a new user, we need to create a session token. You can see the configuration for this token in the snippet below. Again, the definition is very similar to the one we used to issue a Bearer Token. Of course
id of the API changed, as we want to create a user for API 3 now. Further, the password of the user was added within
Now everything is ready to publish the user to the API Gateway with a POST request to
/tyk/keys/[USERNAME]. The following snippet shows how to create a new user with the name
Now you can make requests with the newly created credentials.
Within this introduction, we covered how to get the Tyk API Gateway up and running with Docker and how to define basic APIs and simple authentication mechanisms.
That’s it. Thanks a lot for reading this article! I hope it helps you to get into the Tyk API Gateway.