# Gateway Quickstart

By the end of this guide, one model request will have passed through Provon AI Gateway and the same
request will be visible as trace evidence in the Workbench.

## Prerequisites

- Node.js 22 or newer and pnpm 10 for a local deployment
- An upstream provider API key for the BYOK path
- `curl`

## 1. Start Provon

From the repository:

```bash
pnpm install
pnpm dev
```

Open `http://127.0.0.1:3000` and create an account, organization, and project when prompted.

If Provon is already deployed, use its public origin instead. The remaining examples use the local
origin.

## 2. Create The Application Key

In the project:

1. Open **API keys**.
2. Select **Create API key**.
3. Keep `gateway:invoke` enabled. Keep `workspace:read` too if this key will call Gateway discovery
   endpoints.
4. Copy the secret when shown; it cannot be retrieved later.

Export the local example values:

```bash
export PROVON_BASE_URL="http://127.0.0.1:3000"
export PROVON_API_KEY="your_project_api_key"
```

This key authenticates the application to Provon. It is not an OpenAI, Anthropic, or other upstream
provider key.

## 3. Connect A Model Target

For the first request, use one explicit target:

| Target access                   | Setup                                                             |
| ------------------------------- | ----------------------------------------------------------------- |
| Bring your own provider key     | Create a Provider Key under **Providers**                         |
| Provon Cloud managed model      | Choose a model and ensure the organization has AI Gateway credits |
| Local model on the Node runtime | Install and start the model, then use `self/<model>`              |

The BYOK path is available in both local and hosted deployments.

In the Workbench:

1. Open **Providers** and select the upstream provider.
2. Under **Provider keys**, select **Add key**.
3. Store the upstream provider API key.
4. Leave **Models** set to **All**, or add an explicit model mapping.
5. Keep the Provider Key enabled.
6. Set **Request traces** to **All** while validating the integration.

With an explicit mapping, **AI Gateway model** is the model ID sent by the application and
**Upstream model** is the ID sent to the provider. Endpoint and feature declarations restrict when
that mapping is eligible.

The application never receives the upstream credential. See
[Model providers](./model-providers.md) for target access, Provider Keys, and model mappings.

## 4. Send The First Request

Use a provider-qualified model for the first request so routing intent is unambiguous:

```bash
curl -i "$PROVON_BASE_URL/gateway/v1/chat/completions" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-otel-gen-ai-conversation-id: quickstart-conversation-1" \
  -H "x-otel-gen-ai-agent-id: quickstart-agent" \
  -H "x-otel-gen-ai-agent-name: Quickstart Agent" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      {
        "role": "user",
        "content": "Explain why an agent repair needs production evidence."
      }
    ]
  }'
```

Replace `openai/gpt-5-mini` with a model available through the Provider Key you configured.

For a local model, use its route instead:

```json
{
  "model": "self/<installed-model-id>"
}
```

Do not use a plain model name or `provon/auto` for this first check. Those forms add routing policy
to a transport test.

## 5. Verify The Response

A successful model path returns:

- an HTTP `2xx` response in the provider-compatible shape;
- an `x-provon-request-id` response header;
- model output in the response body.

Record `x-provon-request-id`. The response proves that inference worked; it does not prove that the
evidence path worked.

If this step fails, start with [Gateway troubleshooting](./gateway-troubleshooting.md) before
changing routing or guardrail settings.

## 6. Verify The Trace

Open **Traces** in the same project and locate the request by its timestamp or
`x-provon-request-id`.

Verify:

- the root operation is `POST /v1/chat/completions`;
- the selected provider and model are correct;
- an upstream attempt appears as a child span;
- latency, status, token usage, and cost appear when available;
- the conversation is `quickstart-conversation-1`;
- the agent is `quickstart-agent`.

If the response succeeded but no trace appears, confirm that **Providers** -> **Request traces** is
set to **All**. Trace persistence may be asynchronous in some deployments. See
[Gateway evidence](./gateway-observability.md) for capture modes and
[Gateway troubleshooting](./gateway-troubleshooting.md#the-model-call-succeeds-but-no-trace-appears)
for the verification sequence.

## You Are Ready

The Gateway path is working when both checks pass:

1. The client receives the expected provider-compatible response and `x-provon-request-id`.
2. The same request appears in **Traces** with its provider attempt and conversation context.

Keep the project key and upstream provider key separate. Use stable, non-secret identifiers for
conversation, user, session, and agent context because these values may be retained with telemetry.

## Continue By Goal

| Goal                                    | Next page                                       |
| --------------------------------------- | ----------------------------------------------- |
| Move an existing production application | [Migration guide](./gateway-migration.md)       |
| Configure a client or framework         | [SDK integrations](./gateway-integrations.md)   |
| Connect more targets or map model IDs   | [Model providers](./model-providers.md)         |
| Add policies, retry, or fallback        | [Routing and reliability](./gateway-routing.md) |
| Add limits and guardrails               | [Gateway governance](./gateway-governance.md)   |
| Choose what evidence to retain          | [Gateway evidence](./gateway-observability.md)  |
| Prepare a production rollout            | [Production guide](./gateway-production.md)     |
| Inspect the complete HTTP contract      | [Gateway API](./gateway-api.md)                 |