Authentication

Requests to the sovseal API require bearer token authentication. The system handles authentication differently depending on whether you are doing programmatic agent synchronization or managing account resources.

Authentication Headers

All API calls must include the standard HTTP Authorization header:

Authorization: Bearer <TOKEN>

Token Taxonomy

1. API Keys (sov_live_)

API keys authenticate your agent's requests when communicating with the cloud sync service or using paid tier resources.

• Format: sov_live_[base62_secret]
• Behavior: The server looks up the SHA-256 hash of this key against the database (api_keys table) and checks active user subscription limits.
• Security: The server never stores the key in plaintext.

2. Local Zero-Configuration Setup

For local-first development and testing, sovseal works out of the box with zero configuration. The local client/MCP server automatically manages a secure local-only project token behind the scenes. You do not need to configure, copy, or manage this key.

When you are ready to enable cloud sync across devices or unlock production quotas, simply copy your API Key (sov_live_...) from the dashboard and set it as your SOVSEAL_API_KEY.

3. Session JWTs (Dashboard Auth)

Administrative dashboard endpoints (like billing, settings, teams, and API key management) require the user's primary Supabase Auth session JWT rather than an agent API key.

• Behavior: The server parses the JWT, extracts auth.uid(), and maps it to the public users table.
• Errors: Attempting to use an API Key or auto-generated local token on dashboard routes will result in a 401 session_jwt_required error.