Docs

Your agents keep the SDK they use. Each gets its own DORET Prism key and calls the gateway instead of the provider; the gateway checks the call against the agent's, its group's and the organization's budgets before it runs.

Quick start

Create an organization and connect a provider under Integrations. The provider key stays with DORET Prism, encrypted; agents never see it.
Create an agent and copy its key (aib_live_…). Your gateway address is on the Developers page; it replaces https://YOUR-GATEWAY below.
Point the SDK at the gateway. Nothing else in the agent changes.

TypeScript, Anthropic SDK

import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ apiKey: process.env.AIB_AGENT_KEY, // aib_live_… baseURL: "https://YOUR-GATEWAY/gw/anthropic", }); const msg = await client.messages.create({ model: "claude-sonnet-5-5", max_tokens: 2000, // caps output; input is bounded too messages: [{ role: "user", content: "Summarize this ticket…" }], }, { headers: { "Idempotency-Key": crypto.randomUUID(), "X-AIB-Task-Id": "ticket-4182" } });

Python, OpenAI SDK

from openai import OpenAI client = OpenAI( api_key=os.environ["AIB_AGENT_KEY"], # aib_live_… base_url="https://YOUR-GATEWAY/gw/openai/v1", ) resp = client.chat.completions.create( model="gpt-5-mini", max_completion_tokens=1000, # injected from policy if omitted messages=[{"role": "user", "content": "Classify this ticket…"}], extra_headers={"Idempotency-Key": str(uuid.uuid4())}, )

curl

curl https://YOUR-GATEWAY/gw/anthropic/v1/messages \ -H "Authorization: Bearer $AIB_AGENT_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"model":"claude-haiku-5-5","max_tokens":500, "messages":[{"role":"user","content":"Hello"}]}'

Read-only mode

To see what you spend before changing any code, connect only a usage key in Integrations → Read-only: an OpenAI organization admin key (sk-admin-…) or an Anthropic Admin API key (sk-ant-admin01-…). Every three hours DORET Prism reads the provider's usage report for text models and prices the tokens at list price: spend by day and model, and this month against your organization's monthly limit. If you set one, Owners, Admins and Finance are warned at your level and at 100% (by email once email is set up, and by Slack if connected). Models without a built-in price are listed but not counted. The key is an admin key at the provider; DORET Prism uses it only to read usage and stores it encrypted.

Spend by client. DORET Prism reads the report split by OpenAI project or Anthropic workspace and by API key, with the names you gave them. On the overview, Assign keys attributes each key or project to a group (one per client); a key counts for its own client, and a key with none counts for its project's. Each client then shows what its keys spent at the provider and what its agents spent through the gateway, for this month and the last.

The reports say which project or key spent, not which request, so attribution is only as fine as your setup: a client with its own key or project is counted exactly, while spend from a key several clients share cannot be split. For exact per-client numbers, give each client its own key or project, or send its calls through the gateway under its group (and a task tag for finer detail).

Providers publish usage hours late, so read-only mode can tell you, not stop anything. To have calls refused before they go over a limit, connect the provider's API key and send calls through the gateway (the Quick start). Without a scope the key reads the whole provider organization; with one (a project, API key or workspace) it also reconciles the gateway's own calls.

Providers

An Owner connects a provider in Integrations with an API key from the provider's console. Use a key made only for DORET Prism, so you can revoke it on its own. Saving checks the key with a free call that lists models; the key is stored encrypted and agents never see it.

OpenAI, Anthropic: Prices are built in. On Business, add an admin key with a scope for reconciliation: every few hours DORET Prism compares its records with the provider's usage report and settles calls whose outcome was unknown. It uses the key only to read usage.
Gemini, Mistral, xAI, DeepSeek, Groq, Together AI, Fireworks AI, OpenRouter: Called through their OpenAI-compatible API. After connecting, an Owner adds each model you use with its price per million tokens; calls to a model without a price are refused, so nothing runs uncapped.
Azure OpenAI, your own server: Give the https base URL as well. It must be reachable from the internet; private and local addresses are refused.

Budgets, groups and policies

Every call passes three budgets: the agent's, its group's if it has one, and the organization's. Each can have a daily and a monthly limit, and an agent can also have a per-call limit. A call runs only if all of them can cover its worst-case cost; days and months follow the organization's time zone (Settings).

Groups are teams or clients: their agents share the group's budget, and a Manager assigned to the group approves its requests.
Temporary increases add a one-time amount on top of a limit for a few hours, from an approved request or by hand in Budgets. They expire on their own.
The policy (Owner only, in Policies) sets the allowed models, default and maximum output tokens, the request rate per agent, when to warn, and the approval rules below. Each change is a new version; old versions stay in the audit log.

Requests and approvals

When an agent asks for more, the request appears in Requests with its reason, the amount, how long it lasts and what it would do to every budget on its path. The policy's approval thresholds name the least senior role that may decide, by amount. By default:

Up to $100: Manager of the agent's group, or anyone more senior.
Up to $1,000: Finance or Admin, or the Owner.
Above $1,000: The Owner.
Automatic: Business and up, off by default. The Owner can allow it in Policies, up to an amount and a duration per request, a number of increases per agent per month and a daily cap for the organization.

An approver can grant less than asked or for fewer hours, and add a note. Pending requests expire after the time set in the policy. Every decision, by a person or by the policy, is in the audit log.

Base URLs

One per provider. OpenAI-compatible providers use the OpenAI SDK with their own path.

Provider	Base URL	SDK and APIs
OpenAI	https://YOUR-GATEWAY/gw/openai/v1	Chat Completions and Responses, OpenAI SDK
Anthropic	https://YOUR-GATEWAY/gw/anthropic	Messages API, Anthropic SDK
Google Gemini, Mistral, xAI, DeepSeek, Groq, Together AI, Fireworks AI, OpenRouter, Azure OpenAI, your own server	https://YOUR-GATEWAY/gw/<provider>/v1	Chat Completions, OpenAI SDK

Streaming works on every provider. OpenAI and Anthropic are priced by DORET Prism; for the others an Owner sets each model's price, because a call is let through only when its cost can be capped.

Headers

Authorization: Bearer aib_live_…, the agent's key. Anthropic's x-api-key works too.
Idempotency-Key: Optional. A retry with the same key never calls the provider twice.
X-AIB-Task-Id: Optional. Tags the call with a task, shown in transactions.

Every answer carries X-AIB-Transaction-Id and X-AIB-Reserved-Usd, the worst case held before the call. Non-streaming answers add X-AIB-Cost-Usd; streams end with an SSE comment : aib-cost {…}.

Errors

In the provider's own error format, so its SDK raises as usual, with an aib object added. Refusals and unknown outcomes carry x-should-retry: false, so SDKs do not retry them and an unanswered call is never charged twice.

Status	Type	Meaning
401	invalid_agent_key	Unknown or revoked key.
402	budget_exceeded	A limit on the call's path cannot cover its worst-case cost. The aib object names the blocking budget, the window and the largest call that would still fit.
403	model_not_allowed / agent_suspended	The policy or the agent's allow-list refuses the model, or the agent is suspended.
409	idempotency_conflict / in_progress / already_completed	The Idempotency-Key was reused. The provider is never called twice.
409	provider_not_connected	The organization has not connected this provider.
422	cap_not_guaranteed	The cost cannot be capped in advance (see what the gateway refuses).
429	rate_limited	Per-agent request rate from the policy.
502	provider_error	The provider failed before generating. Nothing was charged.
504	outcome_unknown	The provider did not answer. The reservation is held until reconciliation.

HTTP 402 budget_exceeded { "error": { "type": "budget_exceeded", "message": "Agent daily limit cannot cover this request.", "aib": { "blocking_account": "agent:agt_…", "window": "day", "limit_usd": "5.000000", "remaining_usd": "0.009900", "required_usd": "0.020200", "request_budget_url": "/v1/agent/budget-requests", "transaction_id": "txn_…" } } }

Asking for more budget

After a 402, an agent can ask for a temporary increase with the amount, the time and the reason. The organization's policy names who may approve it; on Business, small requests can be approved automatically within limits set in advance.

POST https://YOUR-GATEWAY/v1/agent/budget-requests Authorization: Bearer aib_live_… Idempotency-Key: 3f6c… { "amount_usd": "25.00", "purpose": "Finish competitor pricing report", "justification": "Daily budget ran out after 140 of 400 pages", "expected_outcome": "Pricing table for 40 competitors today", "duration_hours": 8 } → 200 { "id": "breq_…", "status": "pending" }

GET /v1/agent/me/budget: Limits, spent, reserved and remaining for today and this month
GET /v1/agent/budget-requests/:id: Status, decision and the granted amount with its expiry
POST /v1/agent/budget-requests/:id/cancel: Withdraw a pending request
Webhook: Set a URL on the agent to receive budget_request.decided, signed with HMAC-SHA256 in AIB-Signature

Agent SDK

Optional helpers, one file each with no dependencies: recognize a 402 from the OpenAI or Anthropic SDK, ask for more budget, wait for the decision, verify webhooks.

doret-agent.ts · TypeScript, any JS runtime budget_agent.py · Python 3.8+

TypeScript

import { AIBankAgent, budgetExceeded } from "./doret-agent"; // one file, no dependencies const bank = new AIBankAgent({ apiKey: process.env.AIB_AGENT_KEY, baseUrl: "https://YOUR-GATEWAY" }); try { await anthropic.messages.create({ … }); } catch (e) { const over = budgetExceeded(e); // works with OpenAI and Anthropic SDK errors if (!over) throw e; const req = await bank.requestBudget({ amountUsd: "5", purpose: "…", justification: "…", expectedOutcome: "…", durationHours: 4 }); const decision = await bank.waitForDecision(req.id); // or receive the webhook }

Python

from budget_agent import BudgetAgent, budget_exceeded # budget_agent.py, one file from anthropic import Anthropic agent = BudgetAgent(api_key=os.environ["AIB_AGENT_KEY"], base_url="https://YOUR-GATEWAY") client = Anthropic(api_key=agent.api_key, base_url=agent.anthropic_base_url) try: client.messages.create(model="claude-sonnet-5-5", max_tokens=2000, messages=[…]) except Exception as e: over = budget_exceeded(e) # works with openai and anthropic SDK errors if not over: raise req = agent.request_budget(amount_usd="5", purpose="…", justification="…", expected_outcome="…", duration_hours=4, idempotency_key="task-42") decision = agent.wait_for_decision(req["id"]) # or receive the webhook

What a call holds

Before each call DORET Prism holds the most it could cost on every budget in its path, so concurrent calls cannot overrun a limit. max_tokens bounds only the output; the rest is bounded separately.

InputEvery token the provider bills as input: messages, system prompt, tool and function schemas, structured-output schemas, and the hidden prompt providers add for tools. Long prompts are counted with the provider's own token counter; short ones are bounded by their size.

Outputmax_tokens (or the policy default when it is missing), times n when several choices are requested. Reasoning and thinking tokens are billed as output and, for OpenAI and Anthropic, fall inside the same cap. Some OpenAI-compatible providers bill reasoning outside max_tokens. For those models an Owner sets a reasoning allowance with the price, and every call holds it too. Without one, a call can cost more than its hold: the overrun is charged, marked Overrun, Owners, Admins and Finance are told, and once the limit is used up the next call is refused.

Prompt cachingIf a request asks for caching, its input is held at the cache-write rate (1.25× for 5 minutes, 2× for 1 hour), the highest it could be billed. Cache reads only make the real cost lower.

Long contextIf the input could cross a model's long-context threshold, the whole call is held at the higher long-context rates.

After the callThe provider's reported usage settles the charge and the rest goes back to the budget. If the outcome is unknown, the full hold stays charged until the real cost is settled: from OpenAI's or Anthropic's usage report with a scoped admin key (Business), or by an Owner, Admin or Finance member working from the provider's console.

What is refused

Calls whose cost cannot be capped before they run get 422 cap_not_guaranteed:

Output caps above the policy ceiling
Images, audio and files (text only for now)
Built-in tools with per-call fees (web search, code execution)
Server-side conversation state (previous_response_id)
Priority tiers and fast mode
Models without a price
MCP servers, containers and other provider-side execution
Predicted outputs (rejected predictions bill beyond the cap)

Troubleshooting

401 invalid_agent_key: The SDK still sends the provider's key, or the agent key was revoked. Use the aib_live_… key from the agent's page; issue a new one there if it was lost.
402 budget_exceeded: The error names the budget and the window that stopped the call and how much is left. Raise that limit in Budgets, wait for the window to reset, or have the agent ask for a temporary increase.
403 model_not_allowed: The model is not in the policy's allowed list or the agent's own list. Add it in Policies (Owner) or on the agent.
409 provider_not_connected: Connect that provider in Integrations.
422 cap_not_guaranteed: The call's cost cannot be capped before it runs: for example no max_tokens and no default, a model without a price, or a feature billed outside the token count. See what is refused above.
429 rate_limited: The agent exceeded the requests per second set in the policy.
502 / 504: The provider failed or did not answer. A 504 call stays charged at its full reservation until it is settled: from OpenAI's or Anthropic's usage report with a scoped admin key (Business), or by an Owner, Admin or Finance member on the transaction.
Calls do not show up: Check the SDK's base URL: it must be the gateway address on the Developers page, not the provider's.
No emails arrive: Check the spam folder and that the address is confirmed (a banner says so). Owners and Admins can also make a password reset link for a teammate in Settings.

FAQ

Does DORET Prism pay the providers?: No. You pay them directly, as today. DORET Prism holds no funds; budgets are limits on what your agents may spend.
Does it see our prompts?: They pass through and are not stored. A transaction keeps the model, tokens, cost and status; for a call the provider rejects, the first 200 characters of its error, which can quote the request.
What happens if DORET Prism is down?: Calls through the gateway fail rather than run unchecked.
How much latency does it add?: In our internal load tests the budget check took about 3 ms per call (p95), a measurement and not a guarantee; in production add the network hop to the gateway. Streaming is passed through as it arrives.
Can an agent call the provider directly?: Only if it holds a provider key. Keep provider keys in DORET Prism and give agents only their gateway key.
Can we export the data?: On Startup and up, transactions (up to 100,000 per export) and the audit log export as CSV, and on Business monthly statements too. On any plan, write to us for a copy of your data.

Support

In the dashboard, Help in the side menu opens an email with your organization's id and the page you were on already filled in, so we can look into it without any keys. Never send provider keys or agent keys to support: we never need them.