# Attribution headers

Attribution is the product. A proxied call with no attribution is a recorded
dollar with no owner, which is the problem Spendline exists to solve.

## The contract

| Header | Required | Cardinality | Value |
|---|---|---|---|
| `x-spendline-key` | Always | Per process | The Spendline API key, from `SPENDLINE_API_KEY`. |
| `x-agent-id` | Yes, unless enforcement is off | **Per agent** | Stable name of the bot/feature: `support-bot`, `doc-summarizer`. |
| `x-customer-id` | Yes, unless enforcement is off | **Per request** | The end customer this call is billable to. |
| `x-spendline-tags` | Yes, unless enforcement is off | Per call site | JSON object carrying a cost-centre key. |
| `x-workflow-id` | Optional | Per run | Groups a multi-step run. |
| `x-step-name` | Optional | Per step | Labels a step inside a workflow. |
| `x-source-route` | Optional | Per call site | The app route that triggered the call. |

## x-customer-id must vary per request

This is the mistake that quietly ruins the data. If you set `x-customer-id` once
in `default_headers`, every call is attributed to the same customer and
per-customer cost is meaningless.

Thread the customer from request context:

```python
# WRONG: every call attributed to one customer
client = OpenAI(default_headers={"x-customer-id": "cus_123"})

# RIGHT: per request
client.chat.completions.create(..., extra_headers={"x-customer-id": request.customer_id})
```

If the call site genuinely has no customer concept (an internal batch job, a
cron task), pick a stable synthetic id such as `internal:nightly-reindex` and say
so in your report. Do not omit the header and do not invent a random value per
call, a random id makes every request look like a new customer.

## x-spendline-tags

A JSON object that **must** include one of these keys:

- `cost_center`
- `costCenter`
- `department`
- `team`

```
x-spendline-tags: {"team":"support","env":"prod","tier":"enterprise"}
```

Extra keys are kept and available for reporting. A tags header without a
cost-centre key fails the attribution check.

## x-agent-id

One stable value per agent, bot or feature, not per request, and not per
customer. This is the dimension hierarchical budgets scope to, so it must be
stable enough to budget against.

## Workflow attribution

For a multi-step agent run, set `x-workflow-id` once per run and `x-step-name`
per step:

```python
workflow_id = f"run_{uuid4()}"

for step in ("retrieve", "draft", "review"):
    client.chat.completions.create(..., extra_headers={
        "x-customer-id": customer_id,
        "x-workflow-id": workflow_id,
        "x-step-name": step,
    })
```

This makes the whole run costable as a unit, which is what "what does one
support ticket cost us" actually requires.

## Enforcement

Attribution enforcement is on by default for new accounts. A call missing a
required field is rejected before it reaches the provider:

```
HTTP 400
{"error_type":"missing_required_attribution","missing_fields":["customer_id"]}
```

An owner or admin can turn enforcement off in Dashboard → Governance. The call
is then forwarded and recorded. With no customer it shows as `(unassigned)` on
the Customers page and `(none)` in the dashboard's customer and agent breakdown.

Send the headers from day one. Do not turn enforcement off to get a call through:
that is how call sites end up never instrumented.

## Body fallback

`customer_id`, `agent_id`, `workflow_id` and `step_name` are also read from a
`metadata` object or the top level of the request body when the header is
absent. Headers are preferred, they survive SDK body validation, which may
strip unknown fields.

## Timestamps are server-controlled

You cannot set the timestamp that decides which month a call lands in. Spendline
stamps it server-side. A client-supplied `created_at` is ignored for spend
attribution by design.
