Conditions

Roles and resource patterns answer "who may do what, on which things". Real rules often depend on the situation too: only from an MFA-verified session, only on documents you own, only until the end of the audit, only after accepting the terms of use. A condition adds such a test to a policy statement, and the statement applies only when every condition holds.

Each condition compares one key of the request context with the values you list. The context is a set of facts the server assembles for every decision from trusted sources: about the principal (the person or service account making the request), such as principal.mfa; about the resource, such as resource.ownerId; and about the request, such as request.time.

{
  "effect": "allow",
  "actions": ["documents:write"],
  "resources": ["document/*"],
  "conditions": {
    "Bool": { "principal.mfa": true },
    "StringEquals": { "principal.kind": "user", "resource.classification": ["internal", "public"] }
  }
}

This statement applies to MFA-verified people, on documents classified internal or public. The keys of conditions are operators (Bool, StringEquals), each operator maps context keys to the expected values, and a key can list several values.

Change resource.classification to secret, or principal.mfa to false, and the statement stops applying. With no other statement allowing the write, the decision becomes an implicit deny.

How conditions combine

A few rules decide how several conditions, keys, and values add up:

• Operators and keys are ANDed. Every operator in conditions, and every key under each operator, must hold.
• Listed values are ORed. A key with several values holds when any of them matches.
• Except for negated operators and ArrayContainsAll, which must hold for every listed value: StringNotEquals with ["secret", "restricted"] means "neither secret nor restricted".
• Types are strict. A missing or wrongly typed context value never satisfies an operator, including the negated ones. StringNotEquals on an absent key is false, not vacuously true. Use Exists to test absence.
• Invalid syntax is rejected early. Unknown operators and values of the wrong type fail with INVALID_POLICY when a policy is created or updated.

Operators

Better IAM supports 21 operators, grouped by the kind of value they compare. Every operator accepts one value or a list of up to 64 values per key.

Text

Use the string operators for identifiers, names, and labels: the kind of account, a department, a classification. The IgnoreCase variants help with values people type, and the Like variants accept * and ? wildcards.

The values of the string operators may contain policy variables, such as "${principal.id}"; see Policy variables.

Yes or no

Use Bool for flags: whether the session used MFA, whether the person is an owner, whether a project is archived.

Numbers

Use the numeric operators for amounts, levels, and counts: an invoice total, a clearance level, how many required agreements are still owed.

Dates and times

Use the date operators to make access start or end at a fixed moment, usually by testing request.time.

Network addresses

Use the IP operators to allow or block networks, such as an office range or a VPN. The server puts the caller's address in request.sourceIp when it knows it (see Resource and request keys).

Lists

Some context keys hold lists: the groups a person belongs to, their roles, the relations they hold on a resource. Use the array operators for them; the string operators never match a list.

The values listed for ArrayContains and ArrayContainsAll may contain policy variables too.

Presence

Use Exists to test whether a key is there at all, which matters because a missing key fails every other operator (see Missing keys).

Negated operators

"Not equal to secret" sounds like it should hold for a document with no classification at all. In Better IAM it does not, and that is deliberate: a negated test on a missing or malformed value would otherwise quietly let requests through. The negated operators are StringNotEquals, StringNotEqualsIgnoreCase, StringNotLike, NumericNotEquals, and NotIpAddress. A negated operator only negates a comparison that could have succeeded, so the context value must first have the operator's type:

If it is not (missing, a list, a number where a string is expected, text that is not an address), the condition is false: an allow with NotIpAddress does not apply to a malformed address, and neither does a deny.

Missing keys

A key that is absent from the context never satisfies any operator except Exists. For allow statements this is the safe direction: the statement simply does not apply. For deny statements it is a trap, because the deny also does not apply.

This pair of statements keeps payments to the finance department, including for people with no department set:

[
  {
    "sid": "OnlyFinance",
    "effect": "deny",
    "actions": ["payments:*"],
    "resources": ["*"],
    "conditions": { "StringNotEquals": { "principal.department": "finance" } }
  },
  {
    "sid": "OnlyFinanceWhenUnset",
    "effect": "deny",
    "actions": ["payments:*"],
    "resources": ["*"],
    "conditions": { "Exists": { "principal.department": false } }
  }
]

The request has no principal.department, so OnlyFinance does not apply and OnlyFinanceWhenUnset denies it. Remove the second deny in the playground and the payment is allowed, which is exactly the gap the guard closes.

analysis.lintPolicy reports such denies as optional-key-deny.

Value formats

Because types are strict, a value in the wrong format never matches. These are the formats each family expects, both in your policy and in the context:

