Back to Code Integration

UsageTap Integration Guide

The live Code Integration workspace is the source of truth for executable examples:

Open Code Integration

It generates the smallest current example for your selected features and model provider, shows the exact server-side keys, and links to maintained playgrounds for specialized workflows.

Recommended: let your coding agent implement Meter

Paste the one-prompt setup from the LLM Integration Reference into the coding agent that has access to your repository. The agent is instructed to inspect the existing provider calls and authentication, choose the UsageTap SDK or direct HTTPS, implement the complete Meter lifecycle, add tests, and return the exact key and verification steps.

The initial onboarding target is UsageTap Meter only. Do not add Gateway, Compress, prompt compression, or Stripe synchronization until the first metered call is working and the user explicitly chooses the next product.

Start here

  1. Keep UsageTap Meter selected for the first integration.
  2. Pick the provider already used by the application: OpenAI, Anthropic, or OpenRouter. Keep the existing provider and model.
  3. Pick the implementation: UsageTap SDK, Without UsageTap SDK, or Python.
  4. Start with Minimal diff, then open Complete example when you need the surrounding request lifecycle.
  5. Create the keys shown beside the example and place them in your server environment.
  6. Copy the generated code, run one request, and confirm the call appears in the connection verification step.
  7. Open UsageTap Quickstart to define the default customer plan, allowances, limits, and limit behavior.

Which key do I need?

What you are using Environment variable Key
UsageTap Meter USAGETAP_API_KEY utk-… with usage:write
UsageTap Compress USAGETAP_API_KEY utk-… with compression:invoke
Meter + Compress USAGETAP_API_KEY utk-… with usage:write and compression:invoke
UsageTap Gateway USAGETAP_API_KEY utk-… with gateway:invoke
OpenAI OPENAI_API_KEY Your OpenAI server key
Anthropic ANTHROPIC_API_KEY Your Anthropic server key

Add usage:read for usage reports, customers:read for customer and plan listings, and customers:write for provisioning, plan changes, and replenishment. Existing prefixed keys continue to use their historical permissions. | OpenRouter | OPENROUTER_API_KEY | Your OpenRouter server key |

Put these variables in the server environment. For local Next.js development, that is commonly .env.local. Never use a NEXT_PUBLIC_ name and never send a provider or UsageTap key to browser code.

Create or manage UsageTap keys

Customer attribution

When an example uses customerId, populate it from your trusted server-side session or database. Use the same stable ID for the same customer across calls. Do not accept an unverified customer ID directly from browser input.

End-user attribution is optional. When a customer account has multiple users, send customerUserId from the same trusted server-side identity. Prefer a stable, non-PII application user ID. customerUserName and customerUserEmail are optional display metadata for Live activity and should be omitted when they are unnecessary.

const usageContext = {
  customerId: currentCustomer.id,       // Required customer/account ID
  customerUserId: currentUser.id,       // Optional stable end-user ID
  customerUserName: currentUser.name,   // Optional display metadata
  customerUserEmail: currentUser.email, // Optional display metadata
  feature: "chat.reply",
};

Direct HTTP requirements

UsageTap public API requests use:

  • Authorization: Bearer <USAGETAP_API_KEY>
  • Accept: application/vnd.usagetap.v1+json
  • Content-Type: application/json when a request has a JSON body
  • Idempotency-Key for retried create, begin, and state-changing requests

The Without UsageTap SDK and Python examples in Code Integration include these headers. See the API reference for request and response contracts.

Specialized workflows

Keep specialized code beside the product workflow that owns it:

The Examples & playgrounds tab in Code Integration also covers customer management, Gateway batches, compression, summarization, sampling, and profiling without duplicating each product’s local setup.

Integration checklist

  • At least one UsageTap feature is selected.
  • Every key is server-side.
  • The provider key and UsageTap key are separate variables.
  • customerId comes from a trusted server-side identity.
  • Optional customerUserId comes from trusted application identity, not request input.
  • Direct API calls send the required versioned Accept header.
  • Failed provider calls still finish metering with an error.
  • The integration has been tested with a real customer and a realistic prompt.

If you need help, use the support option in the application after opening the relevant product workspace.