mirror of
https://github.com/pawelorzech/MacTorn.git
synced 2026-03-31 20:25:43 +00:00
715f0877ff
Create wiki/ directory with 11 markdown pages covering: - Home, Installation, Getting Started guides - Features documentation for all tabs - API Setup with permissions and security - Configuration options and settings - Troubleshooting and FAQ - Development guide with architecture overview - Changelog with version history - Sidebar navigation
139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# API Setup
|
|
|
|
MacTorn requires a Torn API key to fetch your game data. This guide explains how to generate a key and what data MacTorn accesses.
|
|
|
|
## Generating an API Key
|
|
|
|
### Step-by-Step
|
|
|
|
1. **Log into Torn** at https://www.torn.com
|
|
2. Go to **Settings** in the sidebar
|
|
3. Click the **API Keys** tab, or go directly to: https://www.torn.com/preferences.php#tab=api
|
|
4. Under "Create New Key":
|
|
- Enter a name (e.g., "MacTorn")
|
|
- Select access level (see below)
|
|
5. Click **Create**
|
|
6. **Copy the 16-character key** that appears
|
|
|
|
### Access Levels
|
|
|
|
Torn offers several API access levels:
|
|
|
|
| Level | Recommended | Notes |
|
|
|-------|-------------|-------|
|
|
| **Full Access** | Yes | Simplest option, works with all MacTorn features |
|
|
| **Limited Access** | Yes | Works if you select required permissions |
|
|
| **Custom** | Possible | Select specific permissions |
|
|
|
|
### Required Permissions
|
|
|
|
If using Limited or Custom access, MacTorn requires these selections:
|
|
|
|
| Permission | Used For |
|
|
|------------|----------|
|
|
| `basic` | Player name, ID, basic info |
|
|
| `bars` | Energy, Nerve, Happy, Life bars |
|
|
| `cooldowns` | Drug, Medical, Booster timers |
|
|
| `travel` | Travel status and destination |
|
|
| `profile` | Battle stats, faction info |
|
|
| `events` | Recent events feed |
|
|
| `messages` | Unread message count |
|
|
| `money` | Cash, vault, points, tokens |
|
|
| `battlestats` | Strength, Defense, Speed, Dexterity |
|
|
| `attacks` | Recent attack history |
|
|
| `properties` | Property information |
|
|
|
|
For watchlist functionality:
|
|
| Permission | Used For |
|
|
|------------|----------|
|
|
| `market` (v2) | Item prices from Item Market |
|
|
|
|
## Entering Your API Key in MacTorn
|
|
|
|
1. Click the MacTorn icon in your menu bar
|
|
2. Go to the **Settings** tab
|
|
3. Enter your API key in the text field
|
|
4. Click **Save & Connect**
|
|
|
|
MacTorn will immediately attempt to fetch your data. If successful, you'll see your status appear in the Status tab.
|
|
|
|
## API Data Usage Disclosure
|
|
|
|
In compliance with Torn's API Terms of Service, here is exactly what MacTorn accesses:
|
|
|
|
### User Endpoint (v1)
|
|
|
|
MacTorn calls the user endpoint with these selections:
|
|
|
|
```
|
|
/user/?selections=basic,bars,cooldowns,travel,profile,events,messages,money,battlestats,attacks,properties
|
|
```
|
|
|
|
**Purpose:** Display your player status, bars, cooldowns, travel info, faction, events, messages, finances, battle stats, and attacks.
|
|
|
|
### Faction Endpoint (v1)
|
|
|
|
When you have faction data:
|
|
|
|
```
|
|
/faction/?selections=basic,chain
|
|
```
|
|
|
|
**Purpose:** Display faction name, chain status, and war information.
|
|
|
|
### Market Endpoint (v2)
|
|
|
|
For watchlist items:
|
|
|
|
```
|
|
/v2/market/{itemId}?selections=itemmarket,bazaar
|
|
```
|
|
|
|
**Purpose:** Fetch current market prices for items you're watching.
|
|
|
|
## Security Best Practices
|
|
|
|
### Do
|
|
|
|
- **Use a dedicated key** for MacTorn that you can revoke if needed
|
|
- **Limit permissions** if you don't need all features
|
|
- **Keep your key private** - never share it
|
|
|
|
### Don't
|
|
|
|
- Don't use your main API key for third-party apps
|
|
- Don't share your API key with others
|
|
- Don't commit your key to git or public repositories
|
|
|
|
## Key Storage
|
|
|
|
MacTorn stores your API key locally using macOS's `UserDefaults` system. The key:
|
|
|
|
- Is stored on your Mac only
|
|
- Is **not** transmitted anywhere except to Torn's API
|
|
- Is **not** backed up to iCloud
|
|
- Can be removed by clearing MacTorn's preferences
|
|
|
|
## Revoking Access
|
|
|
|
If you need to stop MacTorn from accessing your Torn data:
|
|
|
|
1. Go to Torn API settings: https://www.torn.com/preferences.php#tab=api
|
|
2. Find your MacTorn key
|
|
3. Click **Delete** next to it
|
|
|
|
MacTorn will show an error state until a new valid key is entered.
|
|
|
|
## API Rate Limits
|
|
|
|
Torn's API has rate limits. MacTorn is designed to respect these:
|
|
|
|
- Default refresh is 30 seconds
|
|
- Minimum refresh is 15 seconds
|
|
- Each refresh makes 1-3 API calls depending on features used
|
|
|
|
If you're using multiple Torn apps, you may want to use longer refresh intervals.
|
|
|
|
---
|
|
|
|
**Next:** [[Configuration]] - Customize your settings
|