> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate requests to the SomyaLabs API.

Authenticate every request with your **API key**, in **either** header (they're
equivalent):

```bash theme={null}
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](https://playground.somya.ai) (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**.

<Warning>
  Never commit API keys or expose them in client-side code. Call the API from
  your backend and store keys in environment variables.
</Warning>

## 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`:

```bash theme={null}
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`:

```json theme={null}
{
  "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}`.

<Warning>
  Revocation takes effect immediately — any service still using the old key will
  start getting `401`s. Always verify the new key first (step 3).
</Warning>

See [Errors](/guides/errors) for the `401`/auth error shape.