Skip to Content
API ReferenceAuthentication

Authentication

API Keys

API keys are the recommended way to authenticate programmatic access to CodeStax.

Creating an API Key

  1. Go to Settings → API Keys
  2. Click Generate New Key
  3. Set a name and optional expiry (in days)
  4. Choose permissions:
    • read:scans — Read scan results
    • read:repos — Read repository data
  5. Click Create

Important: The API key is only shown once. Copy and store it securely.

Key Format

ch_a1b2c3d4e5f6...  (64 hex characters with ch_ prefix)

The dashboard shows a truncated prefix for identification: ch_a1b2c3d4...

Using API Keys

Include the API key in the X-API-Key header:

curl -H "X-API-Key: ch_your_api_key_here" \
  https://codestax.co/api/scans

Key Management

ActionHow
List keysSettings → API Keys (shows name, prefix, last used, created date)
RevokeClick the delete icon next to any key
Track usageEach key shows last_used timestamp and use_count

Limits

PlanMax API Keys
Free0
Pro2
Team10
EnterpriseUnlimited

JWT Authentication

The web application uses JWT tokens for session management. This is handled automatically by the frontend and is not intended for direct API use.

Token Lifecycle

  1. Login — POST /auth/login returns an access token
  2. Use — Include in Authorization: Bearer <token> header
  3. Refresh — POST /auth/refresh exchanges an expired token for a new one
  4. Expiry — Tokens expire after a configured period

For programmatic access, use API keys instead of JWT tokens. They’re simpler and don’t require refresh logic.

OverviewEndpoints