Menu
Meter firstCheck installed SDK transportGuard contract: October 27, 2026

UsageTap Meter implementation contract

This page is the canonical starting context for a coding agent. The first integration is Meter only. Preserve the application's provider, model, request shape, streaming behavior, and error behavior. Gateway, Compress, sampling, deployments, and Stripe synchronization require a separate explicit request.

Use an opaque customer ID for Meter. The organization privacy policy controls optional names and emails, hosted prompt processing, and sample retention. Organization admins can change it in Configure. The Prompt sampling policy permits configured prompt capture while omitting separate sample outputs and raw provider errors before storage. Gateway batches, sample analysis, benchmarks and quality reviews require Batch compression & quality reviews. Existing saved retention policies keep their access. Meter responses preserve their existing fields and return contact details already saved on the customer profile. Optional customer and end-user contact fields are stored on usage records when the organization has no saved privacy level or permits customer details. The policy for metering with customer IDs only omits those fields. Writes with contact fields check policy; identity-free writes skip that lookup. Customer names and emails can also populate a new profile. Use the customer API or dashboard to update existing profiles, and stable customerUserId for attribution.

Production and dev/test traffic

Set server USAGETAP_ENVIRONMENT=production or test; SDK and observer read it automatically. A configured client can use defaultEnvironment. Direct HTTP sends X-UsageTap-Environment on every UsageTap request, including customer creation, reads, updates, call_begin, call_end, and custom_meter. Send it only to UsageTap, never to the underlying provider.

Only those two exact values are valid. For Automatic customers, omission stays unlabelled; do not infer from NODE_ENV, customer IDs, tags, metadata, or sampling options. Preserve the label across lifecycle requests, workers and idempotent retries. Automatic calls reject conflicting explicit labels; pinned calls and delivery retries retain their recorded group. Verify outgoing headers with a supporting SDK release.

Admins can pin a customer panel's Traffic group to Production or Dev / test for new usage, overriding request labels. Automatic restores request labels. This groups the customer immediately and leaves historical usage, active calls and retries unchanged. Automatic customers can have both labels. Dashboard, Customers, Usage and Live have environment filters; Usage filters retained event quantities, costs, forecast training and exports. Account balances and customer signals remain shared. Page-level Environment filters group unlabelled usage with Production and keeps Dev/Test separate; API header filters still match exact recorded labels. Usage Forecast defaults to All traffic, offers Production, and does not offer Dev/Test-only forecasting. Guard behavioral checks always compare Production + unlabelled usage with matching retained history. Dev/Test is excluded from those checks. A separate environment-mix check uses all recorded traffic to detect substantial Dev/Test growth and share increases; it follows existing Guard notification opt-ins. There is no Dev/Test inclusion setting. Viewing filters do not change detection, and eligible retained history is reused without restarting learning. Test labels do not switch Stripe mode, disable billing or create separate allowances.

Complete environment contract

Connect usage to Guard monitoring

Guard is part of Meter. Keep existing providers and instrument completed LLM calls with customer and feature attribution, or report completed API / Agentic Calls and custom-meter events. Usable token and cost fields enable the corresponding LLM signals.

  1. Use the Meter integration below for model calls, or the API / Agentic Calls contract for call-based usage.
  2. Guard monitors reported application behavior automatically for all organizations. Organization administrators can inspect evidence; offline detector preflight remains restricted to UsageTap platform administrators. Only R1 collection runs; R0 evaluation, historical initialization, configured Guard rules and incident handling are retired. Cache reuse, output/input, output size and API/custom-meter feature mix have population comparison adapters. Genuine calls/reports remain the sampling units; quantities do not invent independent calls. Applications automatically compare trailing two-hour populations using each detector's supported calendar history. The organization timezone is used, with an explicit UTC default. Same-weekday, weekday/weekend and daily references activate according to eligible support; sparse checks use labelled recent compatible history. Customers do not configure comparison policies. Dense calendar periods are reproducibly sampled without replacement, up to 256 observations per historical period and 4,096 current observations. Numeric comparisons use 512 observations per population within those caps, dividing the reference budget across periods to bound exact-test runtime. Periods below their allocated quota retain every observation. Categorical recent-history fallback can use the 4,096-observation reference budget. Full recorded counts, missingness and sampling support remain separate; samples can miss rare changes. Provisional sampling assumptions and a per-assessment statistical budget do not establish a daily or lifetime false-positive rate. No policy or insufficient/descriptive evidence is not health. Recorded cost-per-call distributions, reported completion reasons and denominator-based token/user/task coverage have comparison adapters. Missing historical measurements stay unknown. Token coverage and end-user attribution coverage measure eligible completed LLM calls; API/custom attribution coverage measures genuine reports. Historical LLM samples without the user-coverage measurement stay unknown; reporting an ID does not establish authorization or enable individual-user behavioral monitoring. Errors compares the recorded response-code distribution across eligible finalized successes, failures and timeouts, including shifts among successful codes; missing codes stay unknown. API call rate uses reported AGENTIC_API quantities over five-minute exposure with an explicit daily UTC reference. Batches do not reveal individual call times; missing/delayed windows remain unknown. Detector preflight replays saved offline cases. Application comparisons are enabled across organizations; customer detail is investigated on demand. Change and recovery notifications use the existing UsageTap Guard email/Slack opt-ins and shared destinations; neither channel is enabled automatically. Guard Settings provides separate Alert and Notification dropdowns per detector, each with Off, All, Major. All includes minor and major changes. Development is the default preset for organizations without saved detector settings: major behavioral alerts and notifications, with Environment mix Off. Production uses Alert: All and Notification: Major for every connected detector. Individual overrides show Custom; presets populate the existing controls and apply on Save. Existing saved preferences keep their behavior. Alert: Major keeps smaller or unclassified changes neutral in evidence/history, without warning icons, active findings or amber timeline emphasis. Alert: Off removes visual alerts while allowing opted-in notifications; both Off skips evaluation. Both levels are saved together in the existing detector preference. Notification: Off stops pending delivery; channel opt-in is still required. Meter recording and saved findings are preserved. The Production preset shows all supported changes; notifications default to major changes, with an optional all-supported-changes setting per detector. Major means detector-specific change magnitude, not proven harm or confidence. A smaller change can notify when it first becomes major. Repeated changed windows do not repeat alerts. Recovery requires a completed no-change comparison and is sent only on a channel that received the change alert; quiet, unknown and unavailable evidence never establish recovery. There is no incident case-management workflow or automatic blocking. Task lookup and configured Meter enforcement remain separate.
  3. Use Detector preflight to replay the connected population adapters. Planned icons retain explicit coverage gaps. Offline preflight sends no notifications; live change/recovery delivery requires explicit organization opt-in.

