# Quickstart Guide

Configure the Barndoor LLM Gateway, connect your tools (Cursor, Claude Code, Codex, the OpenAI/Anthropic SDKs), send requests, and troubleshoot.

## Quickstart

If your admin has already configured a provider and at least one model, you can be sending requests in two minutes.

### Steps

1. **Get your API key**: Open **Settings → My Models** in the Barndoor portal and click **Create Key**. Copy the `bd-…` token immediately — you won't be able to see it again.

2. **Find your endpoint**: On the same page, the **LLM Gateway Endpoint** card shows your base URL — it looks like `https://app.barndoor.ai/api/llm-gateway/v1`.

3. **Send a request**:
   
   ```bash
   curl https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \
     -H "Authorization: Bearer bd-…" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "gpt-4o-mini",
       "messages": [{"role": "user", "content": "Say hello"}]
     }'
   ```

Use a `model` name from the **Available Models** list — either a plain alias (`gpt-4o-mini`) or a provider-qualified name (`openai/gpt-4o-mini`).

The rest of this guide expands on each piece — admin setup, client integrations, advanced features, and troubleshooting.

## Admin: Configure the Gateway

All admin configuration happens in **LLM Management** in the Barndoor portal — a single hub whose left-hand nav groups every piece of the gateway.

| Group           | Section                                        | What it configures                                                                                                                                            |
| --------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connections** | **Credentials**                                | The actual upstream credentials (API key, AWS role, Vertex service account, etc.).                                                                            |
| **Connections** | **Providers**                                  | A named upstream that references one set of credentials and a model family.                                                                                   |
| **Models**      | **Models**                                     | The catalog of upstream models exposed via this provider.                                                                                                     |
| **Models**      | **Model Pricing**                              | Per-million-token input/output costs used for usage and budget reporting.                                                                                     |
| **Models**      | **Model Routes**                               | The client-facing model name (for example `gpt-4o-mini`) and the ordered list of providers / upstream models it resolves to.                                  |
| **Keys**        | **API Keys**                                   | `bd-…` keys issued on a user's behalf — assigned to a user, a group, or neither (developers mint their own under **Settings → My Models**).                   |
| **Controls**    | **Budgets**, **Rate Limits**, **Model Access** | Governance policies — token/spending budgets, RPM/TPM throttles, and model allow/denylists. Covered in [Configuring LLM Controls](/how-tos/use-llm-controls). |

| Step                                           | Description                                                                                                                                                       |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add Provider Credentials                       | Most credentials live in **LLM Management → Credentials**, where you save reusable secrets that one or more providers can share.                              |
| Create a Provider                              | From the **Providers** tab, click **Add Provider** to open the **Add a Provider** card grid:                                                                 |
| Enable Models                                 | Open the **Models** tab and toggle on every upstream model your org should be able to call (for example `gpt-4o-mini`, `claude-sonnet-5`, `text-embedding-3-large`).            |
| Configure Model Pricing (optional)            | Barndoor already costs every request against its **managed default catalog** of market-rate prices, so the cost-aware features below work without any setup.   |
| Define Model Routes                           | This is the most important step. A **Model Route** maps a *client-facing* model name to one or more (provider, upstream model) targets in priority order. 
| Add Governance (optional)                     | Once routes are live, layer on usage policies — token budgets, rate limits, and model access. All of these live under the **Controls** group of **LLM Management**.  |
| Create an Org API Key (optional)             | If you need a service-account-style key not tied to a single user, use **LLM Management → API Keys → Create Key**.                                           |

## User: Get Your Endpoint and API Key

If you're a developer who just wants to call the gateway from your app or editor:

### Steps

1. **Open My Models**: In the Barndoor portal, navigate to **Settings → My Models**. The top of the page shows your **LLM Gateway Endpoint** — copy this base URL.

2. **Create an API key**: Under **My API Keys**, click **Create Key**, give it a descriptive name (for example `Cursor on laptop`), and click **Create**. The dialog shows a `bd-…` token — **copy it now**.

3. **Pick a model**: The **Available Models** section lists every model your admin has enabled and that your access policies allow.

* **Model routes** (`gpt-4o-mini`, `claude-sonnet-5`, …) — use the plain name in the `model` field of your request.
   * **Standalone models** — use the `provider/model` form (for example `openai/gpt-4o-mini`).

## Sending Requests

The gateway speaks two API dialects on the same port:

| Endpoint                         | Use it from                                                                                                                |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/chat/completions`      | OpenAI SDKs, LangChain, LlamaIndex, most chatbots                                                                          |
| `POST /v1/messages`              | Anthropic Messages clients (Claude Code, Anthropic SDK)                                                                    |

### List Available Models

To enumerate what a key can call instead of hardcoding model names:

```bash
curl https://app.barndoor.ai/api/llm-gateway/v1/models \
  -H "Authorization: Bearer bd-…"
```

### Non-Streaming Chat Completion

```bash
curl https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \
  -H "Authorization: Bearer bd-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a terse assistant."},
      {"role": "user", "content": "Summarize Barndoor in one sentence."}
    ]
  }'
```

## Example of Streaming Chat Completion

```bash
curl -N https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \
  -H "Authorization: Bearer bd-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a haiku about gateways."}]
  }'
```

## Troubleshooting
### Common Errors

1. **401 invalid API key** / **missing or invalid Authorization header**: Confirm the header is `Authorization: Bearer bd-…` (with a space after `Bearer`).
2. **404 model not found** / **no route configured for alias**: Call `GET /v1/models` to see exactly which aliases your key can use.
3. **403 Forbidden** (model access denied): Check **LLM Management → Model Access** for the policy that applies to your role/group.

### Frequently Asked Questions

* **Do I have to use OpenAI's SDK?** No. Any HTTP client that can speak OpenAI's request/response shape — or Anthropic's Messages shape on `/v1/messages` — will work. SDKs are a convenience, not a requirement.
* **Where do upstream API keys live?** In Barndoor's encrypted secret store. The gateway loads them at request time; they're never exposed to the browser or returned via any API.