Gateway Quickstart

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:

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:

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:

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 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:

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:

{
  "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 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 for capture modes and Gateway troubleshooting 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#