OAuth Access (oauth)

Category: modifiers | Form: | Symbol: Oa

Collect delegated user grants for provider APIs

Enables delegated OAuth access for a circle: signed-in users grant provider scopes to their Triform circle so agents can interact with Microsoft Graph, Google APIs, and similar services on their behalf. Tokens are encrypted by the platform vault; this modifier stores policy, not raw secrets. Provider LOGIN to a circle is not configured here — it lives in the circle’s membership settings (circle spec membership.oauth_login).

Guide

OAuth lets a circle collect user-approved delegated access grants for agents: signed-in users grant provider scopes (Microsoft Graph, Google APIs, GitHub) to their Triform circle, and agents act on their behalf with exactly those scopes.

Typical Microsoft 365 setup:

1. Create an oauth modifier in the circle.
2. Set provider to microsoft.
3. List the scopes users may approve in delegated_scopes (for example User.Read, offline_access, Files.Read.All).
4. Users visit /api/auth/oauth/microsoft/connect to approve the grant.

Tokens from delegated grants are stored in the platform vault. The modifier contains policy and setup metadata, not raw OAuth secrets.

Provider login is not configured here. Letting external users sign IN to a circle with Microsoft/Google/GitHub is a membership concern of the circle itself — configure the membership.oauth_login block in the circle’s settings instead. Users always authenticate as their own personal circle; the circle’s membership policy decides whether that personal circle is joined to the target circle, and as what role/relationship.

Capabilities

• delegated-grants: Store user-approved provider tokens encrypted in the vault for agent use

Properties

Property	Type	Default	Description
enabled	boolean	true	Whether this OAuth access policy is active
provider	string	"microsoft"	External OAuth provider
client	object	—	OAuth client configuration source
delegated_scopes	array	[]	Provider scopes users can approve for agents, for example User.Read or Files.Read.All

Operations

attach

Post /ops/attach | Auth: Read

Attach this modifier to a target element

Attaches this modifier to a target element. The target_id must be a UUID of an existing element that supports this modifier type (check applies_to in definition.yaml). Priority controls evaluation order when multiple modifiers of the same type are attached — lower priority runs first. The attachment is stored in element_modifiers table. Cascade resolution runs at bond-time to merge this modifier into the target’s resolved config. Common mistake: attaching to an incompatible element type — check topology rules first.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this modifier from a target element

Removes this modifier from a target element. Requires the target_id. Pervasive modifiers (audit, policy) can only be detached at the level they were originally attached — inherited pervasive modifiers cannot be detached by child elements. After detach, cascade resolution re-runs to remove this modifier’s effect from the resolved config.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached/{target_id} | Auth: Read

Get all modifiers attached to a target element

Lists all modifiers attached to a specific target element, including modifier_id, type, subcategory, and priority. Useful for debugging cascade resolution or understanding which policies apply to an element before invoking it.

list_attachments

Get /ops/targets | Auth: Read

List all elements this modifier is attached to

Returns all target elements where this modifier is currently applied. Shows target_id, target_type, priority, and cascade_policy.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

Error Codes

Code	Class	Retryable	Description
OAUTH_PROVIDER_DISABLED	auth	no	The provider is not configured or enabled
OAUTH_POLICY_DENIED	auth	no	The requested delegated scopes are not allowed for this circle
OAUTH_STATE_INVALID	auth	yes	The provider callback state expired or was already used