Owner actions
Owner actions use signed-in sessions, fresh approval, and idempotency keys for sensitive workspace changes.
Owner actions change who controls a workspace, who can reach it, what it costs, or where it can connect. Use this page before changing ownership, members, billing, keys, credentials, webhooks, triggers, or an external destination.
This security rule is separate from normal credit-bearing work. For the run credit boundary, read Spend caps and budgets. For provider connections, read Integrations.
What owner actions cover
Root capabilities cover changes that affect workspace control or an external destination. The set includes deleting an account or workspace, transferring ownership, changing or removing members, and changing the workspace's billing state.
It also includes billing checkout, seat and tier changes, cancellation, credits purchase, overage actions, and API key creation, reveal, and revocation. A key belongs to one workspace, one actor, explicit scopes, and its own spend policy.
Connection work is included because credentials and destinations determine what the workspace can reach. The protected changes include LinkedIn, X, Slack, Google, scheduler, Stripe, mailboxes, signal sources, custom HTTP, pixel signing secrets, webhooks, workflow triggers, trigger secrets, and social content destinations.
| Purpose | Examples |
|---|---|
| Workspace and membership | Account or workspace deletion, ownership transfer, member changes, and role changes. |
| Billing and keys | Checkout, seats, tier, cancellation, credit purchase, overage, and API-key creation, reveal, or revocation. |
| Connections and destinations | Integration credentials, social destinations, mailboxes, webhooks, workflow triggers, and secrets. |
Use a signed-in session
Root capabilities run only from a signed-in session. They never run from an API key. This keeps the security decision attached to the current person instead of a reusable programmatic key.
The server applies the tier that the root action defines: fresh_owner, workspace_admin, or current_member for mailbox authorization. The tier is a property of the action, not a client-selected request field.
A fresh signed-in session matters when a change can remove access, expose a secret, cancel a plan, or connect the workspace to an outside system. The current session is checked before the root action executes.
Prepare the request
First discover the exact capability contract. The tool catalog returns the input schema, action policy, required scopes, cost policy, and asynchronous policy for the selected capability. Do not infer fields from a similar workspace action.
Use one idempotency key for one intended mutation. The REST route accepts the key in the Idempotency-Key header or as the top-level idempotency_key field. A header and body value must match when both are present.
A mutating call also names a Mode. The server does not default mutations to live. Use a supported mode from the fetched contract, and use a dry run to validate against real workspace state without business writes, provider spend, or outward actions.
Explain the exact owner-action requirements for changing this workspace setting. Show the capability contract, the signed-in session tier, and the idempotency key requirement before making any change.Understand the result
A successful state-bearing result can include web_url, which points to the exact object in the app. Keep the JSON identifiers as the source of truth and use the link to inspect the object in the appropriate workspace screen.
The action can affect access, money, a credential, or an outside system. Record the returned identifiers, the final workspace state, and the destination that changed. This makes later investigation possible without guessing which request made the change.
An owner action is a security exception, not a general spend or sending control. Normal actions run under the quote and maximum-credits ceiling their fetched contract requires, and a paid run above the server's row or provider-spend limit also waits for the user's yes (see the spend caps page). Do not add owner-action security language to an ordinary sequence or provider run.
Before changing a connection or a destination, identify the workspace, the actor, the requested scope, and the external system affected. Before changing billing or membership, identify the current workspace state and the intended end state. Those checks make the confirmation specific: a user can see whether they are changing a mailbox, a social destination, a role, a plan, or a key, rather than receiving a generic warning about a write.
When it goes wrong
If the route returns destructive_approval_required, the request is not coming from a current owner session at the required tier. Sign in to the workspace with the appropriate member session, then retry the intended action from that session.
If it returns idempotency_key_required, include an Idempotency-Key with one to 255 characters. Keep that exact key for a retry of the same intended action, rather than making a new key after a network interruption.
If it returns idempotency_conflict, the header and body key disagree. Send the same key in both places or send only one. The server does not select a winner between two different values.
Delegate execution is different: the approved step mints its key on the server. A caller key in the header, top level, or params is refused. Send the delegate step token without a caller idempotency key, because using the minted key preserves the already-created operation identity.
If a mutation has no mode, the route returns mode_required. Fetch the selected capability schema, choose one supported mode, and retry with the same action details. The server refuses to guess whether a security-sensitive change should be live.
If the requested capability is not the action you intended, stop before retrying. Search the catalog again, fetch the exact contract, and compare its description, scopes, and input fields with the workspace change you need. A nearby capability can affect a different destination or a different part of workspace access.