Skip to main content
Hyperagent
ConceptsAgentsAutonomy

Access policy JSON

Reference for policy documents, rule fields, conditions, and run filters.

Advanced reference

To get started with access policies, follow Control your agent’s actions. Use this reference when you need to edit the JSON directly.

An access policy defines an agent’s permissions through a policy document and its rules. Explore the schema below, or select an example to inspect its JSON.

Policy document

The outer structure: version, mode, rules, and default.

versioninteger · enumRequiredManaged by Hyperagent

Hyperagent maintains the format version and saves the lowest version the policy needs. Keep the provided value; use Draft policy when changing rules requires a different format. Hyperagent lowers the saved version when rules requiring a higher version are removed.

modestring · enumRequired

Sets the broadest permission the policy’s rules may grant. Keep Hyperagent’s saved value unless you intend to change this limit.

Examplewrite
rulesarray<object>Required

The list of rule objects. Add or replace a rule here, preserving the others.

default"deny" · enumRequired

Always deny; any other value fails validation. A write that no rule covers needs approval in a conversation where someone can respond. Otherwise, it cannot proceed.

Exampledeny

Rules

Each rule sets a permission (Allow, Ask, or Deny) for the actions it covers. Narrow that permission to particular apps, destinations, conditions, or thread types.

Rules can cover different thread types and connected integrations.

effectstring · enumRequired

What should happen when this rule applies?

opsarray<string>Required

A nonempty list of operation classes or exact supported action names. The values depend on the rule pattern above. Choose named actions from the action catalog.

Show 3 variants

Thread type

array<string> · enum

Use this variant to decide which thread types need your approval for integration writes, such as conversations or scheduled runs. Use trigger to select the run type.

Include all three values together to cover every update during that type of run. Individual values do not give create-only or delete-only permissions.

Cannot be combined with

The integration, resources, and where objects.

App-based

array<string> · enum

Controls what your agent may do through a connected app, such as reading Notion pages without changing them.

Use this variant with the integration object.

Named-action

array<string>

Controls individual tools, such as Gmail’s action for sending an existing draft. Use it when a specific action needs its own permission.

Choose exact action names from the action catalog.

Cannot be combined with the integration object.

Example["GmailSendDraft"]

triggerobjectOptional

Limit the rule to a specific type of thread or automation trigger. See Thread filters for the fields. Omit trigger to apply the rule without a run-type restriction.

integrationobjectOptional

Select a connected app by its connector identifier, or slug. This can cover more than one connection to the app.

Show 1 property
slugstringRequired

The app identifier from the actual connection.

Examplenotion
whereobjectOptional

Add a condition that an action must meet for this rule to apply.

Use semantic for criteria Hyperagent’s AI policy checker interprets for each call, or deterministic for precise conditions in structured JSON. When both are present, both must match.

Show 2 properties
semanticstringOptional

Natural-language criteria that Hyperagent interprets for each call. Use this when defining an integration object. Be specific about what may happen and what must not change. This does not create a strict read-only connection.

ExampleOnly fetching or searching existing Notion content. Do not change it.
deterministicobjectOptional

Match specific criteria using structured JSON. All supplied conditions must match.

These conditions use Judge, per write; they do not make the rule Strict.

Hide 2 propertiesShow 2 properties
paramsobjectOptional

Check inputs supplied to the action. Each key is a nonempty, top-level input name, such as channel. All named checks must match; dotted paths do not traverse nested inputs.

Each input name maps to one of these comparison objects.

Hide 4 comparison variantsShow 4 comparison variants
equalsobject

Match one exact value.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Choose the equals comparison.

equals
valuestring | number | booleanRequired

A string, number, or boolean to match. Null, arrays, and objects are not accepted.

in_listobject

Match any value in a list.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Choose the in_list comparison.

in_list
valuesarray<string | number | boolean>Required

A nonempty list of strings, numbers, or booleans. The list may mix those types.

domain_matchobject

Match domains in email addresses, including subdomains.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Choose the domain_match comparison.

domain_match
domainsarray<string>Required

A nonempty list of literal email domains. Wildcards and URLs are not accepted.

numeric_compareobject

Match an inclusive numeric range. Supply min, max, or both; min must not exceed max.

Hide 3 propertiesShow 3 properties
typestring · enumRequired

Choose the numeric_compare comparison.

numeric_compare
minnumberOptional

The lowest allowed number, inclusive.

maxnumberOptional

The highest allowed number, inclusive. The action input must be a number, not a numeric string.

whenobjectOptional

Match a local-time window, optionally limited to selected weekdays. This must match alongside every params condition.

Hide 5 propertiesShow 5 properties
typestring · enumRequired

Choose the time_window condition.

time_window
timeZonestringRequired

A recognized time-zone name, such as America/New_York. Use 1–64 characters.

startstringRequired

Start time in 24-hour HH:MM format, inclusive.

endstringRequired

End time in 24-hour HH:MM format, inclusive. An end earlier than the start wraps past midnight.

daysarray<string · enum>Optional

Optional, nonempty list of weekdays. Omit it for every day. The weekday is checked in the chosen time zone, including for overnight windows.

resourcesobjectOptional

Limit a rule to particular destinations or connected accounts.

