DM / Code Pairing

6.2. DM / Code Pairing — Flexible Authorization Without Collecting IDs First

How it works

Instead of having to collect user IDs in advance, a stranger who DMs the bot receives a one-time pairing code, which the bot owner then approves via CLI:

# What the user sees: "🔐 Pairing code: XKGH5N7P"
hermes pairing list                          # view pending requests
hermes pairing approve telegram XKGH5N7P      # approve
hermes pairing revoke telegram 123456789      # revoke previously granted permission
hermes pairing clear-pending                  # delete all pending codes

Security properties of the pairing code

Pairing codes expire after 1 hour, are rate-limited on attempts, and are generated with cryptographic entropy — not a simple random string. Pairing state is stored persistently and survives gateway restarts.

A Docker-specific note

The official Docker image runs the gateway as a non-privileged user (hermes, uid 10000) via gosu, but docker exec runs as root by default — if you approve pairing through docker exec without specifying the correct user, the approval file is created by root with 0600 root:root permissions, which the gateway cannot read and silently ignores the approval. Always specify the correct user when exec-ing into the container:

docker exec -u hermes <container> hermes pairing approve telegram XKGH5N7P

Notes

• Pairing is the ideal choice for teams — no gateway restart needed when adding a new member; an approval takes effect immediately.
• Approve pairing from a private channel (the bot owner’s DM/CLI), not from the public bot itself — avoid an attacker using the bot itself to approve themselves.
• The Web Dashboard (4.4) also supports approving/revoking pairing without the CLI — useful for remote administrators who do not have convenient SSH access.