Send customerId, stable feature, and optional customerUserId, taskId, and stable taskType as top-level fields on call starts and meter reports. Share one task ID across an operation's LLM calls, tools, and workers, with separate per-event idempotency keys. Both task strings are trimmed, case-sensitive, 1–128 characters without control characters. runId is local circuit-breaker state, not remote task attribution.

API/custom-meter task-type mix compares reported consumption shares weighted by actual consumed calls/units, with update shares supporting batching investigation. Unspecified taskType stays visible as measurement context. This does not count distinct/completed tasks or cost per task; taskId remains customer-scoped lookup identity. Current application monitoring adds no independent customer/end-user or LLM task-type collection.

HTTP metadata.method/endpoint and MCP metadata.serverName/toolName label operations in Live View; arbitrary metadata and tags do not add detector dimensions. Report actual consumed units, preserve cache/token telemetry, and keep batching consistent. Older wrapper builds can accept task fields in types but omit them from requests; verify transport or use withUsage/beginCall until a fixed build is installed.

Read GET /usage/monitoring?customerId=...&taskId=... or MCP get_task_usage with usage:read. Follow all pages: totals are per-page and completion is not reported. Keep provider cost separate from meter charges and inspect missing-cost/open-call counts. Live Guard has opt-in change/recovery delivery and no incident case-management workflow. Automatic feature mix needs no manual feature dictionary.

For opt-in numerical investigation, MCP get_usage_anomalies with opt-in evidence (usage:read) accepts the user's question and finalized recorded-call periods. It returns local-calendar count references and expected ranges, explicit success/trial comparisons or sparse replay. Inspect recent evidence, uncertainty, support and completeness; use list_calls for source rows. Independent-trial inference requires a justified explicit assumption. Reuse the source fingerprint when paging. This read does not send alerts, change scheduled Guard behavior or add an SDK method. See investigation semantics.

For daily operational briefs, MCP get_guard_summary with usage:read reports application behavioral findings and recorded change/recovery notifications separately from customer signals and ordinary usage/cost anomalies. It defaults to the last 24 hours; explicit inclusive startTime and exclusive endTime select a prior day converted to UTC (up to seven days within 56-day retention). Follow nextToken until null, merging finding groups by ID; overlapping comparisons are not incidents. Keep period findings/support counts separate from current readiness. Missing, quiet, stale, pending, disabled or unsupported evidence is not an all clear. Channel delivery is sent, skipped or unknown_or_pending; reading does not send alerts or enable opt-ins. There is no SDK summary method.

Legacy scope reads without a task ID return an empty scope page with retired: "r0". They do not initialize history. Use MCP get_guard_summary for application reports or the signed-in Guard UI with active organization-admin membership for interactive evidence.

Existing Gateway integrations send top-level taskId and taskType on Chat Completions or Responses requests, including streams, or inside each native batch item's body. Gateway validates and forwards these fields to metering and strips them before provider dispatch. Do not add a second LLM metering lifecycle.

Complete Guard field guide, task examples, and verification

One-prompt Meter Tap setup

Implement Meter from this contract

Paste the prompt into a coding agent with repository access. It should inspect the application, implement the smallest safe integration, test it, and leave an exact setup handoff.

You can add the code first. Before the test call, set USAGETAP_API_KEY on your server. The prompt never contains your key. Set up the key before testing.

Open the canonical agent reference
Paste into your coding agent
Implement UsageTap Meter in this repository.

Meter Tap connects direct-provider calls to UsageTap Meter. These instructions apply to the direct-provider call sites selected for this task. The setup selector chooses examples, not an application-wide routing policy. Direct-provider Meter reporting and Gateway can coexist in one app and change over time. Preserve existing Gateway call sites and their built-in metering; do not add a second wrapper around them or migrate unrelated call sites.

Implement the code first with server environment-variable references. Credential prerequisite before the test call: before running a metered call, have the user create an integration key at https://usagetap.com/embed-api?features=meter#meter-key-setup, or reuse an active key with usage:write that they already saved. New inline integration keys include usage:write, gateway:invoke, and compression:invoke and provide server environment configuration. These permissions do not enable Gateway or compression or change this task. Hosted compression is easier through Gateway with compress: true; direct-provider calls need an SDK wrapper or a separate compression step. Add compression only when requested. Existing keys need only usage:write for Meter Tap; do not broaden them automatically. The user creates and saves the key just before live verification, and sets USAGETAP_API_KEY in the server runtime; retain their existing provider credentials. Never ask them to paste a key into this prompt or chat. If the key is not configured, finish the code safely and make key setup the explicit next action before live verification.

For opt-in numerical investigation, use MCP get_usage_anomalies with opt-in evidence (usage:read) with the user's question and finalized recorded-LLM-call periods. It returns local-calendar count references/expected ranges or explicit success/trial evidence and sparse replay. Inspect recent comparisons, uncertainty, support and completeness; use list_calls for supporting rows. Independent-trial inference requires an explicit justified assumption. Reuse the source fingerprint when paging. This read does not send alerts or change scheduled Guard behavior; there is no SDK/observer method. See https://usagetap.com/docs/usage-investigation.

For requested daily operational briefs, use MCP get_guard_summary with usage:read alongside usage totals and get_customer_signals. Guard is application behavioral monitoring, separate from customer signals and ordinary usage/cost anomalies. It defaults to the last 24 hours; explicit inclusive startTime and exclusive endTime select a prior day converted to UTC (up to seven days within 56-day retention). Follow nextToken until null and merge finding groups by id; overlapping comparisons are not independent incidents. Keep period findings and saved comparison support counts separate from current readiness. Missing, quiet, stale, pending, disabled or insufficient evidence is not an all clear. Notification email/Slack delivery is sent, skipped or unknown_or_pending; reading does not send alerts or enable opt-ins. There is no SDK Guard-summary method.

POST /call, /call_begin, /call_end and /custom_meter use fast index-based key authentication. Revoked/replaced keys and previous permissions may remain usable there until index propagation, with no promised maximum delay. Other durable-key requests recheck the current primary record and fail closed on verification failure. New/replacement key discovery, issued-session lifetimes and the internal verifier's permitted 30-second positive cache retain their existing behavior.

