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

# Authentication

> How to authenticate with the Wu-Weism API using session tokens, and how to supply your own AI provider keys.

All Wu-Weism API endpoints require an authenticated session. Unauthenticated requests return `401 Unauthorized`.

## Browser sessions

When you sign in at [wuweism.com](https://wuweism.com), your session is established automatically. All API requests made from the browser include your session credentials — no extra setup required.

## Programmatic access

To call the API from outside a browser (scripts, automation, server-side integrations), include your session token in every request:

```http theme={null}
Authorization: Bearer <your-session-token>
```

<Steps>
  <Step title="Sign in to your account">
    Go to [wuweism.com](https://wuweism.com) and sign in with your email and password.
  </Step>

  <Step title="Obtain your session token">
    After signing in, retrieve your access token from your account settings under **API Access**, or from the session cookie set by your browser (`sb-access-token`). You can also use the [Supabase client library](https://supabase.com/docs/reference/javascript/auth-signinwithpassword) to sign in programmatically and receive the token in the response.
  </Step>

  <Step title="Pass the token on every request">
    Include the token in the `Authorization` header:

    ```http theme={null}
    Authorization: Bearer <your-session-token>
    ```
  </Step>

  <Step title="Refresh the token before it expires">
    Session tokens are short-lived. Refresh your token before it expires to avoid `401 Unauthorized` errors mid-session. Your auth library will handle this automatically if you use the SDK to sign in.
  </Step>
</Steps>

## Example request

```http theme={null}
POST /api/causal-chat HTTP/1.1
Host: wuweism.com
Authorization: Bearer <your-session-token>
Content-Type: application/json
X-BYOK-Api-Key: sk-ant-... (optional — your own Anthropic key)

{
  "question": "Does cortisol exposure causally increase hippocampal volume reduction?",
  "sessionId": "uuid-here",
  "providerId": "anthropic"
}
```

## Request headers

<ParamField header="Authorization" type="string" required>
  Your Wu-Weism session token, formatted as `Bearer <token>`. Required on every API request.
</ParamField>

<ParamField header="X-BYOK-Api-Key" type="string">
  Your own AI provider API key (Anthropic, OpenAI, or Gemini). Optional. When provided, Wu-Weism uses this key for the underlying model call. See [BYOK keys](#byok-ai-provider-keys) below.
</ParamField>

## BYOK AI provider keys

Causal chat and related AI-powered endpoints support Bring Your Own Key (BYOK). Pass your AI provider's API key in the `X-BYOK-Api-Key` header to use your own account quota and billing.

Supported providers and their `providerId` values:

| Provider      | `providerId` |
| ------------- | ------------ |
| Anthropic     | `anthropic`  |
| OpenAI        | `openai`     |
| Google Gemini | `gemini`     |

<Note>
  **Session token vs. BYOK key — these are two different credentials.**

  * `Authorization: Bearer <token>` — your Wu-Weism session token. This authenticates you to the Wu-Weism platform.
  * `X-BYOK-Api-Key: <key>` — your API key from Anthropic, OpenAI, or Google. This is forwarded directly to the AI provider. Wu-Weism does not store this key beyond the duration of the request.
</Note>

## Error responses

| Status                      | Body                                                                     | Cause                                                       |
| --------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------- |
| `401 Unauthorized`          | `{ "error": "Unauthorized" }`                                            | Missing or invalid session token                            |
| `400 Bad Request`           | `{ "error": "Invalid providerId" }`                                      | `providerId` is not `anthropic`, `openai`, or `gemini`      |
| `400 Bad Request`           | `{ "error": "Invalid model for selected provider" }`                     | The specified model ID is not valid for the chosen provider |
| `500 Internal Server Error` | `{ "error": "Configuration Error: Missing API key for provider '...'" }` | No AI provider key configured and no BYOK key supplied      |

<Warning>
  Do not share your session token or BYOK keys. Treat them as passwords. If a token is compromised, sign out of all sessions from your Wu-Weism account settings to invalidate it.
</Warning>