Security

Protect your account and data with two-factor authentication, personal access tokens, audit logging, and other security features.

Two-Factor Authentication (2FA)

Add an extra layer of security to your account with TOTP-based two-factor authentication. When enabled, you'll need both your password and a time-based code from your authenticator app to log in.

Setting Up 2FA

1. Go to Profile in the sidebar
2. Scroll to the Two-Factor Authentication section
3. Click Enable 2FA
4. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.)
5. Enter the 6-digit code from your app to verify
6. Save your backup codes — these are single-use codes that let you log in if you lose access to your authenticator app

Logging In with 2FA

1. Enter your email and password as usual
2. You'll be prompted for a 6-digit code
3. Enter the code from your authenticator app
4. Alternatively, click Use backup code and enter one of your backup codes

Disabling 2FA

To disable 2FA, go to Profile → Two-Factor Authentication → Disable. You'll need to confirm with your current 2FA code or a backup code.

Supported Authenticator Apps

Any TOTP-compatible authenticator works. Popular options:

• Google Authenticator — Android, iOS
• Authy — Android, iOS, Desktop (with cloud backup)
• 1Password — Built-in TOTP support
• Bitwarden — Built-in TOTP support (Premium)
• Microsoft Authenticator — Android, iOS

Personal Access Tokens (PAT)

Personal Access Tokens let you authenticate with the API without using your password. They are ideal for scripts, CI/CD pipelines, and third-party integrations.

Creating a Token

1. Go to Profile in the sidebar
2. Scroll to the Personal Access Tokens section
3. Click Generate New Token
4. Enter a descriptive name (e.g., "CI Pipeline", "Monitoring Script")
5. Click Generate
6. Copy the token immediately — it will only be shown once

Using a Token

Include the token in the Authorization header of your API requests:

curl -H "Authorization: Bearer pat_abc123..." \
  https://your-domain.com/api/checks/

import requests

headers = {"Authorization": "Bearer pat_abc123..."}
response = requests.get(
    "https://your-domain.com/api/checks/",
    headers=headers
)
print(response.json())

Token Management

In the Profile page, you can see all your active tokens with:

• Name — The descriptive name you gave the token
• Created — When the token was created
• Last Used — When the token was last used (and from which IP address)
• Revoke — Permanently disable the token

Token Format

All personal access tokens start with the prefix pat_ followed by a random string. The token is hashed with SHA-256 on the server — the raw token is never stored. This means even if the database is compromised, tokens cannot be extracted.

Audit Log

The audit log records important actions performed within your organization. This provides accountability and helps investigate security incidents.

What's Logged

The audit log captures actions including:

• User logins and logouts
• Check creation, modification, and deletion
• Notification channel changes
• Organization settings changes
• Member management (invites, role changes, removals)
• Token creation and revocation
• 2FA enable/disable
• Maintenance window operations
• Status page modifications

Viewing the Audit Log

Organization admins and owners can access the audit log from the organization settings. Each entry shows:

• Timestamp — When the action occurred (UTC)
• User — Who performed the action
• Action — What was done (e.g., "check.created", "member.role_changed")
• Details — Additional context (e.g., check name, old/new role)
• IP Address — Source IP of the request

Exporting Audit Logs

Audit logs can be exported for compliance or archival purposes via the API or the export button in the UI.

CSRF Protection

SysTeam HealthChecks uses a double-submit cookie pattern for CSRF (Cross-Site Request Forgery) protection. This prevents malicious websites from making API requests on your behalf.

How it works:

1. The server sets a csrf_token cookie on login
2. For state-changing requests (POST, PUT, DELETE), the frontend sends the token in the X-CSRF-Token header
3. The server validates that the header matches the cookie

This is handled automatically by the web interface. If you're making API calls from scripts, use Personal Access Tokens instead — PAT-authenticated requests are exempt from CSRF checks.

API Rate Limiting

To protect against abuse, API endpoints have rate limits:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Webhook Security (HMAC Signing)

When using custom webhook notification channels, you can configure HMAC-SHA256 signing to verify that webhook payloads are genuinely from SysTeam HealthChecks.

How It Works

1. Set a webhook secret when creating a webhook notification channel
2. SysTeam includes an X-Webhook-Signature header with each request
3. The signature is an HMAC-SHA256 hash of the request body using your secret
4. Your server verifies the signature before processing the payload

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
signature = request.headers.get("X-Webhook-Signature")
if not verify_signature(request.body, signature, YOUR_SECRET):
    return 403, "Invalid signature"

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// In your webhook handler:
const signature = req.headers['x-webhook-signature'];
if (!verifySignature(req.rawBody, signature, YOUR_SECRET)) {
  return res.status(403).send('Invalid signature');
}

IP Whitelist

Organization admins can restrict API access to specific IP addresses or CIDR ranges. This is useful for locking down access to your office network or VPN.

Configure in Organization Settings → IP Whitelist. Add individual IPs (e.g., 10.0.0.1) or CIDR ranges (e.g., 192.168.1.0/24). Leave empty to allow access from all IPs.

Secret Masking

SysTeam HealthChecks automatically masks sensitive data in API responses:

• Notification channel configs hide tokens, passwords, and API keys
• Check configurations mask database passwords and authentication credentials
• Webhook secrets are never returned in API responses
• Agent keys are hashed and never stored in plain text

This prevents accidental exposure of secrets through API access, browser dev tools, or log files.

SSO Security

When using Single Sign-On, additional security measures apply:

• SSO + MFA — Users with linked SSO accounts can still enable 2FA for password-based login. SSO login follows the IdP's MFA policy.
• Account linking verification — Linking an SSO identity requires matching the email address to prevent account takeover via unverified SSO emails.
• SAML assertion validation — SAML responses are validated against the IdP certificate, audience restriction, and time window.
• OIDC state parameter — OAuth2/OIDC flows use a cryptographic state parameter to prevent CSRF during the redirect flow.

Session Management

SysTeam HealthChecks uses JWT tokens with token rotation for session management:

• Access tokens — Short-lived (15 minutes), stored in cookies with HttpOnly and Secure flags
• Refresh tokens — Longer-lived (7 days), used to obtain new access tokens without re-authenticating
• Token rotation — Each refresh token can only be used once. Using a refresh token issues a new one and invalidates the old.
• Session timeout — Configurable per-organization in settings. Auto-logout after inactivity.

Security Best Practices

• Enable 2FA for all users, especially admins and owners
• Use PATs instead of passwords for scripts and automation
• Review audit logs regularly for unexpected activity
• Rotate tokens periodically and revoke unused ones
• Use IP whitelist to restrict API access when possible
• Verify webhook signatures to prevent spoofed notifications
• Use HTTPS for all communication (agent URLs, webhook endpoints)

Next Steps

• Organization settings (permissions, quiet hours)
• Configure notification channels
• API reference