Quickstart

Sign in to the console

Go to app.corevalue.dev and sign in with your email and password.

The first time you sign in you are asked to name your organisation. Everything you set up — keys, budgets, requests — belongs to that organisation, and you can invite teammates to it later.

Add your provider key

CoreValue needs a key for each provider you want to call. It keeps the key and uses it on your behalf; your applications never see it.

1. In the top bar, click Gateway, then the Provider keys tab.
2. Find your provider — type in Search providers... to filter the list.
3. Paste your key into the provider's API key field (for OpenAI, OpenAI API Key, starting sk-).
4. Leave Enable for AI Gateway (BYOK) ticked — BYOK means "bring your own key": CoreValue calls the provider with your key, and the provider bills you — then click Save.

The card now reads 1 key configured. Repeat for any other provider you use.

Create a CoreValue API key

Your applications send a CoreValue API key with each request, instead of your provider key. That way the provider key stays inside CoreValue, and every request is tied to a key you can see and limit. (What's the difference?)

1. In the top bar, click Governance, then the Keys tab.
2. Click Generate API key.
3. Enter a Key Name that says where the key will be used — for example checkout-service — and pick a Team if you use teams.
4. Click Create Key.

Copy the key now. It starts with sk-cova-, and you will not be able to see it again after you close the dialog.

Store it where your application reads secrets, for example:

export COVA_API_KEY="sk-cova-..."

Send your first request

Point your OpenAI client at the gateway and use your CoreValue key. Nothing else in your code changes.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.corevalue.dev/v1",
    api_key=os.environ["COVA_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.corevalue.dev/v1",
  apiKey: process.env.COVA_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(response.choices[0].message.content);

curl -i https://gateway.corevalue.dev/v1/chat/completions \
  -H "Authorization: Bearer $COVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

The response is exactly what OpenAI returns. CoreValue adds a few headers of its own (curl -i shows them):

For a streamed response the cost arrives in the stream's last event instead of a header — see Streaming.

See it in the console

In the top bar, click Requests. Your request is at the top of the list, with its status, cost, model, provider, tokens and latency.

Click the row to open it. The panel shows the model, cost, latency, tokens and any properties you sent — and the request and response bodies when your organisation stores them (see Body retention).

Say which customer each request is for

Send the Cova-Customer-Id header with the ID you already use for that customer — an account ID, a tenant slug, anything stable. This is what turns your AI bill into a cost per customer.

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
    extra_headers={"Cova-Customer-Id": "acme-corp"},
)

const response = await client.chat.completions.create(
  {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Say hello in one sentence." }],
  },
  { headers: { "Cova-Customer-Id": "acme-corp" } },
);

curl https://gateway.corevalue.dev/v1/chat/completions \
  -H "Authorization: Bearer $COVA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Cova-Customer-Id: acme-corp" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

Go to Budgets & Limits → Customers. acme-corp is listed with what it has cost you this month.

Set a first customer budget

On Budgets & Limits → Customers, click Add limit, choose the Customer, and click Continue. Enter the Monthly budget (USD), set At the budget to Refuse the request or Downgrade the model, and click Save.

The budget is checked before the model is called. Once the customer's spend reaches it, their requests get HTTP 429 (or move to a cheaper model from your downgrade mappings), and every other customer is unaffected. Per-customer budgets covers the error your application sees and how to show each customer's margin.