System architecture
Understand how your application, Zorveus, model providers, and user allowances fit together.
Zorveus sits between your application and AI model providers. Your application sends model requests to Zorveus. Zorveus checks access and spending rules, routes each request, and records usage against your app and, when attributed, your customer.
You configure the rules in the dashboard. Your application does not need to build its own provider routing or per-user AI spend accounting.
The system at a glance
- Your application backendSends a model request with a Zorveus API key and your customer’s external user ID.
- ZorveusChecks access, attribution, allowance, and funding. Routes the request and records usage.
- Model providerRuns the model. The response returns through Zorveus to your application.
The three paths have different jobs:
| Path | What you do | Credential |
|---|---|---|
| Dashboard setup | Configure apps, connections, keys, caps, provider credentials, and webhooks | Dashboard sign-in |
| Inference | Send chat, media, embedding, or other supported model requests | API key, zrv_... |
| Product-user management | Read allowance, update customer details, or grant credits through supported /product-users/by-external-id routes | Server-only service key, zrv_svc_... |
Service keys do not configure apps, connections, caps, provider credentials, or webhooks. Use the dashboard for those operations.
The core concepts, with one example
Imagine you are adding AI to a customer-support product called Acme Support. Acme pays for inference and wants to track each customer's usage.
| Concept | Meaning | Acme Support example |
|---|---|---|
| Organization | The workspace that owns funding, credentials, and access | Acme's Business organization |
| App | The identity of the product you integrate | Acme Support |
| App connection | Links an app to its funding organization and request policies | A connection with models and spending rules for your Pro tier |
| API key | Authenticates inference under a connection | The key Acme's backend selects for a Pro customer |
| Product user | Your customer, identified by your existing user ID | cus_123, not a dashboard team member |
| Model | The model identifier your request asks Zorveus to run | A model selected from the model catalog |
| Provider credential | Upstream provider credentials for Bring Your Own Key routing | Acme's OpenAI credentials, saved in the dashboard |
| Wallet | Funds that pay for wallet-routed inference and applicable platform fees | Acme's organization wallet |
| Cap and credits | Rules that determine a customer's available AI allowance | A monthly base allowance, plus a purchased credit grant |
An app is not an API key. A connection holds the policies; the API key authenticates requests under that connection. You can rotate the key without creating a different product identity.
Attribute requests to your customer
Send your customer ID on every attributed request, using either the X-Zorveus-External-User-ID header or metadata.external_user_id in the body. Either creates the product user on their first request. You do not need to pre-register them.
Use the same identifier across inference and product-user management calls. Your backend selects the connection's API key for the customer's plan and supplies the customer ID for attribution.
Separate allowance from funding
Allowance answers “How much AI usage may this customer consume?” Funding answers “Who pays for that usage?”
For a capped product user, available allowance combines the remaining base allowance and eligible product-user credits. Credit grants extend that allowance. They do not deposit money into your organization wallet or pay a model provider.
With wallet-funded routing, the organization wallet pays Zorveus for inference. With BYOK, the upstream provider bills your provider account. Applicable Zorveus platform fees use your organization wallet.
A customer can have allowance left while the organization lacks funding. The reverse can also happen. See Funding and billing and Caps and credits.
Follow one request
Acme's customer cus_123 asks the support assistant a question:
- Acme's backend selects the Zorveus API key configured for the customer's plan.
- The backend sends the model request and the customer's external user ID.
- Zorveus authenticates the key, resolves its connection, and attributes the request to the product user.
- Zorveus checks model access, applicable caps, credit mode, and available funding. Enforcement depends on the connection's settings.
- For wallet-funded requests, Zorveus reserves an estimated charge before provider work. BYOK uses an eligible provider credential and checks applicable funding requirements.
- The provider runs the model. Zorveus returns the response, including streamed output when requested.
- Zorveus records actual usage, settles charges, and releases unused reservations.
Streaming changes how output reaches your app, not the spending rules. Interrupted requests can require later release or reconciliation of reservations.
Your backend can check available allowance before accepting work. That check is a snapshot, not a reservation. Zorveus still checks the actual inference request. Webhooks notify your backend of supported events, such as a product user reaching a cap.
Choose where to start
If your company pays for customers' AI usage, start with Integrate your product. Configure a Business organization, app, connection, and API key in the dashboard. Fund the wallet or add provider credentials, then make an attributed request.
If users connect their own Zorveus accounts to your tool, start with the OAuth app quickstart. OAuth consent creates the connection to the user's funding context.
For more detail, continue with Organizations, Apps, connections, and keys, and Models and routing.