User authorized actions

Best practices for building experiences where generative AI needs user authorization to invoke tools, run commands, or carry out a consequential action during a session.

On this page

About this page

Published: August 15, 2025 | Last updated: September 15, 2026

Key UX concepts

Match authorization to risk level

Present the level of friction appropriate to the action's potential impact. Routine tool calls and commands use a scope selector. A single consequential action uses an explicit approve or reject decision. Irreversible actions add a confirmation input.

Reduce repeated friction

When an agent calls the same tool repeatedly, let users grant trust once so the agent can proceed without prompting again. Scope that trust to a single call, the current conversation, or all conversations.

Communicate consequences

Before authorization, clearly communicate whether changes can be reversed, what happens if something goes wrong, and any long-term impacts of the change. This helps users decide how much trust to grant.

Keep users in control

Always provide clear scoped access, full access or exit. If the user declines, make sure the agent acknowledges it.

Record the outcome

An authorization request is a decision the user made, so its outcome belongs in the conversation. Leave a resolved state in the transcript showing what was decided and at what scope.

Building blocks

A.
Authorization dialog

Display a dialog above the prompt input to allow users to authorize tool or command calls when an AI invokes it.

B.
Title

Describes what the agent wants to do. For example, use Allow tool-name ? for tool authorization, use Allow this command? for command authorization.

C.
Description - optional

A short explanation of what this tool or command does. Use regular body text. When builders need to provide additional context that is secondary for the user, show an expandable section below the description.

D.
Command body - optional

When a command is too long to fit in the title of the dialog, the complete command string appears in a code block underneath the title.

E.
Expandable section - optional

When additional details are needed (such as parameters, metadata, or output), use an expandable section below the description. This keeps the dialog compact by default while allowing users to inspect details when needed.

F.
Scope selector

A compact Select component that determines how long the permission persists. Options vary by use case.

  • Allow this time: Grants permission for this single invocation only. The next time the agent calls the same tool or command, the authorization dialog appears again.

  • Allow for this chat: Grants permission for all subsequent invocations of the same tool or command within the current conversation. The agent runs the tool automatically without prompting again.

  • Always allow: Grants persistent permission for all future invocations of the same tool or command, across all conversations.

G.
Action buttons

  • Cancel: Dismisses the dialog. Agent then acknowledges the dismissal in the conversation. For example: Got it, skipping that step.

  • Allow: Approves the action at the selected scope. dialog dismisses immediately.

  • Skip: Skip is used for bulk authorization. For example, when the agent needs authorization for multiple tools, it allows user to selectively deny individual tools while continuing to review the remaining ones.

H.
Pagination - optional

Pagination is used for bulk tool authorization, for example, when the agent needs authorization for multiple tools, the dialog shows one tool at a time with pagination controls in the header. Users can navigate between tools, approve or skip each one individually.

I.
Close button

Always present in the top-right corner of the dialog. Dismisses the entire authorization flow. The close button is always visible regardless of use case to maintain consistency.

Common use cases

Tool authorization

Use when an agent needs to invoke a tool (MCP server, API integration) during a workflow. The user sees the tool name and decides whether to allow it. When the user first invokes the tool, the authorization dialog appears with the tool name. The user selects a permission scope and approves or cancels. When the same tool is invoked subsequently in the current session, and if the user previously selected "Allow for this chat", the tool runs automatically. Display an inline confirmation in the conversation. For example, if the MCP is involved during the thinking stages of the agent, display a step stating the tool name and requisite details.

The agent requests permission to invoke a certain tool. The title shows the tool name in inline code format.

CLI command authorization

Use when an agent needs to run a command such as a CLI command. Display the command in the authorization dialog so the user can verify what will be executed before approving. For short commands (under ~40 characters) display the command in the title. For long commands, use a generic title with the full command as a code block in the body of the dialog.

The command is brief enough to display in the title. A description explains what the command does.

One-time authorization