Read https://usagetap.com/llmreference first and treat it as the canonical contract. The initial goal is Meter only. Do not add UsageTap Gateway, UsageTap Compress, prompt compression, provider migration, model changes, or Stripe synchronization unless I explicitly ask.

Use an opaque customerId. Send names and emails only when the organization policy permits customer details. Gateway and runtime Compress require Gateway & realtime compression or higher. Prompt capture requires Prompt sampling or higher plus the existing sampling configuration. The Prompt sampling policy omits separate sample outputs and raw provider errors before storage; Gateway batches, sample analysis, benchmarks and quality reviews require Batch compression & quality reviews. Ask an organization admin to review Configure → Privacy policy if an enabled integration is blocked.

Meter responses preserve their existing fields and can include names and emails already saved on the customer profile. Supplied optional customer and end-user contact fields are stored on usage records when the organization has no saved privacy level or permits customer details. The policy for metering with customer IDs only omits those fields. Writes with contact fields check policy; identity-free writes skip that lookup. Customer names and emails can also populate a new profile. Update existing profiles through the customer API or dashboard. Use stable customerUserId for attribution.

If this application already uses UsageTap Gateway, extend its existing requests instead of adding a second LLM metering lifecycle. Read https://usagetap.com/docs/LLM_GATEWAY. Send top-level taskId and taskType on Chat Completions/Responses requests, including streams, or in each native batch item's body. Gateway validates these fields, forwards them to call_begin, and removes them before provider dispatch.

Start by wrapping the application's existing LLM calls. New UsageTap workspaces receive a Metering plan with unlimited calls and output tokens and no plan quota blocking. Existing workspaces retain their configured plans; do not overwrite them or bypass their enforcement. Pricing tiers, limiting, and usage widgets are optional follow-up work, not prerequisites for a new workspace's first metered call.

When the requested target is HTTP API requests or MCP tool calls, use the dedicated Agentic & API Calls meter: POST /custom_meter or incrementCustomMeter with meterSlot AGENTIC_API and a positive integer amount. Read https://usagetap.com/llmreference#agentic-api. Configure the allocation, eligible purchased credits, PAYG funding and single or graduated prices just like a custom meter. Report completed usage with a stable idempotency key; inspect data.blocked and enforce it in the application. This reporting API does not reserve credit or impose rolling rate limits. Skip the provider-specific lifecycle, model and token steps below for this target; those steps apply only to LLM usage.

Read https://usagetap.com/docs/GUARD_INTEGRATION to make recorded usage useful for Guard. Send stable customerId and feature plus optional customerUserId, taskId, and stable taskType as top-level fields on call_begin and meter reports. Propagate one operation's taskId across LLM calls, tools, and workers, with separate idempotency keys for each event. runId is SDK-local circuit-breaker state, not remote task attribution. Verify installed wrapper transport because older SDK builds may accept task fields in types but omit them. Use explicit withUsage/beginCall until a fixed build is available. For HTTP labels send sanitized metadata.method/endpoint; for MCP send metadata.toolName and optional serverName. Arbitrary metadata/tags are not additional Guard detector dimensions. API/custom-meter task-type mix compares reported consumption shares, with update shares supporting batching investigation; unspecified taskType remains measurement context. It does not count distinct/completed tasks or create taskId baselines. Report real consumed units and keep batching consistent; one report is not necessarily one consumed call. Preserve actual total input/output, cache subsets, provider/model, and known pricing/reasoning settings; omit unknown usage rather than inventing zeros.

Verify linked usage with GET /usage/monitoring?customerId=...&taskId=... or MCP get_task_usage using usage:read. No SDK task-read method exists. Follow every nextToken; totals cover each page only. Report missing-cost/open-call counts and keep LLM cost separate from commercial meter charges. Task completion and cost per completed task are not inferred. Guard monitors reported application behavior automatically for all organizations. Organization administrators can inspect evidence; offline detector preflight remains restricted to UsageTap platform administrators. Only R1 collection runs; R0 evaluation, historical initialization, configured Guard rules and incident handling are retired. Cache reuse, output/input, output size and API/custom-meter feature mix have population comparison adapters. Genuine calls/reports remain the sampling units; quantities do not invent independent calls. Applications automatically compare trailing two-hour populations using each detector's supported calendar history. The organization timezone is used, with an explicit UTC default. Same-weekday, weekday/weekend and daily references activate according to eligible support; sparse checks use labelled recent compatible history. Customers do not configure comparison policies. Dense calendar periods are reproducibly sampled without replacement, up to 256 observations per historical period and 4,096 current observations. Numeric comparisons use 512 observations per population within those caps, dividing the reference budget across periods to bound exact-test runtime. Periods below their allocated quota retain every observation. Categorical recent-history fallback can use the 4,096-observation reference budget. Full recorded counts, missingness and sampling support remain separate; samples can miss rare changes. Provisional sampling assumptions and a per-assessment statistical budget do not establish a daily or lifetime false-positive rate. No policy or insufficient/descriptive evidence is not health. Recorded cost-per-call distributions, reported completion reasons and denominator-based token/user/task coverage have comparison adapters. Missing historical measurements stay unknown. Token coverage and end-user attribution coverage measure eligible completed LLM calls; API/custom attribution coverage measures genuine reports. Historical LLM samples without the user-coverage measurement stay unknown; reporting an ID does not establish authorization or enable individual-user behavioral monitoring. Errors compares the recorded response-code distribution across eligible finalized successes, failures and timeouts, including shifts among successful codes; missing codes stay unknown. API call rate uses reported AGENTIC_API quantities over five-minute exposure with an explicit daily UTC reference. Batches do not reveal individual call times; missing/delayed windows remain unknown. Detector preflight replays saved offline cases. Application comparisons are enabled across organizations; customer detail is investigated on demand. Change and recovery notifications use the existing UsageTap Guard email/Slack opt-ins and shared destinations; neither channel is enabled automatically. Guard Settings provides separate Alert and Notification dropdowns per detector, each with Off, All, Major. All includes minor and major changes. Development is the default preset for organizations without saved detector settings: major behavioral alerts and notifications, with Environment mix Off. Production uses Alert: All and Notification: Major for every connected detector. Individual overrides show Custom; presets populate the existing controls and apply on Save. Existing saved preferences keep their behavior. Alert: Major keeps smaller or unclassified changes neutral in evidence/history, without warning icons, active findings or amber timeline emphasis. Alert: Off removes visual alerts while allowing opted-in notifications; both Off skips evaluation. Both levels are saved together in the existing detector preference. Notification: Off stops pending delivery; channel opt-in is still required. Meter recording and saved findings are preserved. The Production preset shows all supported changes; notifications default to major changes, with an optional all-supported-changes setting per detector. Major means detector-specific change magnitude, not proven harm or confidence. A smaller change can notify when it first becomes major. Repeated changed windows do not repeat alerts. Recovery requires a completed no-change comparison and is sent only on a channel that received the change alert; quiet, unknown and unavailable evidence never establish recovery. There is no incident case-management workflow or automatic blocking. Task lookup and configured Meter enforcement remain separate. Do not change plans or notification preferences unless requested.

