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

# Authentication

> Generate an API key from the Wrenn dashboard and authenticate using WRENN_API_KEY, the api_key constructor argument, or the X-API-Key HTTP header.

Every request to the Wrenn API must include a valid API key. You can provide it through an environment variable — which the SDK picks up automatically — or pass it explicitly when constructing a `Capsule`. API keys are scoped to your team and have the prefix `wrn_`.

## Get an API key

Open the [Wrenn dashboard](https://app.wrenn.dev), navigate to **Settings → API Keys**, and create a new key. The plaintext key is shown only once at creation time — copy it immediately and store it somewhere safe.

<Warning>
  Never commit API keys to source control. Use environment variables, a secrets manager, or a `.env` file excluded from version control.
</Warning>

## Authenticate with the SDK

You have two options for providing credentials to the SDK.

<CodeGroup>
  ```bash Environment variable (recommended) theme={null}
  export WRENN_API_KEY="wrn_your_api_key_here"
  ```

  ```python Direct constructor argument theme={null}
  from wrenn import Capsule

  capsule = Capsule(api_key="wrn_your_api_key_here")
  ```
</CodeGroup>

When `WRENN_API_KEY` is set, you never need to pass `api_key=` explicitly:

```python theme={null}
from wrenn import Capsule

# Reads WRENN_API_KEY from the environment
with Capsule(template="minimal", wait=True) as capsule:
    result = capsule.commands.run("echo hello")
    print(result.stdout)
```

## Override the base URL

By default the SDK points to `https://app.wrenn.dev/api`. You can override this with the `WRENN_BASE_URL` environment variable or the `base_url=` argument:

<CodeGroup>
  ```bash Environment variable theme={null}
  export WRENN_BASE_URL="https://app.wrenn.dev/api"
  ```

  ```python Direct constructor argument theme={null}
  from wrenn import Capsule

  capsule = Capsule(base_url="https://your-self-hosted-instance.example.com/api")
  ```
</CodeGroup>

## Authenticate REST requests directly

If you call the API directly rather than through the SDK, include your key in the `X-API-Key` header:

```bash theme={null}
curl https://app.wrenn.dev/api/v1/capsules \
  -H "X-API-Key: wrn_your_api_key_here"
```

## Error codes

| Status | Meaning                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `401`  | The API key is missing or invalid. Check that `WRENN_API_KEY` is set and the key hasn't been deleted. |
| `403`  | The key is valid but not authorized to access this resource.                                          |

The SDK surfaces these as typed exceptions:

```python theme={null}
from wrenn import WrennAuthenticationError, WrennForbiddenError

try:
    capsule = Capsule(api_key="wrn_bad_key")
except WrennAuthenticationError as e:
    print(e.message)     # "unauthorized"
    print(e.status_code) # 401
```