# Temporary Permission Grants

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

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"actorBkg": "#083241", "actorTextColor": "#FFFFFF", "actorBorder": "#083241", "signalColor": "#575452", "signalTextColor": "#100F0F", "labelBoxBkgColor": "#F1EAE7", "labelBoxBorderColor": "#D7D2D0", "labelTextColor": "#100F0F", "loopTextColor": "#100F0F", "noteBkgColor": "#F1EAE7", "noteBorderColor": "#D7D2D0", "noteTextColor": "#100F0F", "activationBkgColor": "#E8E2EB", "activationBorderColor": "#083241", "altSectionBkgColor": "#F1EAE7", "altSectionColor": "#100F0F"}}}%%
sequenceDiagram
autonumber
participant E as Engineer
participant CLI as Agent Forge CLI
participant API as Amigo API

E->>CLI: forge conversation request-access <URL> -j "reason"
CLI->>API: GET /conversation/ (fetch owner user\_id)
API-->>CLI: conversation metadata
CLI->>API: POST /temporary\_permission\_grant/ (x3)
API-->>CLI: grant IDs + expiration
CLI-->>E: Display grants table
Note over E,API: Grants auto-expire after duration (default: 2 hours)" %}

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

```bash
# 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 colleague@example.com
```

| 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

```bash
# 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](https://docs.amigo.ai/developer-guide/classic-api/permissions/role-based-permissions) - Permanent role configuration
* [Agent Forge CLI Changelog](https://docs.amigo.ai/reference/agent-forge) - Release notes