Serve health checks on an admin port

Run liveness checks and control-plane routes on a separate SuperTokens Core port with its own thread pool.

Overview

SuperTokens Core can open a second port, the admin port, with its own request thread pool. Liveness checks and control-plane routes on that port keep responding when the main port’s thread pool is busy with application traffic.

The admin port requires Core 12.4.0 or later.

Before you start

Enable the admin port

Set admin_port to a port that differs from the main port (default 3567). If you don’t set it, Core runs a single port and serves every route on it.

docker run \
    -p 3567:3567 \
    -p 3568:3568 \
    -e SUPERTOKENS_ADMIN_PORT=3568 \
    -d "$SUPERTOKENS_IMAGE"

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

admin_port: 3568

Requests on the admin port don’t count toward the request pool of the main port, and the concurrency cap doesn’t apply to them.

Which routes each port serves

With the admin port enabled, each route belongs to one of three groups:

A request for a route on a port that doesn’t serve it gets a 404 response.

/global-request-stats requires one of the base configuration’s api_keys; an app’s own API key doesn’t unlock it.

Health checks

Use the two health check routes for different purposes:

• GET /livez is a liveness check. It returns 200 OK without reading the database, without an API key, and without a cdi-version header. Point your container’s liveness probe at /livez on the admin port, so that a slow database or a busy main port doesn’t get a healthy process restarted.
• GET /hello reads from the database and works as a readiness check. See Self-host SuperTokens for its limits.

For example, in Kubernetes:

livenessProbe:
  httpGet:
    path: /livez
    port: 3568
readinessProbe:
  httpGet:
    path: /hello
    port: 3567

Change which port serves a route

Use these configurations to move a route to the admin port or to serve it on both ports:

docker run \
    -p 3567:3567 \
    -p 3568:3568 \
    -e SUPERTOKENS_ADMIN_PORT=3568 \
    -e ADMIN_ONLY_PATHS="/ee/license" \
    -d "$SUPERTOKENS_IMAGE"

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

admin_port: 3568
admin_only_paths: "/ee/license"

Core refuses to start if:

• One of the paths doesn’t match a Core API path.
• The same path appears in both lists.
• admin_port is not set.