Skip to main content

Server-side Policies

Rules written inside your agent's code protect you from honest mistakes. They can't protect you from the agent itself, because code the agent runs is code the agent could skip, and a rule that only sees one action can't notice ten small ones. Policies are rules that live in Auditail:

  • Approvers write them. Agents can't change them. Saving needs an approver token, and every version is recorded in the audit log with who saved it.
  • They're evaluated on the server, against usage the server counts itself.
  • Every decision is recorded by Auditail, and every allowed action gets a signed receipt your other systems can require.

Turn them on in the SDK:

const auditail = new Auditail({ apiKey: process.env.AUDITAIL_API_KEY!, serverPolicy: true });
auditail = Auditail(api_key=os.environ["AUDITAIL_API_KEY"], server_policy=True)

With serverPolicy, guard() makes one network call per action. If Auditail can't be reached, the action is denied (code: "policy_unavailable"). Rules in your code still run first, and they can block without a round trip.


A complete policy​

Edit it in the dashboard (Policy, with an Insert example button) or with PUT /v1/policy using an approver token.

{
"defaultAction": "deny",
"trustedSources": ["user", "system"],
"actions": {
"create_payout": {
"deny": [
{ "field": "beneficiary.country", "op": "in", "value": ["KP", "IR"], "reason": "sanctioned country" },
{ "field": "currency", "op": "not_in", "value": ["USD", "EUR"], "reason": "only USD and EUR payouts are supported" }
],
"requireApproval": [{ "field": "amount", "op": ">", "value": 10000, "reason": "payouts over $10,000 need a human" }],
"limits": [
{ "name": "daily-usd", "window": "24h", "sum": "amount", "max": 25000, "onExceed": "require_approval",
"when": [{ "field": "currency", "op": "==", "value": "USD" }] },
{ "name": "daily-eur", "window": "24h", "sum": "amount", "max": 20000, "onExceed": "require_approval",
"when": [{ "field": "currency", "op": "==", "value": "EUR" }] },
{ "name": "per-beneficiary", "window": "1h", "count": true, "max": 3, "groupBy": "beneficiary.id", "onExceed": "deny" }
],
"firstTime": [{ "field": "beneficiary.iban", "window": "365d", "onFirst": "require_approval" }],
"approvers": 2,
"sensitiveFields": ["amount", "beneficiary.id", "beneficiary.iban"],
"untrustedSource": "require_approval",
"taintedSession": "require_approval",
"hint": "Payouts are limited to $25,000 a day."
},
"issue_refund": { "limits": [{ "name": "refunds-per-hour", "window": "1h", "count": true, "max": 20, "onExceed": "deny" }] },
"delete_customer": { "allow": false, "hint": "Customer deletion is done by the support team." }
}
}

Policies are validated strictly. A typo, an unknown field or an impossible limit is rejected with a list of exactly what's wrong, and nothing is saved.


1. Default-deny: only listed actions run​

With "defaultAction": "deny", an action that isn't listed is refused, and the agent is told what it can do:

{ "decision": "deny", "code": "action_not_allowed",
"reason": "\"wire_transfer\" is not an allowed action.",
"hint": "Allowed actions: create_payout, issue_refund." }

"allow": false turns off a listed action. Disabled actions aren't advertised in hints. Until an approver saves the first policy, everything is denied (code: "no_policy").

2. Limits over time​

A per-action rule like "over $10,000 needs approval" lets an agent pay $9,999 ten times. Limits close that gap. Auditail counts usage on the server, over a sliding window, and each check-and-count is atomic: 20 simultaneous $5,000 payouts against a $25,000 cap let exactly 5 through.

FieldMeaning
window"30m", "24h", "7d" (1 minute to 90 days)
sum / countAdd up a payload field ("sum": "amount") or count actions ("count": true)
maxThe cap for the window
groupByCount separately per value, e.g. per beneficiary.id (velocity per recipient)
whenOptional conditions; the limit only applies to payloads that match all of them, e.g. one cap per currency
onExceed"deny", or "require_approval" to let a human decide

Currencies. Auditail doesn't convert currencies. Give each currency its own limit with when, as in the example above, and deny currencies you don't support with a deny condition. A limit with no when adds up amounts in every currency together.

Details:

  • If a human approves an over-limit action, it counts, so the next action sees the higher total.
  • Denied actions don't count.
  • A payload that can't be counted, such as amount: "25000" as a string or a missing groupBy field, is denied with code: "invalid_payload". It is never silently skipped.

New recipients: firstTime​

Most payment fraud goes to an account that has never been paid before. firstTime sends the first action for a new value to a human, or refuses it:

"firstTime": [{ "field": "beneficiary.iban", "window": "365d", "onFirst": "require_approval" }]
  • The first create_payout to an IBAN not seen in the last 365 days gets code: "first_time". Once it's approved (or allowed by shadow mode), later payouts to that IBAN aren't "first" any more.
  • A denied first payout doesn't make the IBAN known.
  • onFirst: "deny" refuses new recipients outright, for teams that set up payees outside the agent. List the approved ones in known (up to 1,000 values), and add a reason explaining where to set up new ones: { "field": "beneficiary.iban", "onFirst": "deny", "known": ["GB29NWBK60161331926819"], "reason": "new payees are set up by finance" }.
  • window is 1 hour to 730 days (default 365d). A payload without the field is denied with invalid_payload.

