On this page
01
What you'll set up
In about ten minutes you will have a policy that limits which models an app can use, how large its requests can be, and how much it can spend per day. You will test it before any live traffic is affected.
- A policy in Monitor only mode, so nothing is blocked while you tune it
- Model access, size limits, and a rate limit that fit your app
- A daily budget with the enforcement style you choose
- A tested path from a simulated request to a real one
You will need an owner or admin role in your organization, an AI plan (policy enforcement is part of the AI plans), and a virtual key for the app you want to govern. Virtual keys are in AI → Credentials & Keys.
02
How a policy fits together
Every request goes through the same checks in the same order. Knowing the order helps you decide where each limit belongs.
1Identify the caller
Key, team, app
2Find the policy
Most specific binding wins
3Check the rules
Models, tools, size, rates
4Protect the content
Guardrails
5Reuse or route
Cache, then the right provider
6Reserve budget
Hold spend before the call
7Call the provider
A policy supplies the rules for steps two to six. If a request breaks a rule in an enforcing policy, it stops there, and the provider never sees it.
03
Create the policy
Open AI → Policies and choose Govern a new app. You name the app, and Cloptima creates its policy, binds the policy to the app, and gives you the app's key.
- 1
Choose Govern a new app
You will find it at the top of the Policies tab.
- 2
Name the app
A name like support-app tells a reviewer what the policy covers. The policy and the key take their names from it. Names are 5 to 64 characters.
- 3
Choose Start blank
A template fills every setting for a common workload. Start blank leaves each setting to you, which suits this guide.
- 4
Set Enforcement mode to Monitor only
A blank policy starts on Enforce. Monitor only records activity and blocks nothing, which is the safe way to tune.
- 5
Leave Model access on All models for now
You will narrow it in the next section, once you know which models the app uses.
- 6
Create the key
Choose Next, then Create and get key. Copy the key: the console shows it once.
- 2App or agent name
- support-app
Basics
- 4Enforcement mode
- EnforceMonitor only
- 5Model access
- All modelsClaudeOpenAIGeminiCustom
04
Choose what is allowed
Start with the models and providers your teams already use. Choose Custom under Model access to set them. Allow lists and deny lists accept wildcards, and a deny always wins over an allow.
| Field | Example | Notes |
|---|---|---|
| Allowed providers | openai, anthropic | Leave on All to allow any provider |
| Allowed models | gpt-5.4-mini, claude-* | A wildcard matches a family of models |
| Denied models | gpt-4-* | Checked first. A deny beats any allow. |
05
Add limits that match the app
Limits protect you from the unexpected: an oversized prompt, a long answer, a noisy caller, an agent that loops. Pick starting values from how the app behaves today.
| Limit | A reasonable start | Protects against |
|---|---|---|
| Max input tokens | Twice your largest normal prompt | A huge prompt sent by accident |
| Max output tokens | What your interface can actually show | Long, expensive answers |
| Request rate per minute | Twice your normal peak | A noisy caller or a retry storm |
| Max tool calls and loop iterations | A small number, such as 10 | An agent that loops on itself |
06
Set a budget
Add a daily budget, a monthly budget, or both. The monthly budget is in Basics; the daily budget and At the budget, which decides what happens at the limit, are in Limits. The budget is shared by every app, team, and key bound to the policy.
| At the budget | What it does | Use it when |
|---|---|---|
| Alert only (never blocks) | Tracks spend and never stops traffic | You are learning what normal looks like |
| Block at the budget | Refuses requests before they reach the provider once the budget is used | You want a hard stop at the limit |
07
When a check cannot run
If one of Cloptima's own checks cannot complete, such as a rate-limit lookup, the request continues on the checks that did run. A guardrail scan does the same, unless its profile is set to block. Requests on Cloptima credits wait for their budget decision.
Your own provider keys
- The request continues on the checks that did run
- Only a guardrail profile you set to block stops it
Cloptima credits
- The request waits for its budget decision
- No credit is spent without one
08
Check the binding and send a test request
A policy only applies where it is bound. The new app's policy is already bound to the app. The second guide covers other bindings and how the gateway chooses between several.
- 1
Check the binding
Open the policy. Its Bindings list shows the app. Add a binding there to cover another app, a team, or a key.
- 2
Open the Request Simulator
It is in the Policies tab. Enter a model and, optionally, the key, team, app, and environment. It reports which policy applies and whether the request would be allowed.
- 3
Send a real request
Use the virtual key. If the key does not carry a team and app, add them as headers.
curl https://api.cloptima.ai/v1/ai/chat/completions \
-H "Authorization: Bearer $CLOPTIMA_VIRTUAL_KEY" \
-H "X-Cloptima-Team: support" \
-H "X-Cloptima-App: support-assistant" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "Say hello"}]}'- 2Model
- gpt-5.4-mini
- 2Virtual Key (optional)
- No key (policy default)
- 2Team ID
- support
- 2App ID
- support-assistant
- 2Environment
- production
Simulation result
| Request | openai/gpt-5.4-mini · Would be allowed |
| Matched policy | support-app-production · observe |
| Model check | Allowed |
| Credential | Platform managed credits |
09
Switch to Enforce and break it on purpose
When the simulator and your usage look right, change Mode to Enforce. Then confirm the policy actually blocks what it should.
- 1
Switch Mode to Enforce
Do this on a policy bound to one app first.
- 2
Send a request with a model you did not allow
Use a model that is on your deny list or not on the allow list.
- 3
Read the response
You should see HTTP 403 with a reason that names the rule.
{
"error": "Your AI request was blocked because this model is not allowed by the active Cloptima policy.",
"reason": "model_not_allowed",
"violations": ["model_not_allowed"]
}10
If something goes wrong
Most first-policy problems come down to a binding or a mode. This table covers the common ones.
| What you see | Likely cause | Fix |
|---|---|---|
| 403 policy_not_configured | No binding matches the caller | Bind the policy to the key, app, or team |
| 403 model_not_allowed | The model is not on the allow list | Allow the model, or use one that is allowed |
| 400 Managed AI requests require Cloptima team and app attribution | The request has no team or app | Set them on the key, or send the x-cloptima-team and x-cloptima-app headers |
| 429 request_rate_limit_exceeded | The per-minute rate limit was reached | Retry shortly, or raise the limit |
| The policy seems ignored | It is in Monitor only mode, or bound to a different scope | Check Mode and the binding |