Attribute cost per workspace for chargeback

The problem

You run a multi-tenant SaaS where each customer makes LLM calls through your platform. Finance needs to know exactly how much each customer spent last month on each model from each provider, with enough detail to either (a) bill the customer back for their usage or (b) allocate cost internally to their cost center. A raw OpenAI invoice can't tell you any of this — it's one lump sum for all of your traffic.

The approach

DVARA issues an API key per workspace, stamps every request with the workspace's identity, and tracks cost at the request level (workspace + API key + model + provider + tokens + USD). A scheduled chargeback job rolls this up into a monthly report per workspace, downloadable as PDF or CSV and ready to attach to the invoice.

Prerequisites

• A running DVARA instance (Quickstart)
• An owner or billing-admin account on DVARA Flightdeck
• Provider credentials configured (environment, per-workspace BYOK, or vault — see Credentials & BYOK)
• Model pricing entries for each (provider, model) pair you use — DVARA ships defaults for the major providers, but verify your pricing is current under Cost Management → Pricing

The steps

1. Create one workspace per customer

For each customer, create a workspace. It carries the customer's name, status, region and optional metadata.

Create one from the Console's Workspaces page (/workspaces → New workspace). To onboard many customers at once, add them to the Console's GitOps export document and import it — the import reconciles by id, so re-running it is safe.

2. Issue an API key per workspace

Each customer-facing application gets its own API key, scoped to one workspace. The gateway reads the key on every request, hashes it, looks up the workspace, and stamps the request — which is what makes the attribution automatic.

Open the workspace and use API keys → New key. The plaintext gw_... value is shown once, at creation: only a SHA-256 hash is stored, so a lost key is replaced rather than recovered.

3. Route application traffic through DVARA

The customer's applications keep their existing code and SDKs — they just point at DVARA and use the issued key. See Add DVARA to an existing OpenAI-SDK app for the client-side change. On every request, DVARA:

1. Hashes the Authorization: Bearer <key> value
2. Looks up the workspace (sub-millisecond — the gateway caches the key-to-workspace mapping)
3. Dispatches the request and records the outcome under that workspace

4. Let cost records accumulate

Every governed request writes a cost record stamped with the workspace, model and provider.

Verify the money is landing where you expect on the Console's Costs page (/costs): filter by workspace and date range, and the summary cards, the by-provider donut and the by-model bar chart show what the gateway attributed.

5. Generate a monthly chargeback report

At month-end, generate a report per workspace on the Console's Chargeback page (/chargeback): pick the workspace and the period, then generate. Each report in the list carries PDF and CSV downloads — the PDF for attaching to an invoice, the CSV for loading into a billing system.

Extending the attribution

Attribute by cost center, project, or product line, not just by workspace. If a single workspace runs multiple products that need separate cost allocation internally, stamp requests with tags via the metadata.tags map. The OpenAI Python SDK passes the field through with extra_body:

client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_body={"metadata": {"tags": {"Project": "customer-support-bot"}}},
)

Tags must be string-to-string. DVARA records them on every cost record from this request and indexes them for tag-aware queries.

Then aggregate by tag on the Console's Costs page: enter the tag key — Project — in the Group by tag filter, and the page groups spend by that key's values for the selected workspace and period.

The filter is opt-in by key: tags are workspace-defined, so there is no default and no panel until you supply one.

See Cost Management → Tags for the full tag cascade.

Enforce budgets, don't just measure. Attribution tells you what was spent after the fact; a budget cap stops the bleeding before it hits the invoice. Create a per-workspace monthly hard cap:

Create it on the Console's Budgets page (/budgets): scope it to the workspace, choose the period and the limit, and set a soft-limit percentage to get warned before the hard cap refuses requests with 402 BUDGET_CAP_HARD.

Field names are snake_case (workspace_id, limit_usd, soft_limit_pct); period values are the uppercase enum (DAILY / WEEKLY / MONTHLY).

When the workspace hits 80%, DVARA fires a soft-limit webhook and audit event. At 100%, requests are rejected with BUDGET_CAP_HARD (HTTP 402). See Cost Management → Budget Caps.

Verification

Check	What you should see
Console Costs page, filtered to the workspace	Rows with matching workspace, model, provider, and non-zero USD cost
The same page's summary cards, with a date range	Aggregate totals for the period that sum to the expected USD
Chargeback PDF	Workspace name, period, line items per model/provider, total USD
Audit events	GATEWAY_RESPONSE events carrying the workspace's UUID

If costs look zero despite traffic flowing, check that pricing entries exist for the (provider, model) pairs being called — a missing pricing row records tokens but zero USD. Add them on the Console's Pricing page.

Next steps

• Multi-Tenancy — how workspace isolation is enforced end-to-end (API keys, budgets, policies, audit)
• Cost Management (Flightdeck) — dashboard, forecasts, anomaly alerts, tags, budget caps, chargeback
• SIEM & Webhooks — route soft-limit alerts to Slack or PagerDuty instead of just emitting audit events