> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# ironclaw pairing

> Manage DM pairing requests for communication channels

# ironclaw pairing

Manage pairing requests for direct message channels like Telegram and Slack. When someone sends a DM to your agent from an unknown sender, a pairing request is created that must be approved before the agent will respond.

## Subcommands

* `list` - List pending pairing requests
* `approve` - Approve a pairing request by code

***

## ironclaw pairing list

List all pending pairing requests for a specific channel.

### Syntax

```bash theme={null}
ironclaw pairing list <CHANNEL> [FLAGS]
```

### Arguments

**`<CHANNEL>`**

Channel name (e.g., `telegram`, `slack`, `discord`).

### Flags

**`--json`**

Output as JSON instead of human-readable format.

### Examples

```bash theme={null}
# List Telegram pairing requests
ironclaw pairing list telegram

# List Slack pairing requests
ironclaw pairing list slack

# Get JSON output
ironclaw pairing list telegram --json
```

### Output

**Human-readable format:**

```bash theme={null}
Pairing requests (3):
  ABC12345  user123  username=alice, first_name=Alice  2024-01-15 14:23:45
  DEF67890  user456  username=bob                      2024-01-15 15:30:12
  GHI11121  user789  first_name=Charlie                2024-01-15 16:15:33
```

Columns:

* **Code** - Pairing code to use with `approve`
* **ID** - Channel-specific user ID
* **Metadata** - Additional information (username, name, etc.)
* **Created** - Timestamp when request was created

**No pending requests:**

```bash theme={null}
No pending telegram pairing requests.
```

**JSON format:**

```json theme={null}
[
  {
    "code": "ABC12345",
    "id": "user123",
    "channel": "telegram",
    "created_at": "2024-01-15T14:23:45Z",
    "meta": {
      "username": "alice",
      "first_name": "Alice"
    }
  },
  {
    "code": "DEF67890",
    "id": "user456",
    "channel": "telegram",
    "created_at": "2024-01-15T15:30:12Z",
    "meta": {
      "username": "bob"
    }
  }
]
```

***

## ironclaw pairing approve

Approve a pairing request using its code.

### Syntax

```bash theme={null}
ironclaw pairing approve <CHANNEL> <CODE>
```

### Arguments

**`<CHANNEL>`**

Channel name (e.g., `telegram`, `slack`).

**`<CODE>`**

Pairing code from the list output (e.g., `ABC12345`).

### Examples

```bash theme={null}
# Approve Telegram pairing request
ironclaw pairing approve telegram ABC12345

# Approve Slack pairing request
ironclaw pairing approve slack XYZ99999
```

### Output

**Success:**

```bash theme={null}
Approved telegram sender user123.
```

**Code not found:**

```bash theme={null}
Error: No pending pairing request found for code: ABC12345
```

**Rate limited:**

```bash theme={null}
Error: Too many failed approve attempts. Wait a few minutes before trying again.
```

## How Pairing Works

### 1. Unknown Sender Messages You

When someone sends a DM to your agent from a channel you've configured:

```
Unknown Telegram user @alice sends: "Hello!"
```

### 2. Pairing Request Created

The agent creates a pairing request and responds with a code:

```
Your pairing code is: ABC12345

Ask the agent owner to approve with:
  ironclaw pairing approve telegram ABC12345
```

### 3. You Approve the Request

```bash theme={null}
ironclaw pairing list telegram
# Shows: ABC12345  user123  username=alice ...

ironclaw pairing approve telegram ABC12345
# Approved telegram sender user123.
```

### 4. Sender Can Now Chat

The sender's next message will be processed normally:

```
Alice: "Hello!"
Agent: "Hi Alice! How can I help you today?"
```

## Pairing Request Lifecycle

### Creation

* Created when an unknown sender messages the agent
* Includes metadata: username, display name, etc.
* Generates an 8-character alphanumeric code
* Valid indefinitely until approved or sender is blocked

### Approval

