# Action intents

Canonical: https://docs.flowrelay.app/reference/action-intents/
Markdown: https://docs.flowrelay.app/reference/action-intents.md

Preview, confirmation, idempotency, metering, audit, and refusal behavior for governed actions.

## Intent lifecycle
Action intents make side effects deliberate and auditable.

- Stage: Preview; What happens: FlowRelay explains the target, current configuration, possible side effects, required authority, and idempotency key.
- Stage: Confirm; What happens: A human or authorized agent confirms the exact action inside the grant and product boundary.
- Stage: Execute; What happens: FlowRelay performs the action, records audit context, and returns the result or refusal.

## Actions that need intents
Use action intents for replay, diagnostics sharing, endpoint edits, secret rotation, endpoint delete, and sender test operations when those operations are exposed through API, CLI, or MCP.

## Idempotency
Preserve the idempotency key from preview through execute. If the target, payload, endpoint, event, or actor changes, create a fresh preview.

## Audit and refusals
Audit preserves who previewed, who confirmed, what was executed, and which grant allowed it. Refusals explain the missing scope, unsafe state, expired retention, usage limit, or product boundary.

## Example Surface
- `preview -> confirm -> execute`
- `idempotencyKey`
- `refusal.reason`

## Safety Boundary
Do not include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.