In the application, use Meter → Guard → Dashboard or Live View → Guard for detector status, active findings and compact history. Findings retains earlier changes, expandable evidence and recorded task lookup. Integration guide opens the instrumentation instructions; Email / Slack notifications opens the existing notification settings. Enable UsageTap Guard changes and recovery only when requested. Notification destinations are shared with other admin alerts.

Set USAGETAP_ENVIRONMENT=production or test in the server deployment, or configure UsageTapClient defaultEnvironment. SDK and observer read that variable; direct HTTP must send X-UsageTap-Environment on every UsageTap request, including customer creation, reads/updates, call_begin/end and custom_meter. Do not send it to provider requests, infer from NODE_ENV, or hide it in metadata/tags. A customer-panel Traffic group pin overrides request labels for new usage. Respect it and do not change admin groups unless asked. Automatic restores request labels; without a pin, omission stays unlabelled. Existing usage, active calls and retries keep their recorded group. Preserve the label across retries and workers; explicit lifecycle conflicts are rejected. Verify outgoing headers and stored labels with a supporting SDK release. One customer ID can have both labels. Filters do not create separate allowances, change Stripe mode, make test traffic free, or partition customer signals. Page-level Environment filters group unlabelled usage with Production and keeps Dev/Test separate; API header filters still match exact recorded labels. Usage Forecast defaults to All traffic, offers Production, and does not offer Dev/Test-only forecasting. Guard behavioral checks always compare Production + unlabelled usage with matching retained history. Dev/Test is excluded from those checks. A separate environment-mix check uses all recorded traffic to detect substantial Dev/Test growth and share increases; it follows existing Guard notification opt-ins. There is no Dev/Test inclusion setting. Viewing filters do not change detection, and eligible retained history is reused without restarting learning.

Work autonomously:
1. Inspect the repository to find every server-side AI/provider call, the framework/runtime, existing provider SDKs, streaming behavior, tests, environment-variable conventions, and the trusted authenticated customer or tenant ID.
2. Choose the smallest safe integration. Prefer @usagetap/sdk for supported server-side JavaScript/TypeScript provider clients. Use the explicit SDK lifecycle when BLOCK or DOWNGRADE must control provider invocation or model selection; provider wrappers do not invent a safe fallback model. Use direct HTTPS for other languages or when the SDK is not a safe fit. Preserve the existing provider, model, request/response shape, and error behavior.
3. Ask one concise clarification only if a stable server-trusted customerId cannot be inferred or there are multiple materially different integration targets. Otherwise proceed.
4. Report optional top-level completionReason at call_end/endCall from the primary provider finish_reason, stop_reason, or Responses incomplete_details.reason (otherwise terminal status such as completed). Omit unknown values; never infer from HTTP 200 or token counts. Use a supporting package release or direct HTTP, and verify the outgoing payload. Values are trimmed, 1-128 characters, without control characters. This does not change pricing/lifecycle. Guard can compare reported reason categories when sufficient eligible data is available. Implement the complete Meter lifecycle. Attribute every call to a stable customerId and feature; begin before provider work; inspect data.allowed before invoking the provider; do not end a denied call because call_begin already finalized it; finalize an allowed call exactly once on success, error, stream completion, cancellation, or abort; report the actual model and usage returned by the provider; sanitize error metadata; and use one unique idempotency key per logical call, reused only for its retries.
5. Begin replay preserves the saved effective decision. Current account metadata can be unavailable: handle null subscription, customerStatus, canceled, inactive and payg.enabled, unknown meter quantities and omitted balance amounts. Never treat unknown values as zero or healthy. Use a fresh idempotency key for new work. Keep all credentials server-side. Never read, print, log, or commit secret values. Add placeholders only to the project's example environment file. UsageTap Meter needs USAGETAP_API_KEY (create a utk-… key with usage:write at https://usagetap.com/embed-api?features=meter#meter-key-setup). Keep the app's existing provider key such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY.
6. Add or update focused tests and run the relevant test, lint, and type/build checks. If credentials are unavailable, finish and verify the code without attempting a live provider request.

For POST /call, require explicit requested-tier permission before provider work or finalization. Otherwise the endpoint returns the accepted HTTP 200 begin envelope directly (data.callId, data.allowed, available rate-limit evidence), without compound begin/end/vendor/endUsage fields. This includes usage-only requests and denied retries. Standard fallback permission does not authorize an unchanged premium vendor payload; select an approved fallback through the explicit lifecycle.

Configured LLM burst limits count distinct attempts including denials; replayed keys do not count again. Premium burst downgrade checks/counts both tiers and records the call under standard. Counts share traffic environments and expire conservatively at one-second resolution. Existing customers/window increases can report estimated state during one-window warm-up; strict boundaries require all writers upgraded and a fully tracked window. Storage failure/exhausted contention returns 503 BURST_ADMISSION_UNAVAILABLE; retry the same key. Do not infer PAYG reservation or exactly-once provider execution.

When done, report:
- what you changed and which calls are now metered;
- the exact environment-variable names the user must set, without values;
- any one remaining user decision or action;
- the command or request that produces the first metered call;
- how to watch it in Live View at https://usagetap.com/live and find the completed request in recent calls at https://usagetap.com/dashboard#recent-calls;
- the integration guide at https://usagetap.com/embed-api?features=meter if setup needs attention;
- optional next steps in Control Center at https://usagetap.com/dashboard?tab=system. The first successful metered call completes the initial setup.

Do not stop at a plan or code sample. Make the changes when it is safe to do so.

