Skip to main content
Authenticate every request with your API key, in either header (they’re equivalent): 
X-API-Key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
Use X-API-Key for server-to-server calls with a SomyaLabs API key. The Authorization: Bearer form is also accepted if it fits your HTTP client better.

​
Create your first key (bootstrap)

Your first key is created from the dashboard — no key needed:
  1. Sign in to the Playground (your account session authenticates you).
  2. Open API keys → Create key, give it a name.
  3. Copy the returned key — it’s shown only once.
Never commit API keys or expose them in client-side code. Call the API from your backend and store keys in environment variables.

​
Create additional keys via the API

Once you have a key (or an authenticated session), you can create more programmatically with POST /v1/api-keys: 
curl -X POST https://api.somya.ai/v1/api-keys \
  -H "X-API-Key: YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production", "description": "server-side key" }'
The new key is returned under data.key: 
{
  "success": true,
  "data": {
    "api_key_id": "…",
    "name": "production",
    "description": "server-side key",
    "key": "sk_…",
    "created_at": "2026-06-30T00:00:00Z"
  }
}

​
Rotating keys

Rotate without downtime — add the new key before removing the old one:
  1. Create a new key (POST /v1/api-keys).
  2. Deploy it to your services (update the env var, roll out).
  3. Verify the new key is serving live traffic (make a real request, check logs/usage).
  4. Drain — give in-flight requests using the old key time to finish.
  5. Revoke the old key: DELETE /v1/api-keys/{api_key_id}.
Revocation takes effect immediately — any service still using the old key will start getting 401s. Always verify the new key first (step 3).
See Errors for the 401/auth error shape.