API Key Authentication

Overview

Staxa supports two authentication methods:

1. Clerk JWT: Used by the dashboard. When you're logged into the web UI, every API request from the frontend includes a Clerk JWT in the Authorization header. You don't need to manage this manually.
2. API Keys: Used for programmatic access. Create an API key and include it in the Authorization: Bearer sk_live_... header of your API requests.

Creating an API Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Enter a name for the key (e.g., "CI/CD Pipeline", "Local Development")
4. Choose the mode:
   • Live: Full access to create and manage real tenants
   • Test: For development and testing
5. Click Create
6. Copy the key immediately: it is shown only once and cannot be retrieved later

Using API Keys

Include the key in the Authorization header of every API request:

Authorization: Bearer sk_live_abc123...

All API endpoints accept both Clerk JWTs and API keys. The API determines which type of token it received by checking the prefix: eyJ for JWTs, sk_live_ or sk_test_ for API keys.

Key Security

• API keys are hashed with SHA-256 before storage. Staxa never stores your key in plaintext
• Keys can be revoked immediately from the API Keys settings page
• Revoked keys cannot be un-revoked. Create a new key instead
• Each key has a status: active or revoked
• You can create multiple keys for different use cases (CI/CD, local dev, third-party integrations)

Best Practices

• Never commit API keys to version control
• Use test keys during development, live keys in production
• Rotate keys periodically by creating a new key and revoking the old one
• Give each key a descriptive name so you know what it's used for