Authentication & Security

Sovant uses API key authentication with two supported header formats.

Authentication Headers

Authorization Bearer (Recommended)

curl https://sovant.ai/api/v1/memory \
  -H "Authorization: Bearer sk_live_your_api_key"

x-sovant-api-key (Also accepted)

curl https://sovant.ai/api/v1/memory \
  -H "x-sovant-api-key: sk_live_your_api_key"

Both headers are fully supported. The SDK automatically handles this for you.

Example: Create Memory

curl -X POST https://sovant.ai/api/v1/memory \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User completed onboarding",
    "type": "observation",
    "tags": ["onboarding"]
  }'

# Response
{
  "id": "mem_abc123",
  "content": "User completed onboarding",
  "type": "observation",
  "tags": ["onboarding"],
  "created_at": "2024-01-15T10:30:00Z",
  "ok": true
}

Example: Search Memories

# Using Authorization Bearer
curl -G "https://sovant.ai/api/v1/memory/search" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  --data-urlencode "query=onboarding status" \
  --data-urlencode "limit=5"

# Response
{
  "results": [
    {
      "id": "mem_abc123",
      "content": "User completed onboarding",
      "score": 0.95,
      "type": "observation"
    }
  ]
}

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

429 Rate Limited

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

Check response headers for rate limit info:

X-RateLimit-Limit: Requests per window
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Reset timestamp (Unix)

Security Best Practices

Use environment variables for API keys
Rotate keys quarterly via the dashboard
Never commit keys to version control
Use HTTPS only for all API calls

API Key Management

Manage your API keys from the dashboard:

Create — Generate new keys with a descriptive name
View — See all active keys (the full key is only shown once at creation)
Revoke — Disable a key immediately when it's no longer needed

Keys are scoped to your user account. All memories created with a key belong to the key's owner.