Torn Limited API Key Generation Guide
Relay needs a Torn API key to read your attack log and confirm hits. It must be a Limited (type 3) key. This guide explains why, and how to generate one.
Why Limited and nothing else
Torn API keys come in access levels. From least to most powerful:
| Type | Name | What it can read |
|---|---|---|
| 1 | Public | Public profile data only |
| 2 | Minimal | Basic personal stats |
| 3 | Limited | Attacks, battle stats summary, basic personal data - what Relay needs |
| 4 | Full | Everything Limited has, plus money, bank, items, messages |
| 5 | Custom | Whatever specific scopes you choose, can include money/items |
Relay reads your attack log (to confirm a loss or hit really happened against the right target), your events (to confirm a payout reached you) and your battle stats (to check you can take a contract). Merc applications also read your merits and equipped weapons. It has no legitimate reason to see your bank balance, items, or private messages. Using a Limited key means that even in the worst case (a bug, a database leak, a malicious server admin), your money and items were never exposed through this bot, because Relay simply cannot see them with that key.
Using a Custom key instead
A Custom key works if it has every selection Relay reads. Anything missing quietly turns off the feature that reads it.
| Section | Selections |
|---|---|
| user | basic, profile, attacks, events, battlestats, personalstats, bars, cooldowns, bounties |
| user (mercs) | merits, equipment |
| torn | bounties, timestamp, merits |
| faction | basic, plus attacks if you use faction retal cover |
The holding account's key (HOLDING_API_KEY, set by the bot operator) is different: Torn only shows logs to a Full access key, or a Custom key with the log selection.
Never give Relay a Full or Custom key with money/item scopes. If you do, Relay's /setup link flow will still work, but you have handed the bot operator more trust than the design requires. If you ever generate a new key for another purpose, do not reuse it here - generate a dedicated Limited key for Relay.
How to generate a Limited key
- Log into Torn, go to Settings -> API Key.
- Click Create New Key.
- Under Access Level, choose Limited Access.
-
Give it a label you will recognize later, e.g.
relay-bot. - Click Generate, then copy the key.
-
Paste it into the Relay Link Account form in
#get-started. Do not paste it anywhere else, and do not post it in chat - see for what Relay does with it once submitted.
Revoking access later
If you ever want to unlink from Relay: run /unlink, or go to Torn's API key settings and delete the key. Deleting the key on Torn's side immediately stops Relay (or anything else) from using it, even if it is still stored somewhere.
Troubleshooting
- "Invalid key" error on link - you probably pasted extra whitespace, or generated a Public/Minimal key by mistake. Regenerate as Limited and try again.
- Link succeeds but hits never verify - see for API error codes and rate-limit notes.