API Keys

API keys provide programmatic access to Thallus for scripts, CI/CD pipelines, and external tool integrations. Unlike JWT sessions used by the web interface, API keys are long-lived credentials designed for server-to-server communication.

Requirements

API key creation requires the api_access feature, which is available on Pro and Enterprise plans. Starter plan users will see the API Keys tab but cannot create new keys until they upgrade. See Billing & Plans for plan details.

Creating a key

Navigate to Settings → API Keys and click Create API Key. Provide a descriptive name and an optional expiration period.

After creation, the raw key is displayed exactly once:

API Key Created
thal_G1x2mN8pQ4wR7vB3kL...
Copy
Copy this key now. You won't be able to see it again.

The key follows the format thal_<random>. Copy and store it securely (e.g., in a secrets manager or environment variable). Once you close this dialog, only the prefix and suffix are visible.

Key storage and security

API keys are hashed at rest — Thallus never stores raw keys. After creation, the dashboard shows only a masked preview:

Production API
thal_G1x2...7kPm
Last used 2h ago
Expires Apr 15, 2026
Revoke
CI Pipeline
thal_Qw9z...nR3x
Last used 5d ago
No expiration
Revoke
Old Integration
thal_Xm4k...pL2w
Revoked

Each key entry shows: - Name — the label you gave the key - Prefix/suffix — masked key identifier (e.g., thal_G1x2...7kPm) - Status — active (green) or revoked (red) - Last used — when the key was last successfully authenticated - Expiration — when the key will automatically expire (if set)

Using API keys

Authenticate requests by including the raw key in the X-API-Key header:

X-API-Key: thal_G1x2mN8pQ4wR7vB3kL...

The API key grants the same permissions as your user account. All actions performed with the key are attributed to your user in audit logs.

API keys vs JWT sessions

JWT Session API Key
JWT Session API Key
Use case Web browser sessions Scripts, CI/CD, integrations
Lifetime Short-lived, auto-refreshed Long-lived, optional expiration
Delivery Authorization: Bearer header + cookie X-API-Key header
Revocation Password change revokes all sessions Individual key revocation
Feature gate None (all plans) Requires Pro or Enterprise
Identity Login credentials Single key string

Use JWT sessions for interactive web use. Use API keys for automated access where you can't go through the login flow.

Revoking keys

Click Revoke on any active key to immediately invalidate it. Revoked keys:

  • Stop working immediately — any request using the key receives a 401 error
  • Remain visible in the key list with a "Revoked" status (for audit trail purposes)
  • Cannot be un-revoked — create a new key instead

Keys that reach their expiration date are also automatically invalidated, but they remain in the "active" visual state until explicitly revoked or the record is cleaned up.