Temporary Permission Grants

Request time-limited, scoped access to specific conversations for debugging and QA.

Temporary permission grants provide time-limited, scoped access to specific resources. They are the recommended way for developers and support engineers to access individual conversations for debugging and quality analysis without requiring broad, permanent role changes.

What You'll Learn

• How temporary permission grants work

• How to request conversation access using the Agent Forge CLI

• How to list and manage active grants

• Best practices for least-privilege access

Why Temporary Grants

The default administrator role restricts conversation visibility to conversations associated with the admin's own role. This is correct for production security, but developers debugging specific conversations need targeted access.

Before (broad role): Grant org-wide conversation visibility via a custom role -- overly permissive, no expiration, no audit trail.

After (temporary grants): Request access to a specific conversation with a justification. The grant expires automatically and is fully auditable.

How It Works

Each request-access call creates three permission grants scoped to the conversation's owner:

Permission	What It Allows
Conversation:GetConversation	View conversation metadata and state
Conversation:GetMessage	Read conversation messages
Conversation:GetInteractionInsights	View interaction-level debugging insights

All grants share the same conditions:

• conversation_user_id equals the conversation owner's user ID

• org_id equals the organization ID

Using the CLI

Request Access

# Basic: request 2-hour access to a conversation
forge conversation request-access https://org.amigo.ai/admin/conversation/abc123 \
    -j "Debugging reported issue #42"

# Using a conversation ID instead of URL
forge conversation request-access abc123def456abc123def456 -e production \
    -j "Reviewing customer feedback" -d PT4H

# Grant access to a colleague
forge conversation request-access https://org.amigo.ai/admin/conversation/abc123 \
    -j "Pair debugging session" --user-email [email protected]

Option	Required	Default	Description
CONVERSATION	Yes	--	Conversation URL or 24-char hex ID
--justification / -j	Yes	--	Reason for access (minimum 10 characters)
--env / -e	Conditional	Inferred from URL	Environment name
--duration / -d	No	PT2H	ISO 8601 duration (e.g., PT30M, PT2H, P1D)
--user-email	No	Self (caller)	Email of user to grant access to
--json	No	false	Output results as JSON

List Active Grants

# List your own active grants
forge conversation list-access -e production

# List all users' grants including expired
forge conversation list-access -e production --all --show-expired

# JSON output for scripting
forge conversation list-access -e production --json

Option	Required	Default	Description
--env / -e	Yes	--	Environment name
--all	No	false	Show all users' grants (not just your own)
--show-expired	No	false	Include expired grants
--json	No	false	Output as JSON

Best Practices

Use Temporary Grants Instead of Broad Roles

Request access per-conversation as needed rather than maintaining a role with org-wide conversation visibility.

Include Meaningful Justifications

Justifications create an audit trail. Reference ticket numbers, bug reports, or customer feedback IDs.

Use Short Durations

The default 2-hour duration is sufficient for most debugging sessions. Use longer durations (up to P3D) only when necessary.

Grant to Specific Users

When granting access for a colleague, use --user-email rather than sharing credentials.

Related Topics

• Role-Based Permissions - Permanent role configuration

• Agent Forge CLI Changelog - Release notes