• Timestamps for DateBefore and DateAfter are ISO 8601 with seconds and a zone: 2026-09-22T09:30:00Z, optionally with one to three fractional digits (.250) or an offset (+02:00) instead of Z. Impossible calendar dates such as February 31 are rejected in policies and never match in the context. request.time is always in this format.
• Numbers must be finite. A string of digits, such as "3", does not match a numeric operator.
• IP addresses and networks are IPv4 dotted decimal or IPv6 (with :: compression or an embedded IPv4 suffix), optionally with a /prefix. Zone IDs (%eth0) and brackets are not accepted. Across families, an IPv4-mapped IPv6 address (::ffff:198.51.100.7) stands for its IPv4 address, so how a dual-stack listener spells a client can neither sidestep a block nor get an allowed office refused.
• Globs in StringLike, StringNotLike, and StringLikeIgnoreCase work like resource patterns: anchored, with * and ? as the only wildcards.
• Array membership is exact: ArrayContains with 3 does not match an array holding "3".

DateBefore and DateAfter compare absolute instants. For recurring hours, such as weekdays from 9 to 5, use an access window on the binding instead; see Access windows.

Context keys

A condition can only test what is in the context, so this list is the vocabulary of your conditions. The server builds the context for every decision from trusted sources: the session, stored identity records, the resolved resource, and your own callbacks. Nothing comes from the browser, so a caller cannot claim to be an owner or to have used MFA.

Principal keys

These describe who is calling and how they signed in.

The session itself adds a second set of keys. They let a policy ask how fresh a sign-in is ("MFA within the last hour"), or who a temporary session was issued to:

Resource and request keys

These describe the thing being acted on, the caller's relation to it, and when the request happens.

Tenant keys

The server never sets resource.type or resource.id (match them in the resource pattern instead), nor principal.email, principal.name, or principal.managerId (declare an identity attribute if a policy needs one). The linter flags these as unknown-context-key.

Application keys

Some rules depend on your own data, such as the customer's billing plan or whether their seats are used up. resolveContext, on the server options or on a plugin, adds such server-derived values to the context. It receives the authenticated principal and returns a map of keys, and it runs for every decision, so keep it fast:

export const iam = betterIam({
  // ...
  async resolveContext(principal) {
    const account = await billing.accountFor(principal.session.tenantId);
    return { 'app.plan': account.plan, 'app.seatsExceeded': account.seatsUsed > account.seats };
  },
});

{ "effect": "deny", "actions": ["reports:export"], "resources": ["*"], "conditions": { "StringEquals": { "app.plan": "free" } } }

Precedence runs from least to most trusted: the application's resolveContext, then plugins, then declared identity attributes, and finally the server-derived principal and request keys, which always win. Resource keys are set from the resolved resource. Neither callback may trust arbitrary browser attributes.

For network rules, test request.sourceIp. It is optional: a request whose address the server did not see (a server-side call without client details, or a simulation) has no such key, so pair a network deny with an Exists guard as shown in Missing keys.

Special sessions

A few kinds of session see a different context, which matters when a condition behaves unexpectedly for them:

• Role sessions, created by role assumption, carry only the assumed role: principal.roles holds the role, principal.groups is empty, principal.owner and principal.rootAdmin are false, no relations apply, and there are no agreements. principal.authMethod is absent, while principal.mfa, principal.authTime, and principal.mfaTime carry over from the session that assumed the role. principal.sourceTenantId names the caller's own tenant, and the caller's declared identity attributes are included unless the trust withholds them.
• Impersonation sets principal.impersonated and principal.impersonatorId, and the decision is also checked against the administrator's own rights.
• Simulations and reviews evaluate an identity in a synthetic session: principal.sessionKind is user for people and api-key for service accounts, principal.authMethod is absent, and principal.mfa is false unless you pass assumeMfa: true. principal.sessionId is simulation, principal.authTime is the moment of evaluation, and there are no session tags. principal.mfaTime and request.sourceIp are always absent, even with assumeMfa, so a condition that requires recent MFA or a particular network never holds in a simulation.

Common conditions

These statements solve problems that come up in most applications. Add them to a role, or to a policy attached to a role everyone holds.

{ "effect": "deny", "actions": ["iam:*"], "resources": ["*"], "conditions": { "Bool": { "principal.mfa": false } } }

principal.mfa is always present, so this deny is safe without an Exists guard. It also blocks API keys, which are never MFA-verified; exclude them with a StringEquals on principal.kind if integrations administer the tenant.

{
  "effect": "deny",
  "actions": ["documents:*"],
  "resources": ["*"],
  "conditions": { "NumericGreaterThan": { "principal.pendingAgreements": 0 } }
}

{
  "effect": "allow",
  "actions": ["beta:use"],
  "resources": ["*"],
  "conditions": { "ArrayContains": { "principal.agreements": ["Beta program"] } }
}

{ "effect": "deny", "actions": ["*:delete"], "resources": ["*"], "conditions": { "Bool": { "principal.impersonated": true } } }

{
  "effect": "allow",
  "actions": ["audit-workspace:read"],
  "resources": ["*"],
  "conditions": { "DateBefore": { "request.time": "2026-12-31T23:59:59Z" } }
}

Try any of these in the policy playground with your own context values.

Next steps