* Marks the sender as trusted
* Removes the pending request
* Future messages from this sender are processed normally

### Re-requesting

If the same sender messages again before approval:

* Extends the existing request timestamp
* Returns the same pairing code
* Does not create a duplicate request

## Security Features

### Rate Limiting

Approval attempts are rate-limited to prevent brute-force attacks:

* Too many failed attempts trigger a cooldown period
* Cooldown is user-specific (per your IronClaw instance)

### Code Format

Pairing codes are:

* 8 characters long
* Alphanumeric (A-Z, 0-9)
* Case-insensitive
* Cryptographically random

### Automatic Cleanup

Old pairing requests are automatically cleaned up after:

* 30 days of inactivity (configurable)
* Approval
* Manual deletion

## Storage Location

Pairing data is stored in:

```
~/.ironclaw/pairing/<channel>.json
```

Example: `~/.ironclaw/pairing/telegram.json`

### File Format

```json theme={null}
{
  "pending": [
    {
      "id": "user123",
      "code": "ABC12345",
      "created_at": "2024-01-15T14:23:45Z",
      "meta": {
        "username": "alice",
        "first_name": "Alice"
      }
    }
  ],
  "approved": [
    "user456",
    "user789"
  ],
  "blocked": []
}
```

## Common Workflows

### Daily Pairing Check

```bash theme={null}
# Check for new pairing requests
ironclaw pairing list telegram

# Approve trusted users
ironclaw pairing approve telegram ABC12345
```

### Bulk Approval

```bash theme={null}
# Get JSON list
ironclaw pairing list telegram --json > requests.json

# Review and approve
cat requests.json | jq -r '.[] | .code' | while read code; do
  ironclaw pairing approve telegram $code
done
```

### Monitoring Script

```bash theme={null}
#!/bin/bash
# check-pairings.sh - Monitor for new pairing requests

CHANNELS=("telegram" "slack")

for channel in "${CHANNELS[@]}"; do
  count=$(ironclaw pairing list $channel --json | jq 'length')
  if [ $count -gt 0 ]; then
    echo "$count pending $channel pairing request(s)"
    ironclaw pairing list $channel
  fi
done
```

## Channel-Specific Metadata

### Telegram

```json theme={null}
{
  "username": "alice",
  "first_name": "Alice",
  "last_name": "Smith"
}
```

### Slack

```json theme={null}
{
  "user_name": "alice",
  "real_name": "Alice Smith",
  "team_id": "T123456"
}
```

### Discord

```json theme={null}
{
  "username": "alice#1234",
  "discriminator": "1234",
  "global_name": "Alice"
}
```

## Troubleshooting

### "No pending pairing requests"

Either:

* No one has messaged your agent from unknown accounts, or
* All requests have been approved/expired

Test by messaging your agent from a new account.

### "Pairing file not found"

The channel may not be configured:

```bash theme={null}
ironclaw doctor
```

Check your `.env` file for channel configuration.

### "Code not found"

Possible causes:

* Typo in the code (codes are case-insensitive)
* Request already approved
* Request expired or manually deleted

List current requests:

```bash theme={null}
ironclaw pairing list <channel>
```

### "Rate limited"

Too many failed approval attempts. Wait a few minutes and try again.

## Manual Pairing File Management

You can manually edit pairing files if needed:

```bash theme={null}
# View pairing file
cat ~/.ironclaw/pairing/telegram.json

# Edit with your editor
vim ~/.ironclaw/pairing/telegram.json

# Validate JSON
jq . ~/.ironclaw/pairing/telegram.json
```

**Warning**: Manual edits can break pairing functionality. Use the CLI commands when possible.

## Privacy Considerations

* Pairing requests include user metadata (usernames, names)
* This data is stored locally in plaintext
* Consider the sensitivity of stored metadata
* Regularly clean up old pairing data

## Related Commands

* [onboard --channels-only](/cli/onboard) - Configure communication channels
* [config](/cli/config) - View channel configuration