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. Project Tokens (sov_proj_)

Project tokens allow developers to spin up local agent vector stores immediately with zero sign-up friction.

• Format: sov_proj_[uuid_v4]
• Behavior: Self-asserting and completely stateless. The server does not perform a database lookup for this token; the project ID itself serves as the namespace.
• Pricing: Free tier. Subject to standard rate-limiting.
• Derivation: The client derives the unique server-blind database key using:

agent_id = sha256(project_id + ":" + client_encryption_key)

2. Live API Keys (sov_live_)

Live API keys are used for paid production agents requiring higher throughput, database backups, and custom billing quotas.

• 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.

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 a sov_live_ or sov_proj_ key on dashboard routes will result in a 401 session_jwt_required error.