Zorveus Documentation

Control AI inference spending, attach plan-based spend caps, and send your first request through Zorveus.

If your organization pays for users' AI inference, Zorveus lets you set and enforce a spending limit for each product user.

Map subscription plans to per-user spending caps, issue credits, and track usage. When enforced allowance cannot fund a request, Zorveus rejects the request. A new period, a higher cap, or available credits can restore access.

1. Create a business organization and API key

Follow these steps in the Zorveus Dashboard:

Select or create a Business Organization

Fund your wallet or configure BYOK

Add funds under Wallet, or connect your upstream provider credentials under Provider Credentials for Bring Your Own Key routing.

Create an app and generate your API key

Navigate to Apps, click Create App, and open your newly created application. Under the connection settings, click Create API Key and copy the generated zrv_... token.

Choose a credit mode

Keep enforce_if_present to enforce a configured base allowance plus credits for attributed users. Use track_only to record usage without rejecting requests for product-user allowance. Configure a cap to establish a finite allowance.

Common gotchas to avoid

For configuration choices and worked scenarios, see Configure product-user allowances.

Business vs Developer Org

Only Business Organizations issue direct API keys (zrv_...). Developer Organizations only manage OAuth applications (zrv_client_...).

Base URL Trailing Path

OpenAI SDK clients require https://api.zorveus.com/v1. Anthropic SDK clients require https://api.zorveus.com without /v1.

API Key vs Service Key

Send your API key (zrv_...) to model routes. Never send your organization Service key (zrv_svc_...) to inference endpoints.

Automatic User Provisioning

You do not need to pre-register product users. Send X-Zorveus-External-User-ID in the headers or metadata.external_user_id in the body. Either creates the product user on their first request and attributes subsequent requests to that user. Include the same identifier on every request.

2. Send an attributed inference request

Pass external_user_id at metadata.external_user_id. Put the optional name, email, and custom fields inside metadata.product_user.

Client SDK / Framework:

// npm install @zorveus/sdk
import { Zorveus } from "@zorveus/sdk";

// Initialize Zorveus client with API key and product user attribution
const client = new Zorveus({
  apiKey: "zrv_your_api_key",
  externalUserId: "usr_sara_101", // Your internal user ID
  displayName: "Sara Connor",     // Optional user name for dashboard
  email: "sara@example.com",       // Optional user email
  userMetadata: { plan: "pro" },   // Optional custom metadata
});

async function main() {
  // Send completion request — usage is attributed and capped per user
  const completion = await client.chat.completions.create({
    model: "openai/gpt-4.1-mini",
    messages: [
      { role: "system", content: "You are a helpful coding assistant." },
      { role: "user", content: "Write a Python function to check for prime numbers." },
    ],
        temperature: 0.7,
    zorveusMetadata: {
      externalUserId: "usr_sara_101",
      displayName: "Sara Connor",
      userEmail: "sara@example.com",
      metadata: { plan: "pro" },
    },
  });

  console.log(completion.choices[0].message.content);
}

main();

3. Map subscription plans to spending limits

Businesses structure pricing around tiered subscription plans (such as Free, Starter, Pro, and Enterprise).

Because every Zorveus API key carries its own spending limits and model access rules, managing multi-tier pricing plans requires no custom gateway logic:

Free Tier Key: Attach a low monthly spend limit (e.g. $1.00/month) restricted to budget models like openai/gpt-4.1-mini.
Pro Tier Key: Attach a higher monthly allowance (e.g. $20.00/month) with access to flagship models like openai/gpt-4o and anthropic/claude-3.5-sonnet.
Enterprise Tier Key: Attach custom high-volume caps or unlimited spending with dedicated provider routing.

When a customer changes plans, have your backend select the API key for the new tier. Never expose an API key to the customer. Update the key's spending limit in the dashboard, not through a service-key request.

Select a plan tier in backend code

Client SDK / Framework:

import { Zorveus } from "@zorveus/sdk";

// Map your app subscription plans to tier-specific Zorveus keys
const PLAN_KEYS: Record<string, string> = {
  free: process.env.ZORVEUS_FREE_TIER_KEY!,    // $1.00/mo cap, budget models
  pro: process.env.ZORVEUS_PRO_TIER_KEY!,      // $20.00/mo cap, flagship models
  enterprise: process.env.ZORVEUS_ENTERPRISE_KEY!,
};

export async function handleUserInference(user: { id: string; name: string; plan: "free" | "pro" }) {
  // Select key bound to user's plan tier
  const apiKey = PLAN_KEYS[user.plan] || PLAN_KEYS.free;

  const client = new Zorveus({
    apiKey,
    externalUserId: user.id,
    displayName: user.name,
    userMetadata: { plan: user.plan },
  });

  return await client.chat.completions.create({
    model: user.plan === "pro" ? "openai/gpt-4o" : "openai/gpt-4.1-mini",
    messages: [{ role: "user", content: "Analyze market trends." }],
  });
}

Next Steps

Product-User Metering

Attribute inference requests to individual end-users using external_user_id.

Connect User Wallet

Let users connect their own Zorveus wallet when their included credits run out.

Was this page helpful?

Edit this page on GitHub

Business Quickstart