1. Required agent behavior

  1. Find every server-side provider call, including streaming, background jobs, retries, tool loops, and alternate routes.
  2. Identify a stable, server-trusted customer or tenant ID. Never trust a browser-supplied customer ID without checking it against the authenticated session.
  3. Prefer the provider wrapper for the smallest JavaScript or TypeScript change. Use the explicit SDK lifecycle when the app must enforce BLOCK or DOWNGRADE itself. Use direct HTTPS outside the supported server-side JavaScript runtime.
  4. Begin before provider work and finalize once after success, provider error, stream completion, cancellation, or abort. Report the model and usage returned by the provider.
  5. Preserve the original provider error if UsageTap finalization also fails. Make the finalization failure observable without replacing the primary error.
  6. Add focused tests and run the repository's relevant test, lint, type, and build checks.
Ask one concise question only when a stable customer ID cannot be inferred or multiple integration targets would materially change the result. Missing credentials do not block the code change: add environment variable names without values and verify without a live provider call.

POST /call, /call_begin, /call_end and /custom_meter use fast index-based key authentication. Revoked/replaced keys and previous permissions may remain usable there until index propagation, with no promised maximum delay. Other durable-key requests recheck the current primary record and fail closed on verification failure. New/replacement key discovery, issued-session lifetimes and the internal verifier's permitted 30-second positive cache retain their existing behavior.

2. Credentials and transport

Direct-provider Meter Tap and UsageTap Gateway can coexist across call sites and change over time. Code Integration is the onboarding page. Its options select matching prompts and examples. Add the code first, then create or confirm the server key immediately before the test call. Gateway uses gateway:invoke and already meters its own model calls. If you are unsure, start with Gateway.

New inline integration keys include usage:write, gateway:invoke, and compression:invoke, without read, admin, or widget access. Existing keys keep their permissions. Permissions do not enable routing or compression. Optional compression is easier through Gateway: add compress: true to supported requests. Direct-provider calls need an SDK wrapper or a separate compression step.

UsageTap key

Create a Meter call key in Code Integration. Use a utk- key with usage:write. Store it as USAGETAP_API_KEY on the server. Meter endpoints now require the key's calls capability; admin, embed, gateway, and compression-only credentials are not interchangeable. Wrong-capability keys return CALLS_ACCESS_REQUIRED.

Provider key

Keep the provider key the app already uses, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY. UsageTap does not replace it for a Meter integration.

  • Never expose either key to browser code, logs, commits, or agent output.
  • API authentication accepts Authorization: Bearer $USAGETAP_API_KEY or x-api-key.
  • Every API request must send Accept: application/vnd.usagetap.v1+json. Missing or incompatible Accept headers return HTTP 406.
  • JSON POST requests should send Content-Type: application/json. Responses use the versioned UsageTap media type and a standard result envelope.

3. Choose the integration path

Provider wrapper

Server-side JavaScript or TypeScript using OpenAI, OpenRouter, or Anthropic. Best for the first metered call and automatic success, error, and stream finalization.

Explicit SDK lifecycle

Use UsageTapClient.withUsage(), beginCall(), and endCall() when the app must inspect entitlements, select an approved fallback, attach custom usage, or coordinate complex streaming.

Direct HTTPS

Use for Python, Go, Java, other runtimes, unsupported providers, or when wrapping the existing client would change behavior.

The SDK requires Node.js 18.17 or newer and is server-only. Do not construct UsageTapClient in browser code. The React package is an application helper, not permission to ship a Meter key to the browser.

4. JavaScript and TypeScript SDK

Install @usagetap/sdk plus the provider package already used by the application. Import OpenAI helpers from @usagetap/sdk/openai, OpenRouter helpers from @usagetap/sdk/openrouter, and Anthropic helpers from @usagetap/sdk/anthropic.

Smallest provider-preserving integration
import OpenAI from "openai";
import { withMetering } from "@usagetap/sdk/openai";

const provider = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export function meteredOpenAI(customerId: string) {
  return withMetering(provider, {
    apiKey: process.env.USAGETAP_API_KEY,
    customerId,
    feature: "chat.reply",
  });
}

// The OpenAI client shape is preserved.
const response = await meteredOpenAI(currentCustomer.id).responses.create({
  model: existingModel,
  input,
});

The wrapper preserves chat.completions.create() and responses.create(), plus Anthropic messages.create() and the synchronous messages.stream() helper. Anthropic streams retain event handlers, async iteration, cancellation, and final-message helpers. The wrappers generate unique idempotency keys, retry eligible UsageTap requests, extract provider usage, and finalize consumed or cancelled streams. They do not know the application's safe model fallback. Use the explicit path when BLOCK or DOWNGRADE must control provider selection.

Explicit SDK lifecycle with entitlement enforcement
import OpenAI from "openai";
import { UsageTapClient } from "@usagetap/sdk";

const usageTap = new UsageTapClient();
const openai = new OpenAI();

const response = await usageTap.withUsage(
  {
    customerId: currentCustomer.id,
    feature: "chat.reply",
    requested: { premium: true },
  },
  async ({ begin, setUsage }) => {
    // A blocked call is already finalized by call_begin.
    // If DOWNGRADE is configured, select a known safe fallback here.
    if (!begin.data.allowed.premium) {
      throw new Error("Premium usage is not allowed for this customer");
    }

    const result = await openai.responses.create({
      model: existingModel,
      input,
    });

    setUsage({
      modelUsed: result.model ?? existingModel,
      providerUsed: "openai",
      inputTokens: result.usage?.input_tokens,
      responseTokens: result.usage?.output_tokens,
      cachedInputTokens:
        result.usage?.input_tokens_details?.cached_tokens ?? 0,
    });

    return result;
  },
);

Supported SDK surface

Root client: UsageTapClient and alias UsageTap; lifecycle methods beginCall, endCall, withUsage, meter, checkUsage, createCustomer, changePlan, and incrementCustomMeter. Provider adapters include withMetering, explicit wrappers, OpenAI route streaming helpers, Express middleware, and OpenAI-compatible OpenRouter exports.

5. Direct HTTPS lifecycle

Complete success and provider-error path
const apiKey = process.env.USAGETAP_API_KEY;
const apiBase = process.env.USAGETAP_BASE_URL ?? "https://api.usagetap.com";

