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

# Configuration

> Configure gateway URL, API keys, and environment variables

The Flint AI Python SDK needs two pieces of information to route traffic through the guardrails proxy: a **gateway URL** and an **API key**. You can provide these as function parameters, environment variables, or in a `.env` file.

## Environment variables

Set these variables in your shell or deployment environment to avoid hard coding credentials:

| Variable                        | Required | Description                                                                                                                                                                                          |
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FLINTAI_GATEWAY_URL`           | Yes      | Guardrails proxy URL                                                                                                                                                                                 |
| `FLINTAI_API_KEY`               | Yes      | Your Flint AI API key                                                                                                                                                                                |
| `FLINTAI_LLM_API_KEY`           | No       | Your upstream LLM provider API key, forwarded to the gateway as `X-LLM-API-Key`. Pass explicitly for Google GenAI (can't be auto-extracted); omit to let the proxy use its own upstream credentials. |
| `FLINTAI_POLICY_ID`             | No       | Guardrails policy ID to enforce on requests                                                                                                                                                          |
| `FLINTAI_ALLOWED_GATEWAY_HOSTS` | No       | Comma-separated allowlist of permitted gateway hostnames. Defaults to `app.flintai.dev`. Set to `*` to allow any host.                                                                               |
| `AGENT_ID`                      | No       | Agent identifier attached to guardrails requests                                                                                                                                                     |
| `AGENT_NAME`                    | No       | Agent name attached to guardrails requests                                                                                                                                                           |

When environment variables are set, you can call `wrap()` without passing credentials:

```python theme={null}
import openai
import flintai

client = openai.OpenAI()
client = flintai.wrap(client)
```

### `.env` file support

Install the `[dotenv]` extra to load variables from a `.env` file automatically:

```bash theme={null}
pip install "flintai-sdk-py[dotenv]"
```

```bash title=".env" theme={null}
FLINTAI_GATEWAY_URL=https://app.flintai.dev
FLINTAI_API_KEY=your-flintai-api-key
FLINTAI_LLM_API_KEY=your-llm-api-key
```

The SDK reads `.env` from the current working directory on first use.

### Precedence

When the same setting is provided in multiple places, the SDK uses this order:

1. **Explicit parameters** passed to `wrap()` or `init()`
2. **Environment variables** (`FLINTAI_*`)
3. **`.env` file** (if `[dotenv]` is installed)

## Gateway URL

The gateway URL is your Flint AI guardrails proxy endpoint. Find it in [Flint AI Platform](https://app.flintai.dev):

1. Navigate to **Agents** and select your agent
2. Open the **Sessions** tab
3. The gateway URL is shown in the code snippet

<Note>
  The gateway URL must use `https://`. Plaintext `http://` is only allowed for `localhost`, `127.0.0.1`, and `::1` (local development). The SDK warns when using HTTP, even on loopback.
</Note>

### Gateway host allowlist

By default, the SDK only allows connections to `app.flintai.dev`. This prevents credentials from being accidentally sent to an unintended endpoint. To use a self-hosted gateway, set `FLINTAI_ALLOWED_GATEWAY_HOSTS`:

```bash theme={null}
# Single host
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com

# Multiple hosts
export FLINTAI_ALLOWED_GATEWAY_HOSTS=gateway.yourcompany.com,gateway-staging.yourcompany.com

# Allow any host (use with caution)
export FLINTAI_ALLOWED_GATEWAY_HOSTS=*
```

Loopback hosts are always allowed regardless of this setting.

## API keys

### Flint AI API key

Create and manage API keys in [Flint AI Platform](https://app.flintai.dev): navigate to **Settings**, then select **API Keys**.

<Warning>
  Copy your API key immediately when created — it is only shown once.
</Warning>

Pass the key directly or set the `FLINTAI_API_KEY` environment variable:

```python theme={null}
import flintai

# Pass directly
client = flintai.wrap(client, api_key="your-flintai-api-key", gateway_url="https://app.flintai.dev")

# Or use environment variable
# export FLINTAI_API_KEY=your-flintai-api-key
client = flintai.wrap(client, gateway_url="https://app.flintai.dev")
```

### LLM provider API key

By default, the gateway supplies its own upstream credentials — you don't need to forward your provider key. If you need to use your own provider credentials, you have two options:

* **`llm_api_key`** — Explicitly pass the key. Required for Google GenAI if you want to forward your key (since its client doesn't expose `api_key` as an attribute). Omit to let the proxy use its own upstream credentials.
* **`forward_llm_key=True`** — Auto-extract the key from `client.api_key` and forward it (`wrap()` only)

```python theme={null}
# Explicit key (required for Google GenAI)
client = flintai.wrap(client, llm_api_key="your-gemini-api-key", ...)

# Auto-extract from client (OpenAI, Anthropic)
client = flintai.wrap(client, forward_llm_key=True, ...)
```

## Policy ID

A policy ID tells the gateway which guardrails policy to enforce. Policies apply input/output detectors that can block, redact, or alert on unsafe content.

```python theme={null}
client = flintai.wrap(
    client,
    gateway_url="https://app.flintai.dev",
    api_key="your-flintai-api-key",
    policy_id="your-policy-id",
)
```

You can also set this via the `FLINTAI_POLICY_ID` environment variable.

## Fail-closed behavior

The SDK defaults to `require_guardrails=True`. If guardrails configuration is missing or can't be applied — for example, missing credentials or an unrecognized client type — the SDK raises `FlintAIGuardrailsError` instead of sending traffic unguarded.

To allow operation without guardrails (for example, in local development), pass `require_guardrails=False`:

```python theme={null}
client = flintai.wrap(client, require_guardrails=False)
```

<Note>
  With `require_guardrails=False`, the SDK logs a warning when guardrails are not configured but still wraps the client and allows it to make calls directly to the provider.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Usage" icon="code" href="/flintai/platform/python-sdk/usage">
    Wrapping patterns, advanced usage, and best practices
  </Card>

  <Card title="Integrations" icon="plug" href="/flintai/platform/python-sdk/integrations">
    Provider-specific setup for OpenAI, Anthropic, Google GenAI, LangChain, and ADK
  </Card>
</CardGroup>