Skip to content

Authentication and security

Jump to bottom
Ashutosh Das edited this page May 20, 2026 · 1 revision

Authentication & Security

Statfyr includes several layers of security that can be enabled independently depending on your use case.

API Key Authentication

When enabled, every API request must include a Bearer token in the Authorization header.

Enabling

In config.yml:

security:
  enable-api-key: true
  api-key: "your-secret-key-here"

Or set the key via environment variable (recommended for production):

STATFYR_API_KEY=your-secret-key-here

Making Authenticated Requests

GET /api/players
Authorization: Bearer your-secret-key-here

What Happens Without a Valid Key

{
  "success": false,
  "status": 401,
  "error": "Unauthorized"
}

Generating a Strong API Key

On Linux/macOS:

openssl rand -hex 32

On Windows (PowerShell):

[System.Web.Security.Membership]::GeneratePassword(40, 5)

HTTPS / TLS

Statfyr supports TLS via a Java keystore (.jks). When enabled, the API is served over HTTPS.

Step 1 — Generate a Keystore

keytool -genkeypair -alias statfyr \
  -keyalg RSA -keysize 2048 \
  -storetype JKS \
  -keystore plugins/statfyr/keystore.jks \
  -validity 3650

You will be prompted to set a keystore password and fill in certificate details.

Step 2 — Configure Statfyr

https:
  enabled: true
  keystore-path: "plugins/statfyr/keystore.jks"
  keystore-password: "your-keystore-password"

Or override the password via environment variable:

STATFYR_KEYSTORE_PASSWORD=your-keystore-password

Step 3 — Access via HTTPS

https://your-server:8080/api/health

Note: Self-signed certificates will trigger browser warnings. For production, use a certificate signed by a trusted CA (e.g. Let's Encrypt) and import it into the keystore.

CORS

Cross-Origin Resource Sharing (CORS) controls which browser origins are allowed to make requests to the API. This matters when building web-based dashboards.

Configuration

security:
  enable-cors: true
  allowed-origins:
    - "*"

"*" allows any origin — fine for open/public APIs.

For a private dashboard, restrict to your actual domain:

allowed-origins:
  - "https://dashboard.example.com"
  - "https://stats.example.com"

IP Whitelist

Restricts API access to a specific list of IP addresses. Any request from an unlisted IP receives a 403 Forbidden.

Configuration

security:
  enable-ip-whitelist: true
  allowed-ips:
    - "127.0.0.1"
    - "192.168.1.50"
    - "203.0.113.42"

This is the strongest access control option. Use it when only known, trusted machines need API access.

Recommended Production Setup

For a public-facing server, use a combination of all security layers:

security:
  enable-api-key: true
  api-key: ""                      # Set via STATFYR_API_KEY env var
 
  enable-rate-limit: true
  rate-limit-requests: 60
  rate-limit-window-seconds: 60
 
  enable-cors: true
  allowed-origins:
    - "https://your-dashboard.com"
 
  enable-ip-whitelist: false       # Enable this if you have a fixed IP
 
https:
  enabled: true
  keystore-path: "plugins/statfyr/keystore.jks"
  keystore-password: ""            # Set via STATFYR_KEYSTORE_PASSWORD env var
 
docs:
  enabled: false                   # Disable public docs in production

Next: Rate Limiting

Clone this wiki locally