Skip to main content

​
Overview

The /hello endpoint is a health check endpoint that verifies the SuperTokens Core server is running and can connect to the database. This endpoint is useful for monitoring, load balancers, and integration tests. Key Features:
  • No authentication required
  • No API version header required
  • Supports all HTTP methods (GET, POST, PUT, DELETE)
  • Tests database connectivity
  • Implements rate limiting (200 requests per window)
  • App-specific (can be scoped to specific apps)

​
Endpoint

GET /hello
POST /hello
PUT /hello
DELETE /hello
Base URL: http://localhost:3567

​
Request

​
Headers

No headers required. API key and version headers are optional and ignored.

​
Query Parameters

None.

​
Request Body

None.

​
Response

​
Success Response

Status Code: 200 OK Content-Type: text/plain Body: 
Hello
If the server is healthy and database connections are working, returns the plain text string "Hello".

​
Rate Limited Response

Status Code: 200 OK Body (in testing mode): 
RateLimitedHello
When rate limited in testing mode, returns "RateLimitedHello". In production mode, still returns "Hello" even when rate limited.

​
Error Response

Status Code: 500 Internal Server Error If the server cannot connect to the database or a storage exception occurs, returns a 500 error with a ServletException.

​
Examples

​
cURL

curl http://localhost:3567/hello
Response: 
Hello

​
App-Specific Request

curl http://localhost:3567/appid-myapp/hello

​
Tenant-Specific Request

curl http://localhost:3567/tenant1/hello

​
JavaScript (Node.js)

const response = await fetch('http://localhost:3567/hello');
const text = await response.text();
console.log(text); // "Hello"

​
Python

import requests

response = requests.get('http://localhost:3567/hello')
print(response.text)  # "Hello"

​
Implementation Details

​
Rate Limiting

The endpoint implements rate limiting with a limit of 200 requests per window per app. The rate limiter is app-specific, so different apps have separate rate limits. Source: View source

​
Database Health Check

The endpoint tests database connectivity by calling storage.getKeyValue() on all storage instances for the app. This ensures that:
  • The database connection is active
  • All storage layers are responding
  • The core can read from the database
Source: View source

​
Use Cases

​
Health Monitoring

#!/bin/bash
# Simple health check script
if curl -f http://localhost:3567/hello > /dev/null 2>&1; then
  echo "SuperTokens is healthy"
  exit 0
else
  echo "SuperTokens is down"
  exit 1
fi

​
Docker Health Check

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3567/hello || exit 1

​
Kubernetes Liveness Probe

livenessProbe:
  httpGet:
    path: /hello
    port: 3567
  initialDelaySeconds: 10
  periodSeconds: 30

​
Error Handling

If the /hello endpoint returns a 500 error, check your database connection and storage configuration. This typically indicates a storage layer issue.
Common Issues:
  • Database connection timeout
  • Storage plugin not initialized
  • Database credentials incorrect
  • Network connectivity issues

​
Notes

  • This endpoint is also available at the root path / (see NotFoundOrHelloAPI)
  • Rate limiting is transparent to the client - no error is returned
  • The endpoint works across all HTTP methods for maximum compatibility
  • No API key required makes it suitable for public health checks

Configuration

Get server configuration details

API Overview

Learn about authentication and error handling

Build docs developers (and LLMs) love

Get started for freeTalk to us