Use when the agent needs authorization for a single action rather than for a tool it will call repeatedly. There is no future invocation for a scope to cover, so the scope selector is omitted and the buttons carry the whole decision. How much friction to add depends on the action's impact.

Ship the checkout service change once the tests are green
The tests passed. The change is ready to go to production.
Use of this service is subject to the AWS Responsible AI Policy 

Irreversible action

Use when the action can't be undone, such as deleting a database cluster that live services still resolve. Where the action names a single resource, the dialog includes a confirmation input. Where several resources are affected, a warning alert lists them. Use one form or the other, not both. After the action runs, the agent reports what was deleted, what was kept, and for how long.

Tear down the staging databases we stopped using
I found three clusters with no connections in the last 30 days. Two of them still have services resolving to them.
Use of this service is subject to the AWS Responsible AI Policy 

General guidelines

Do

  • Show the tool or command name in awsui-inline-code format to visually distinguish it from surrounding text.
  • Dismiss the dialog immediately when the user selects Action buttons. Don't show a loading state or success indicator. "The resolved state belongs in the conversation, not in the dismissed dialog."
  • Always show the close button on the authorization dialog.
  • Show a description explaining what the tool or command does. This helps users who may not recognize the tool name.
  • If the user cancels, have the agent acknowledge in the conversation. For example, Got it, skipping that step.
  • When a request expires, show the expired resolved state and have the agent report that nothing ran.

Don't

  • Don't show the authorization dialog for a tool that is already trusted for the session. Instead, let the agent execute the tool automatically, and display a confirmation in chat or thinking trace.
  • Don't show the scope selector if your system does not support persisting preferences.
  • Don't pre-select or auto-focus the approve action for risky operations. A stray enter or click could confirm a consequential action the user didn't intend.
  • Don't let a pending request block the UI indefinitely. If the user never responds, cancel and report rather than continuing silently.

Writing guidelines

General writing guidelines

  • Use sentence case, but continue to capitalize proper nouns and brand names correctly in context.

  • Use end punctuation, except in headers and buttons. Don’t use exclamation points.

  • Use present-tense verbs and active voice.

  • Don't use please, thank you, ellipsis (...), ampersand (&), e.g., i.e., or etc. in writing.

  • Avoid directional language.

    • For example: use previous not above, use following not below.

  • Use device-independent language.

    • For example: use choose or select not click.

Component-specific guidelines

Authorization dialog title

  • Use the format: Allow tool-or-command-name?

    • For example: Allow npm test?

Irreversible action title

  • name the consequence rather than the verb pair. For example, Your authorization is needed to delete objects in the S3 bucket.

One-time decision title:

  • Approve action? For example, Approve deployment to production

Resolved state labels

  • past tense, no end punctuation —Approved, Rejected, Approved automatically, Request expired

Expiry message

  • state what didn't happen. For example, This request expired. Nothing was deployed.

Scope selector options

  • Allow this time, Allow for this chat, Always allow

Accessibility guidelines

General accessibility guidelines

  • Follow the guidelines on alternative text and Accessible Rich Internet Applications (ARIA) regions for each component.

  • Make sure to define ARIA labels aligned with the language context of your application.

  • Don't add unnecessary markup for roles and landmarks. Follow the guidelines for each component.

  • Provide keyboard functionality to all available content in a logical and predictable order. The flow of information should make sense.

Component-specific guidelines

  • When the dialog appears, focus moves to the dialog.

  • When a confirmation input is present (critical action variant), Enter triggers form submission only after the confirmation phrase matches. The Allow button remains disabled until the input is validated.

  • Focus returns to the chat input when the dialog is dismissed.

  • The one-time decision card is not a dialog. Don't give it a dialog role and don't trap focus in it, the conversation stays reachable while the request is pending.

  • Don't set initial focus on the approve action. Move focus to the card's heading.

  • Convey the resolved state with text, not color alone. The StatusIndicator label carries the disposition for assistive technology.

  • Report an expiry as a message in the conversation, so it appears in reading order rather than only changing the appearance of the card.