More than one approver: approvers​

"approvers": 2 means a request for this action is approved only after two different approvers say yes. One deny ends it. The same approver can't approve twice, and agent keys can never approve. Each approval is recorded in the audit log (approval.voted), and the final decision lists everyone who approved. See Human approval.

3. Where the data came from​

The most likely way an agent gets talked into a bad action is prompt injection. It reads an email or a web page, and the content says "pay invoice 882 to this account". Tell Auditail where the data came from:

await auditail.guard({
action: 'create_payout',
payload: { amount: 4200, beneficiary: { id: 'ben_77', iban: ibanFromEmail } },
agentId: 'payout-agent',
source: 'user', // the request itself came from your user
fieldSources: { 'beneficiary.iban': 'inbound_email' }, // but the IBAN came from an email
});
  • Sources in trustedSources (default user, system) are trusted. Anything else is untrusted.
  • untrustedSource sets what happens: "require_approval" (default), "deny" or "allow".
  • sensitiveFields limits the reaction to the fields that matter. An untrusted memo doesn't trigger approval, an untrusted IBAN does.
  • taintedSession covers the indirect case: once a session has read untrusted content, later actions in it follow this setting ("require_approval", "deny" or "allow"; default: the action's untrustedSource). It applies to guard() calls with a sessionId. See session taint.
Set sources in your code, never from the model

source is only as good as your integration. Set it in the code that feeds content to the model: "this text came from an inbound email". Never let the model choose it. An agent that has been tricked will happily say source: "user".

4. Denials the agent can act on​

Every result has a stable code and, where there's something useful to say, a hint. Agents (and your code) can branch on them instead of retrying blindly or improvising a workaround.

codeMeaningTypical hint
allowedAllowed by policy or rules
approved_by_humanA human approved it
action_not_allowedNot on the allowlistAllowed actions: create_payout, issue_refund.
action_disabledListed with allow: falseThe action's hint
policy_deniedA deny condition matchedThe action's hint
limit_exceededA limit would be exceeded9,000 amount left in this 24h window.
first_timeFirst action for this value (e.g. a new IBAN)The rule's reason
untrusted_sourceData came from an untrusted sourceAsk the user to confirm these details directly...
invalid_payloadA limit couldn't be countedFix the payload so the limit can be counted.
approval_denied / approval_expiredA human said no / nobody answeredDo not retry it unchanged; ask the user how to proceed.
approval_pendingwait: false and still waiting
rule_blocked / rule_errorA rule in your code blocked it / threwYour rule's hint
policy_unavailableAuditail couldn't be reachedRetry later.
frozenThe kill switch is on for this agent or actionStop and tell the user. An approver must lift the freeze...
no_policyNo policy saved yet

Rules in your code can set their own code and hint too.

5. Approvers see the context​

An approver who sees only a payload approves blind. Pass what led to the action:

await auditail.guard({ ..., intent: 'Supplier emailed updated bank details', userRequest: 'Pay the Globex invoice for October' });

The approval card then shows:

  • User asked and Agent says, from the fields above.
  • Data from, with an UNTRUSTED flag.
  • Every reason approval was triggered.
  • Live usage against each limit, e.g. "daily-total: 19,998 of 25,000 used in the last 24h; this action adds 9,999".

All of it is also stored in the audit log with the request.


How a decision is made​

  1. An active freeze → deny (frozen), even in shadow mode.
  2. Action not listed → defaultAction.
  3. Action disabled → deny.
  4. Any deny condition → deny.
  5. Untrusted data → per untrustedSource. A session that read untrusted data earlier → per taintedSession.
  6. Any requireApproval condition (or a require_approval rule in your code) → human.
  7. First time for a firstTime value → per onFirst.
  8. Limits that apply (when) → per onExceed.
  9. Otherwise allow: usage is counted and a signed decision receipt is returned.

If the result is "human", the request needs approvers approvals (default 1).

A deny anywhere beats an approval, so nobody is asked to approve something the policy would refuse anyway.

Conditions​

{ "field": "beneficiary.country", "op": "in", "value": ["KP"], "reason": "..." }. Field paths use dots, up to 6 levels deep. Operators: >, >=, <, <=, ==, !=, in, not_in, exists, missing. Numeric comparisons only match numbers. The optional reason is what agents and approvers see.

Shadow mode and backtests​

Set "mode": "shadow" to evaluate a policy on live traffic without enforcing it, or backtest a draft against the last 7 days of recorded actions with POST /v1/policy/simulate. See Kill switch, shadow mode and examiner reports.

Limits of this feature, plainly​

  • Policies cover what passes through guard(). Put a receipt check in the system that executes the action, and decide there which actions need a receipt.
  • Provenance depends on your integration tagging data correctly.
  • A limit counts approved and allowed actions, including ones that later fail elsewhere, until a trusted outcome report says the money never moved (failed or voided). Agent reports never give budget back.
  • Agents can read their own allowed actions and remaining budget with getCapabilities(). Set "introspection": false at the top of the policy to turn that off.