Cannot be combined with the integration object.
Hide 2 propertiesShow 2 properties
destinationobjectOptional

The target of the action, such as a Slack channel or email recipient. Choose one comparison below.

Hide 4 variantsShow 4 variants
equalsobject

Match one destination, such as an email recipient or an identifier the action uses.

Hide 3 propertiesShow 3 properties
typestring · enumRequired

Use equals for this comparison.

equals
valuestringRequired

The destination identifier or one email address.

principalstring · enumOptional

Marks value as the agent owner’s email address. If the owner’s address changes, an allowance stops matching; a denial can match both the saved and current address.

owner
in_listobject

Match a destination from the list. This is the comparison used for strict Slack channel permissions.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Use in_list for this comparison.

in_list
valuesarray<string>Required

A nonempty list of destination identifiers. For a strict Slack posting allowance, use actual C… channel IDs.

domain_matchobject

Match a recipient or URL domain, including its subdomains.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Use domain_match for this comparison.

domain_match
domainsarray<string>Required

A nonempty list of literal domains, such as example.org. Do not use URLs, email addresses, or wildcard patterns.

outsideobject

Match mail recipients outside the permitted addresses and domains. Include mailboxes, domains, or both. This denial does not grant permission to send within the set.

Requirements for this variant

  • Use only on a deny rule for sending actions from one mail integration: Gmail or Outlook.
  • Requires policy format 5. Use Draft policy to generate a compatible policy rather than changing its version yourself.
  • Keep destination as the only field in resources, and leave out where.
  • Use one outside-recipient set per mail integration. Combine its permitted addresses and domains in that set.
Hide 3 propertiesShow 3 properties
typestring · enumRequired

Use outside for this comparison.

outside
mailboxesarray<string | object>Optional

A nonempty list of permitted email addresses. Each entry may be an address string or an owner-address object.

Hide 2 item variantsShow 2 item variants
Email addressstring

One permitted email address, such as reviewer@example.com.

Owner’s email addressobject

A permitted address tied to the agent owner. It is in the permitted set only while value is still the owner’s current address. Both fields are required.

Hide 2 propertiesShow 2 properties
valuestringRequired

The agent owner’s actual email address.

principalstring · enumRequired

Use owner to tie this entry to the agent owner.

owner
domainsarray<string>Optional

A nonempty list of literal domains, such as example.org. Do not use URLs, email addresses, or wildcard patterns.

accountobjectOptional

The connected account used to perform the action, identified by the account-selection short ID Hyperagent supplies. Account-specific conditions use Judge, per write.

Hide 2 variantsShow 2 variants
equalsobject

Match one connected account.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Use equals for this comparison.

equals
valuestringRequired

The account-selection short ID Hyperagent supplies, not an email address, display name, integration slug, or full connection record ID.

in_listobject

Match any connected account in the list.

Hide 2 propertiesShow 2 properties
typestring · enumRequired

Use in_list for this comparison.

in_list
valuesarray<string>Required

A nonempty list of account-selection short IDs supplied by Hyperagent.

Thread filters

Limit a rule to particular thread types and invocations.

Set permissions for each thread type

Define write permissions for every thread type before adding app-specific conditions. Follow Control your agent’s actions to set them up.

triggerobjectOptional

Choose which thread types this rule covers.

Choose one selector below.

Hide 2 selector variantsShow 2 selector variants
kindstring · enumOptional

Select the thread type. Conversational threads where you can reply, such as room threads, Slack replies, and iMessage replies, are covered by the electionCarrying variant.

Hide 1 related propertyShow 1 related property
idsarray<string>Optional

Limit the rule to one or more saved triggers. Without this list, the rule covers all threads of the selected type.

Requires kind to be one of:

scheduledalivewebhookemailmcp
electionCarryingbooleanOptional

Select the thread type by whether it carries an additional election.

attendedbooleanOptional

Choose whether this rule applies to threads where someone can answer an approval request in the thread’s conversation.

To remove run scoping, omit trigger rather than leaving an empty object.

Integration action names

Native actions are tools Hyperagent recognizes by name, such as GmailSendDraft. Search by integration, action name, or purpose. Put the action name in ops without adding integration.slug.

Purpose
Gmail31
Google Calendar13
Google Drive33
Google Docs27
Google Sheets34
Google Slides31
Google Tasks11
GAGoogle Admin10
GCGoogle Chat6
GFGoogle Forms5
GAGoogle Ads19
GCGoogle Search Console5
Google Analytics32
Google Meet16
Microsoft Outlook logoMicrosoft Outlook21
Microsoft OneDrive logoMicrosoft OneDrive13
YouTube47
Twitter / X38
QuickBooks logoQuickBooks4
Basecamp logoBasecamp15
Databricks logoDatabricks3
Slack49
Telegram15
Google Contacts7
Meta Ads47
Instagram29

Run examples

Control your agent’s actions

Write, review, save, and test a policy, or migrate from the old controls.

Understand autonomy

See how instructions, connected accounts, and policy rules work together.

FAQ

Autonomy

Understand what an agent can do on its own, what needs your approval, and what its access policy blocks.

Activity

The agent's own thread history: every run it has done, live and interactive alike, with search and filters, each row opening the thread behind it.