async function usageTapPost(path, body) {
  const response = await fetch(`${apiBase}/${path}`, {
    method: "POST",
    headers: {
      Accept: "application/vnd.usagetap.v1+json",
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`,
      "X-UsageTap-Environment": "production", // test in dev/staging
    },
    body: JSON.stringify(body),
  });
  const envelope = await response.json();
  if (!response.ok || envelope.result?.status !== "ACCEPTED") {
    throw new Error(
      `UsageTap ${path} failed: ${envelope.result?.code ?? response.status}`,
    );
  }
  return envelope;
}

const idempotencyKey = crypto.randomUUID();
const begin = await usageTapPost("call_begin", {
  customerId: currentCustomer.id,
  feature: "chat.reply",
  requested: { premium: true },
  idempotencyKey,
});

// call_begin returns HTTP 200 for entitlement denials and has already
// finalized the denied call. Do not invoke the provider or call call_end.
if (!begin.data.allowed.premium) {
  throw new Error("Premium usage is not allowed for this customer");
}

let providerResponse;
try {
  providerResponse = await openai.responses.create({
    model: existingModel,
    input,
  });
} catch (providerError) {
  try {
    await usageTapPost("call_end", {
      callId: begin.data.callId,
      error: {
        code: "PROVIDER_ERROR",
        message: "Provider request failed",
      },
    });
  } catch {
    // Preserve the original provider error. Report finalization separately.
  }
  throw providerError;
}

await usageTapPost("call_end", {
  callId: begin.data.callId,
  modelUsed: providerResponse.model ?? existingModel,
  providerUsed: "openai",
  inputTokens: providerResponse.usage?.input_tokens,
  responseTokens: providerResponse.usage?.output_tokens,
  cachedInputTokens:
    providerResponse.usage?.input_tokens_details?.cached_tokens ?? 0,
});
Direct callers must send a unique explicit idempotency key for each new logical call and reuse that key only for retries of that call. The API has a deterministic fallback when the field is omitted; identical customer, feature, requested entitlement, call type, hold, and pricing inputs can therefore replay an earlier call. Do not rely on that fallback for normal traffic.

Use the Custom & API meters tab for SDK, fetch, and Python examples with matching agent instructions. Meter includes Guard as sufficient eligible production history builds.

Agentic & API Calls

For HTTP API requests and MCP tool calls, enable the named Agentic & API Calls meter on the customer's plan. Set an included allocation and single or graduated overage prices. Select PAYG credit as the funding source to charge extra calls against the customer's credit balance.

await usageTap.incrementCustomMeter({
  customerId,
  meterSlot: "AGENTIC_API",
  taskId: "import_123",
  taskType: "document.import",
  customerUserId: "user_42",
  amount: 1,
  feature: "mcp.tools.call",
  metadata: { kind: "mcp", serverName: "github", toolName: "search_code" },
}, { idempotencyKey: requestId });

Report usage after work completes and reuse the same idempotency key on retries. Add metadata.toolName and optional metadata.serverName for MCP calls, or metadata.endpoint and metadata.method for HTTP APIs, so Live View can identify the operation. This meter records calls without model, token, or tier fields. It uses the custom meter funding and asynchronous settlement rules; it does not reserve credit or enforce a rolling rate limit.

Live View and meter activity display these events. Select agenticApi in usage and forecast widgets. The credit ledger shows settled charges.

6. POST /call_begin

FieldRequiredContract
customerIdYesStable server-trusted customer or tenant identifier. Maximum 100 sanitized characters.
featureRecommendedStable application operation such as chat.reply or document.summarize.
taskId / taskTypeRecommended when operations span callsTop-level operation ID and stable workload category. Trimmed, case-sensitive, 1–128 characters without controls. Share taskId across related LLM and meter events; keep per-event idempotency keys separate.
customerUserIdWhen knownStable non-PII end-user ID for attribution; not a substitute for customerId.
tagsNoLow-cardinality labels. Do not include secrets or raw prompts.
requestedRecommendedEntitlements the provider call needs: standard, premium, audio, image, search, and reasoningLevel.
idempotencyKeyDirect API: yesUnique per logical call, stable across its retries. The SDK supplies one by default.
customerName / customerEmailNoOptional profile data used when the customer is first provisioned. Avoid sending data the product does not need.
batch / pricingModeNoBatch pricing metadata. pricingMode, when present, is authoritative.
Request
{
  "customerId": "tenant_123",
  "customerUserId": "user_42",
  "taskId": "import_123",
  "taskType": "document.import",
  "feature": "chat.reply",
  "tags": ["production"],
  "requested": {
    "standard": true,
    "premium": false,
    "audio": false,
    "image": false,
    "search": false,
    "reasoningLevel": "NONE"
  },
  "idempotencyKey": "one-key-per-logical-call"
}
Response envelope
{
  "result": {
    "status": "ACCEPTED",
    "code": "CALL_BEGIN_SUCCESS",
    "timestamp": "ISO-8601"
  },
  "correlationId": "request-correlation-id",
  "data": {
    "callId": "call-id",
    "startTime": "ISO-8601",
    "newCustomer": false,
    "canceled": false,
    "policy": "NONE | BLOCK | DOWNGRADE",
    "allowed": {
      "standard": true,
      "premium": false,
      "audio": false,
      "image": false,
      "search": false,
      "reasoningLevel": "NONE | LOW | MEDIUM | HIGH"
    },
    "entitlementHints": { "...": "advisory details" },
    "rateLimits": { "...": "optional rolling-call state" },
    "meters": { "...": "remaining, used, limit, unlimited, ratio" },
    "remainingRatios": { "...": "0 through 1, or null" },
    "subscription": { "...": "current subscription snapshot" },
    "plan": { "id": null, "name": null, "version": null },
    "balances": { "...": "optional remaining balances" },
    "idempotency": {
      "key": "one-key-per-logical-call",
      "source": "explicit | derived"
    }
  }
}
  • A blocked entitlement still returns an accepted HTTP 200 envelope with allowed set accordingly. The denied call record is already finalized; do not invoke the provider and do not call /call_end.
  • For DOWNGRADE, choose only a fallback model already approved by the application or user. Never invent a provider or model mapping.
  • Treat entitlementHints, models, and rate-limit snapshots as guidance. The allowed fields are the decision inputs.
  • POST /call requires the requested tier to be allowed before provider work or finalization. Otherwise it returns the accepted HTTP 200 begin envelope directly, with data.allowed and data.callId, without compound begin/end/vendor fields. This includes usage-only requests and denied retries. Standard fallback permission does not authorize an unchanged premium vendor payload; select an approved fallback explicitly.
  • Configured LLM burst limits count distinct attempts, including denials, across traffic environments. Replayed keys do not count again. Premium burst downgrade checks standard capacity and counts both attempted tiers, recording the call under standard. Counts expire conservatively at one-second resolution. Existing customers and window increases can report estimated state during one-window warm-up; strict boundaries require upgraded writers and a fully tracked window. Storage failure or exhausted contention returns 503 BURST_ADMISSION_UNAVAILABLE; retry the same key.

7. POST /call_end

FieldRequiredContract
callIdYesThe exact callId returned by call_begin.
modelUsedSuccessUse the provider-returned model when available, otherwise the actual requested model.
inputTokensWhen availableTotal provider input tokens, including cache reads and cache writes.
cachedInputTokensWhen availableInput tokens read from provider cache. Do not subtract them from inputTokens.
cacheWriteInputTokensWhen availableInput tokens written to provider cache. They remain included in inputTokens.
responseTokensWhen availableProvider output or completion tokens.
reasoningTokens / searches / audioSecondsWhen availableSend actual provider usage only. Omit unavailable metrics rather than estimating them silently.
errorProvider failureA sanitized object with non-empty code and message. Do not include prompts, credentials, or raw provider bodies.
Successful provider call
{
  "callId": "call-id",
  "modelUsed": "provider-returned-model",
  "inputTokens": 1200,
  "cachedInputTokens": 400,
  "cacheWriteInputTokens": 0,
  "responseTokens": 180,
  "reasoningTokens": 0,
  "searches": 0,
  "audioSeconds": 0
}
Provider failure
{
  "callId": "call-id",
  "error": {
    "code": "PROVIDER_ERROR",
    "message": "Provider request failed"
  }
}
Accepted response
{
  "result": {
    "status": "ACCEPTED",
    "code": "CALL_END_SUCCESS",
    "timestamp": "ISO-8601"
  },
  "correlationId": "request-correlation-id",
  "data": {
    "callId": "call-id",
    "status": "COMPLETED | FAILED",
    "error": { "code": "optional", "message": "optional" },
    "costUSD": 0.00123,
    "standardCostUSD": 0.00123,
    "pricingMultiplier": 1,
    "usage": {
      "inputTokens": 1200,
      "cachedInputTokens": 400,
      "cacheWriteInputTokens": 0,
      "billableInputTokens": 800,
      "responseTokens": 180,
      "reasoningTokens": 0
    },
    "metered": { "...": "usage applied to configured meters" },
    "spendVelocity": { "...": "optional hour and day snapshots" },
    "meters": { "...": "updated meter snapshot" },
    "balances": { "...": "updated balances" }
  }
}

Optional completionReason on call_end / SDK endCall records the primary provider finish_reason, stop_reason, or Responses incomplete_details.reason (otherwise terminal status such as completed). Omit unknown values; HTTP 200 and token counts do not establish completion. Values are trimmed, 1–128 characters, without control characters. Verify transport with a supporting package release or direct HTTP. Pricing, lifecycle status, and Guard detection are independent. /call_end is idempotent. A repeated finalization does not decrement meters twice. The SDK error object is a first-class API contract: an accepted provider-error finalization returns data.status = "FAILED" while preserving the normalized error metadata.

8. Streaming, retries, and failure policy

  • Finalize after the stream is consumed, not when headers arrive. Include final usage events from the provider when its streaming option must be enabled explicitly.
  • Finalize on consumer cancellation and abort. Do not discard a wrapped stream without consuming or cancelling it.
  • Retry a UsageTap request only with the same idempotency key and call ID for the same logical call. Never generate a new key inside a retry loop.
  • Begin replay preserves the saved effective decision. Current account metadata can be unavailable: handle null subscription, customerStatus, canceled, inactive and payg.enabled, unknown meter quantities and omitted balance amounts. Do not treat unknown values as zero or healthy.
  • The SDK defaults to three total attempts with bounded backoff and jitter for retryable UsageTap failures. Provider retries remain controlled by the existing provider integration.
  • Decide and document fail-open versus fail-closed behavior for a UsageTap outage. Access enforcement generally fails closed; observability-only metering may fail open if the product owner accepts missing usage.

9. Customer and Meter setup after code

  1. Set USAGETAP_API_KEY and the existing provider key in the application's server runtime.
  2. Run the exact local command or request identified by the coding agent to produce one provider call.
  3. Confirm the connection and customer attribution on Code Integration.
  4. Configure customer plans, call and output-token allowances, limits, replenishment, and optional custom meters in Meter setup.
  5. Exercise one allowed call and one limit path before production.

POST /customers and usageTap.createCustomer() are idempotent and can provision a customer before their first model call. GET /customers/{customerId}/usage and usageTap.checkUsage() return the current entitlement and meter snapshot. Plan changes require an admin key and should not be embedded in the initial application integration.

10. Explicitly outside first onboarding

Do not add UsageTap Gateway, prompt compression, Compress keys, sampling or payload capture, deployment resolution, provider migration, model changes, Stripe synchronization, browser embed sessions, or admin automation unless the user asks. The SDK exposes several of these advanced capabilities, but their presence is not permission to enable them.

11. Agent completion contract

The task is complete only when:

  • the intended server-side provider calls are actually metered;
  • customer attribution is stable and authenticated;
  • success, failure, retry, streaming, cancellation, and limit behavior are handled;
  • keys remain server-only and no values were logged or committed;
  • focused tests and repository checks pass;
  • the handoff names every required environment variable, the first-call command, the verification page, and the remaining Meter configuration action.

Compression integrations

The Compression tab provides text, HTML, messages, SDK wrapper, and Gateway examples. Selected modes, role tuning, gates, and fallback settings update the code and coding-agent prompt together. Read credentials from the server environment and forward the configured traffic label to UsageTap.

Compression-only wrappers do not record model usage. For combined compression and Meter, select both on the LLM calls tab. Gateway already meters its calls; do not add a duplicate lifecycle. Guard is included through Meter as eligible history builds and does not automatically block activity.

Browser authentication

12. Secure Gateway sessions for browser chat

Keep the existing UsageTap key on the customer's server. Their authenticated backend exchanges it for a customer-bound, five-minute client token that the chat panel can use directly. A Gateway key gets gateway:chat; a Compression key gets compression:run; a combined key gets both. The app's normal login session is the renewal authority, so there is no separate refresh token to store. If the parent key can use Compression, the temporary session inherits that capability too.

  1. 1. Authenticate

    The customer backend verifies its user and resolves stable UsageTap customer and user IDs.

  2. 2. Mint

    The backend creates a five-minute session with the parent key's effective Gateway and Compression capabilities.

  3. 3. Call and renew

    The browser keeps the token in memory, calls Gateway, and asks its backend for another token before expiry.

1. Customer backend: mint and renew

Adapt the authentication and identity lookup to the application. The browser must never choose either identifier.

app/api/usagetap/gateway-session/route.ts
import { NextResponse } from "next/server";
import { requireUser } from "@/lib/auth";
import { usageTapIdentityForUser } from "@/lib/usagetapCustomers";

// GET /api/usagetap/gateway-session
export async function GET() {
  const user = await requireUser();

  // Resolve UsageTap-safe, stable IDs from the authenticated user.
  // Never accept either ID from the browser.
  const identity = await usageTapIdentityForUser(user.id);

  const response = await fetch(
    "https://api.usagetap.com/v1/client/sessions",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.USAGETAP_API_KEY}`,
        Accept: "application/vnd.usagetap.v1+json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        customer_id: identity.customerId,
        customer_user_id: identity.customerUserId,
      }),
      cache: "no-store",
    },
  );

  const envelope = await response.json();
  if (!response.ok) {
    return NextResponse.json(
      { error: "Unable to create a client session" },
      { status: response.status },
    );
  }

  return NextResponse.json(
    {
      token: envelope.data.token,
      expiresAt: envelope.data.expires_at,
    },
    { headers: { "Cache-Control": "no-store" } },
  );
}

