WSO2 Microgateway — Securing APIs with API Key.

Menaka Jayawardena
4 min readJul 19, 2020

In modern Organizations, most of the functions are handled via APIs. These APIs expose sensitive and valuable information which should be only consumed by the right person or entity. If a wrong person can access these APIs, the entire organization could be in a vulnerable state.

Due to the above reason, API Security is The #1 priority in any API Driven organization.

WSO2 Microgateway is a lightweight, super-fast, cloud-native, developer-focused, and 100% open-source product which enables you to expose microservices as managed APIs. It also provides an easy to use, strong security layer for APIs which helps the user to easily configure and enforce proper authentication/ authorization mechanisms to secure their APIs.

There are several authentication mechanisms, that can be used to secure APIs in WSO2 Microgateway.

  • Basic Authentication
  • OAuth2
  • API Key
  • MutualSSL

What is API Key

An API Key is a unique Application Token which is used to identify the user. This is often used for development uses where application developers can use the API Keys to invoke particular API resources from a Web App/ Mobile App.

Using API Key to secure APIs with Microgateway

Microgateway provides full support for API Key authentication and also provided with an API Key generation service.

The API Key Issuer Service

Microgateway is equipped with a Security Token Service which can be used to generate API Keys. The generated API Key will be a self-contained JWT token. The API Key STS can be configured via the <MGW_HOME>/conf/micro-gw.conf file.

Restrict API Keys for specific APIs

Generally, an API Key can be used to invoke any API (with security scheme is set to API key). But, if it is required to restrict an API key to be used for a specific API or version, it can be configured using the [[apikey.issuer.api]] section, providing the required API Name and the list of versions.

Generating API Key

An API Key can be generated as follows.

curl -k -X GET “https://localhost:9095/apikey" -H “Authorization: Basic YWRtaW46YWRtaW4=”



Using API Key to Invoke an API

The APIs exposed via Microgateway are by-default secured with OAuth2. Therefore, in order to use API Key, the security scheme of the API should be changed to API key.

Defining Security Scheme

The API Key security scheme can now be used in API level or individual resource level.

Now let’s get our hands dirty with some exercise.

Practical Exercise: Publish and invoke an API using API Key with Microgateway

  • Step 1: Initializing API Project

If you are new to WSO2 API Microgateway, here is how to get started with creating an API.

Download the WSO2 Microgateway and Microgateway Toolkit [1] for your platform (OS) and extract them. Those will be MGW_HOME and MGW_TOOLKIT_HOME.

To initialize an API Project, run the following command.

<MGW_TOOLKIT_HOME>/bin/micro-gw init petstore

A new directory with the name ‘petstore’ will be created.

  • Step 2: Add an API definition

The API Project requires an OpenAPI definition, which should be placed in <PROJECT_HOME>/api_definitions directory. Let’s use the petstore.yaml from[2].

  • Step 3: Update security schemes

In Petstore API, the /pet/{petId} resource is already using api_key authentication scheme. Let’s change the name of the expected header.

  • Step 4: Build and Run Microgateway.

Once the API definition is updated, run the below command to build the Microgateway.

<MGW_TOOLKIT_HOME>/bin/micro-gw build petstore

If no errors occurred, a Microgateway will be built successfully.

Target: <PATH _TO_PROJECT>/petstore/target/petstore.jar

To run the Microgateway, invoke the command below.

<MGW_HOME>/bin/gateway <PATH _TO_PROJECT>/petstore/target/petstore.jar

The following log will be printed if the gateway started successfully.

JAVA_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0_211.jdk/Contents/Home
[ballerina/http] started HTTPS/WSS listener
[ballerina/http] started HTTP/WS listener
2020–07–19 14:09:09,055 INFO [wso2/gateway/src/gateway/utils] — [APIGatewayListener] [-] HTTP listener is active on port 9090
[ballerina/http] started HTTPS/WSS listener
2020–07–19 14:09:09,057 INFO [wso2/gateway/src/gateway/utils] — [APIGatewayListener] [-] HTTPS listener is active on port 9095

  • Step 5: Generate API Key.

Using the below command, generate an API Key. Here we do not alter any API Key issuer configuration.

curl -k -X GET “https://localhost:9095/apikey" -H “Authorization: Basic YWRtaW46YWRtaW4=”

  • Step 6: Invoke the API with API Key.

Invoke the API key with below command.

curl -X GET “https://localhost:9095/v2/pet/10" -H “petstore_key: <API_KEY>” -k


{“id”:10, ”category”:{“id”:19, ”name”: ”6JR75SI-T8Jj0hQf”}, ”name”: ”doggie”, ”photoUrls”: [“O5twvFB8QS3IxUet”], ”tags”:[{“id”:1013, ”name”:”kJqpNQuuouYugNAO”}], ”status”: ”pending”}

Restricting Access.

Let’s alter some configurations and generate an API key again.

Configure the API key issuer config and API Key token config as below in <MGW_HOME>/conf/micro-gw.conf file and re-generate the API key using the command in Step 5.

Decoded API Key

Invoke the API using the API Key.


{“fault”:{“code”:900901, “message”: ”Invalid Credentials”, “description”: ”Invalid Credentials. Make sure you have given the correct access token”}}


API Key is a security mechanism that is used to secure API access. WSO2 API Microgateway is fully supported for issuing API Keys and API Key authentication and allows configuration for optimal use cases.

Download and try all the features of WSO2 API Microgateway.[1]

Join the Microgateway Slack community

Report any issues: