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

# 401 Unauthorized

> Common causes of first-time 401 errors on the Theo API and how to fix them.

If your first request to the Theo API returns `401 Unauthorized`, it is almost always one of the causes below. Work through them in order.

## 1. The apex → www redirect (most common)

`https://hitheo.ai` 307-redirects to `https://www.hitheo.ai`. Most HTTP clients — including Node 18's built-in `fetch`, curl without `--location-trusted`, and several language runtimes — strip the `Authorization` header on 3xx responses as a security precaution. That leaves the redirected request unauthenticated and the server correctly returns `401 invalid_api_key`.
**Fix:** use the canonical `www` host directly. The SDK defaults to `https://www.hitheo.ai` as of `@hitheo/sdk@0.2.0`; if you pinned `baseUrl` manually, update it:

```typescript theme={null}
// Before
new Theo({ apiKey, baseUrl: "https://hitheo.ai" })

// After
new Theo({ apiKey, baseUrl: "https://www.hitheo.ai" })
// or: omit baseUrl entirely to pick up the default.
```

For raw curl:

```bash theme={null}
# Use www directly
curl -H "Authorization: Bearer $THEO_API_KEY" https://www.hitheo.ai/api/v1/models
```

The CLI diagnostic command catches this automatically:

```bash theme={null}
theo status   # probes both apex and www, warns when your baseUrl is a redirect target
theo verify   # machine-readable JSON diagnostic you can pipe into CI
```

## 2. Missing or malformed API key

Every request (except `GET /api/v1/health`) needs an `Authorization: Bearer theo_sk_...` header. Check:

* The header name is exactly `Authorization`, not `authorization:` with a stray colon or `X-API-Key`.
* The token is prefixed with `theo_sk_` (there is no `theo_sk_test_` variant — all keys are live).
* No leading/trailing whitespace in the token — a trailing newline from a `.env` file is a common cause.
* The key has not been revoked. Check the [API Keys dashboard](https://api.hitheo.ai/dashboard/api-keys).

## 3. Wrong scope on the key

API keys carry scopes (`completions`, `skills`, `tools`, `connectors`, `billing`). A key without the `completions` scope returns `403 missing_scope`, not `401`. If you see a `403` specifically: re-issue the key with the scopes you need, or ask the key's creator to update it.

## 4. Key expired (grace period ended)

When you rotate a key, the old one enters a grace window (configurable, default 60 min) then gets revoked. Requests against an expired key return `401 key_expired`. Rotate on the dashboard or via `POST /api/v1/keys/rotate` and swap the new token into your secret store.

## 5. Clock skew breaking HMAC on webhooks

Unrelated to API key auth, but sometimes reported as "401 on webhooks": webhook signature verification uses the `Theo-Signature` header which is HMAC-SHA256 over the request body. If your server's clock is more than 5 minutes out of sync, the signature won't match. Run `ntpdate -q pool.ntp.org` to check.

## Still stuck?

* Call `theo verify` (or `await theo.verify()` in the SDK) and share the output with support.
* Include the `X-Request-Id` response header in your ticket — every v1 response carries one, and successful responses also expose it as `request_id` in the JSON body. Support can look the request up in logs.
* Check [status.hitheo.ai](https://status.hitheo.ai) for active incidents.