2. Browser: hold, renew, and retry once

The shared renewal promise prevents several simultaneous chat calls from minting several sessions.

lib/usagetapGateway.ts
type ClientSession = {
  token: string;
  expiresAt: string;
};

let session: ClientSession | undefined;
let renewal: Promise<ClientSession> | undefined;

async function gatewayToken(forceRenew = false) {
  const validForMs = session
    ? Date.parse(session.expiresAt) - Date.now()
    : 0;

  if (!forceRenew && session && validForMs > 60_000) {
    return session.token;
  }

  renewal ??= fetch("/api/usagetap/gateway-session", {
    credentials: "same-origin",
    cache: "no-store",
  }).then(async (response) => {
    if (!response.ok) throw new Error("Unable to renew Gateway session");
    return response.json() as Promise<ClientSession>;
  });

  try {
    session = await renewal;
    return session.token;
  } finally {
    renewal = undefined;
  }
}

async function gatewayRequest(
  path: "/chat/completions" | "/responses",
  body: unknown,
  retry = true,
) {
  const response = await fetch(`https://gateway.usagetap.com/v1${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${await gatewayToken()}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (response.status === 401 && retry) {
    session = undefined;
    await gatewayToken(true);
    return gatewayRequest(path, body, false);
  }
  if (!response.ok) throw new Error(`Gateway request failed: ${response.status}`);
  return response;
}

// Keep the session only in memory. This works for JSON or streamed responses.
const response = await gatewayRequest("/chat/completions", {
  model: "usagetap/standard",
  messages,
  stream: true,
  // Optional when the server key has compression:invoke.
  // Omit this to let centrally configured Runtime Compression decide.
  compress: true,
});

Security boundary

Keep USAGETAP_API_KEY server-only. Do not put either credential in localStorage, sessionStorage, a query string, logs, or a public environment variable. Session claims supply customer attribution and restrict access to chat completions and responses; they cannot list models or run batches. Hosted and configured Runtime Compression work only when the minting key has compression:invoke.

Coding-agent handoff

Implement the secure browser path

This prompt asks a coding agent to find the app's trusted login and customer mapping, add the mint endpoint and in-memory renewal, preserve streaming, and test the security boundary.

Paste into your coding agent
Implement secure UsageTap Gateway authentication for the browser chat panel in this repository.

Read https://usagetap.com/llmreference#browser-gateway-sessions first and treat it as the canonical contract. The goal is only to let authenticated application users call UsageTap Gateway without exposing the customer's long-lived key. Do not create a new API key type, add origin allowlists, or change providers or models unless the repository or user explicitly requires it.

Work autonomously:
1. Inspect the application's authentication, tenant or account model, server framework, chat client, environment-variable conventions, and tests.
2. Find the stable UsageTap customer ID and optional stable end-user ID that belong to the authenticated application user. Resolve and validate both on the server. Never accept a customer or user ID from browser input.
3. Add a same-origin authenticated endpoint such as GET /api/usagetap/gateway-session. It must use the existing server-only USAGETAP_API_KEY with gateway:invoke to POST https://api.usagetap.com/v1/client/sessions. Send Accept: application/vnd.usagetap.v1+json, Content-Type: application/json, customer_id, and optional customer_user_id. UsageTap derives the temporary capabilities from the parent key: gateway:invoke becomes gateway:chat and compression:invoke becomes compression:run. Never let browser input choose or widen scopes.
4. Return only data.token and data.expires_at to the browser with Cache-Control: no-store. Never expose the long-lived key through NEXT_PUBLIC_, VITE_, browser bundles, browser storage, query strings, logs, errors, or committed values.
5. Add a small browser token manager. Keep the five-minute bearer token in memory, share one in-flight renewal between concurrent requests, renew through the authenticated same-origin endpoint about 60 seconds before expiry, and retry a Gateway request at most once after a 401. There is no separate refresh token; the application's existing login session is the renewal authority.
6. Send the short-lived token in Authorization: Bearer to https://gateway.usagetap.com/v1/chat/completions or /v1/responses. Preserve the existing request, streaming, model, Compression, response, cancellation, and error behavior. A Compression-capable session may use the normal compress option, while centrally configured Runtime Compression requires no browser flag. Do not send customer identity in the Gateway request because the signed session identity is authoritative.
7. Add focused tests for unauthenticated minting, trusted identity lookup, upstream mint failure, no-store responses, concurrent renewal, renewal before expiry, and one-time 401 retry. Run the relevant tests, lint, typecheck, and build checks.

When done, report the files changed, the server-only environment-variable name without its value, the trusted customer and user identity sources, the chat call sites using the short-lived token, the checks run, and how to verify that browser-supplied identity cannot cross customer boundaries.

Do not stop at a plan or code sample. Make the changes when it is safe to do so.

See the canonical browser-session contract and the API reference.

Gateway Chat Completions and Responses requests, including streams, accept at most 1 MiB (1,048,576 bytes) of decoded UTF-8 JSON before compression. There is no fixed message or input-item count cap. Provider/model input, context and output limits still apply; budget for every fallback model. Upstream HTTP 400 input errors do not trigger fallback. Native batches have separate limits. See Gateway request limits.

Guard reporting and task attribution checked against repository source on October 28, 2026, including traffic environment headers, SDK wrapper forwarding, meter metadata, task pagination, and readiness. Check the installed SDK transport for older builds. This source review does not verify a live deployment or notification delivery.