Humanitec API gateway

When creating an app, you have the option to enable the Humanitec API gateway. If you do so, all of your modules will be able to communicate with each other over a core authentication layer. All of the endpoints will be exposed as part of a single API

First, you must configure your modules to connect to it. This page will explain how.

Note: We recommend reading through the gateway documentation before completing this tutorial.


In addition to the basic deployment requirements, your module must satisfy these conditions:

  1. It must follow the OpenAPI (Swagger) spec and expose a swagger.json file at the /docs endpoint.
  2. It must use an OAuth2 library with support for JSON Web Tokens (JWTs).

Implement JWT authorization

Next, you need to implement the gateway’s authorization method.

For external requests to modules, the gateway uses an OAuth2 flow to issue JSON Web Tokens (JWTs) signed with RS256.

Inside the container where the module is deployed, Walhall exposes the gateway’s public key as the environment variable JWT_PUBLIC_KEY_RSA_BIFROST. The module must use this environment variable to decode requests from the gateway.

The gateway passes the JWT to the module in the Authorization HTTP header using the format JWT {token}. Example:

Authorization: JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJiaWZyb3N0IiwiZXhwIjoxNTYwNjA0OTc2LCJpYXQiOjE1NjA1MTg1NzYsImNvcmVfdXNlcl91dWlkIjoiODJiZGI2YTMtMjExOS00MThmLThjMmQtY2FhYjdlYmI4OTc1Iiwib3JnYW5pemF0aW9uX3V1aWQiOiJiMjY1YmFkNS1iODEyLTRmNDItYjNlZS0zNDFlYmJiNzJjNmIiLCJzY29wZSI6InJlYWQgd3JpdGUiLCJ1c2VybmFtZSI6ImFkbWluIn0.CV8PafWuGDZSpWRI5wC6btO6cyt9udI9P5uLBdnHzVhbbIY-LH1o3qBgnRf0OAreUhRfl7zBTBMNO56pbyWeyg

Example using PyJwt

Here’s an example using the PyJwt library. It takes the encoded_jwt from the HTTP header and decodes it with the JWT_PUBLIC_KEY_RSA_BIFROST environment variable:

import jwt

jwt.decode(encoded_jwt, os.environ['JWT_PUBLIC_KEY_RSA_BIFROST'], algorithms=['RS256'])

The JWT payload looks like this:

	"core_user_uuid": "fd76ce0c-d8be-4aa6-91ed-59e698f6af60",
	"exp": 1560472728,
	"iat": 1560436728,
	"iss": "bifrost",
	"organization_uuid": "70f0d039-e3d9-427e-b161-4e95dbd9e918",
	"scope": "read write",
	"username": "admin"
  • core_user_uuid: UUID of the CoreUser who initiated the request.
  • exp: Datetime when the token expires.
  • iat: Datetime when the token was issued.
  • iss: Issuer of the JWT. This will always be bifrost.
  • organization_uuid: UUID of the Organization that contains the CoreUser who initiated the request.
  • scope: Permission scopes granted in the request by the gateway.
  • username: The username of the CoreUser who initiated the request.

Add module to your Walhall app and deploy

Now you have completed the minimum necessary configurations to make your module work with the gateway. The last step is to add it to a Walhall app and deploy it.

Appendix: Reserved endpoint names

The following endpoint names are reserved by the gateway and may not be implemented in your modules’ APIs:

  • /admin
  • /oauth
  • /health_check
  • /docs
  • /complete
  • /disconnect
  • /static
  • /graphql
  • /workflow
  • /core
  • /logicmodule
  • /user
  • /group
  • /milestone
  • /organization