On this page
01
What you'll set up
By the end of this guide you will know how to point a policy at exactly the traffic it should govern, predict which policy wins when several match, and check your answer before it matters.
- A binding scoped to a team, app, environment, or key
- A clear picture of how overlapping bindings resolve
- A company-wide floor that teams can add to but not loosen
02
Bindings in one minute
A binding connects a policy to traffic. The console binds by app, team, or key, with an optional environment. Terraform and the API accept every field below, and an empty field matches any value.
| Field | Matches | Example |
|---|---|---|
| Team | The team label on the request or key | analytics |
| App | The app label | customer-copilot |
| Environment | The environment label | production |
| Caller type (API and Terraform) | A person or a service | service |
| Key (principal) | One specific key | The billing-agent key |
Through Terraform or the API, a binding with only an environment of production covers every team and app in production. A binding with a team, an app, and an environment covers one thing precisely.
03
Create a binding
Bind from the policy form, or from the bindings list in AI → Policies.
- 1
Choose the policy to bind
Open it from the Policies tab.
- 2
Choose the binding type
Choose App, Team, or Key. Use a team for team-wide rules, an app for app rules, and a key for one integration.
- 3
Fill in the target and an optional environment
Enter the app or team, or select the virtual key. Add an environment such as production to narrow the binding further.
- 4
Leave priority alone
The default is right unless two bindings cover the same traffic and you need to override the usual order.
- 5
Save
The binding takes effect at once.
- 2Binding type
- AppTeamKey
- 3App ID
- support-chatbot
- 3Environment
- production
Optional. Only match one environment when needed.
- 4Binding priority
- 100
Optional. Lower numbers win when multiple bindings overlap.
04
Which policy wins
When more than one binding matches a request, the gateway decides in a fixed order.
- 1
Lowest priority number
A binding with priority 10 beats one with the default priority.
- 2
Most specific scope
A specific key ranks highest, then caller type, then team, then app, then environment.
- 3
Newest binding
If everything else ties, the most recently created binding wins.
A worked example
You have three bindings: production for the whole company, team research in production, and the billing-agent key. A request from the billing-agent key, which belongs to the research team, matches all three. With default priorities the key-level binding is the most specific, so its policy is the one that governs the request.
05
Keys, labels, and headers
A virtual key can carry its own team, app, environment, and policy. For a key, those values decide which policy applies.
Headers such as x-cloptima-team and x-cloptima-app label usage for reporting and fill in anything the key does not set. A caller cannot use them to move a key onto a different policy.
06
When two bindings overlap
If a new binding overlaps another and either one uses a custom priority, the console stops you and shows which binding would win.
Read the result, then acknowledge it if it is what you intend. The acknowledgement is recorded in the audit log along with the bindings it overlapped, so the decision has an owner.
07
A floor that teams cannot loosen
Some limits combine across every matching policy in Enforce mode. This lets one company-wide policy set a floor that holds even when a team writes its own.
| What combines | How |
|---|---|
| Request size, tool calls, retries, loop depth | The strictest limit across all matching enforcing policies |
| Request and token rate limits | The strictest limit |
| Daily and monthly budgets | The strictest limit |
| Denied tools and tool servers | Every deny list is honored |
08
Patterns that work
These setups cover most organizations.
| Pattern | Binding | Policy |
|---|---|---|
| Company floor | Environment: production (Terraform or API) | Allowed models, a daily budget |
| Team room to experiment | Team: research, environment: sandbox | More models, a low daily budget |
| Tight integration | Key: billing-agent | A short tool allow list and a small output cap |
09
Check your work
Use the Request Simulator with the key you want to test. It uses the same team, app, environment, and policy settings as a live request.
- 1
Pick the key
Choose the key whose traffic you want to check.
- 2
Enter the model
Use the model the app sends, and add the team, app, and environment if the key does not carry them.
- 3
Read the result
It shows whether the request would pass and which rule applied.
| What you see | Likely cause | Fix |
|---|---|---|
| The wrong policy applies | A more specific or higher-priority binding matches | Narrow a scope or adjust priority |
| policy_not_configured | No binding matches | Add a binding for the key, app, or team |
| A limit is stricter than the policy shows | Another enforcing policy matches too | Check the other policies bound to the same traffic |