MobileMusicAssistant/Mobile Music Assistant/DocsLongLivedTokens.md

# How to Use Long-Lived Tokens

## Why Use Long-Lived Tokens?

✅ **More Secure** - Password is never stored on device  
✅ **Convenient** - No repeated logins (token valid for months/years)  
✅ **Revocable** - Can be invalidated from server without changing password  
✅ **Best Practice** - Official Music Assistant apps use this method  

## Creating a Long-Lived Token

### Method 1: Via Web Interface (Recommended)

1. **Open Music Assistant in your browser:**
   ```
   https://musicassistant-app.hanold.online
   ```

2. **Login with your username and password**

3. **Go to Settings:**
   - Click the gear icon (⚙️) in the top right
   - Select "Users" or "User Management"

4. **Create a Token:**
   - Find your user account
   - Click "Create Token" or "Generate Long-Lived Access Token"
   - Give it a name (e.g., "iPhone App")
   - Set expiration (optional - can be "Never")

5. **Copy the Token:**
   - Token will be displayed ONCE
   - Copy it immediately!
   - **Important:** You can't see it again after closing the dialog

6. **Use in App:**
   - Open the iOS app
   - Select "Long-Lived Token" as login method
   - Paste the token
   - Enter server URL
   - Click "Connect"

### Method 2: Via API (Advanced)

If you need to automate token creation:

```bash
# Step 1: Login to get short-lived token
curl -X POST https://musicassistant-app.hanold.online/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

# Response: {"access_token": "eyJ..."}

# Step 2: Create long-lived token (requires WebSocket connection)
# This is complex - use the web interface instead!
```

## Using the Token in the App

### Option A: Long-Lived Token (Recommended)

1. **In LoginView, select "Long-Lived Token"**
2. **Enter server URL:**
   ```
   https://musicassistant-app.hanold.online
   ```
   (No port number needed if using reverse proxy on 443!)

3. **Paste your token:**
   - Token looks like: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
   - Very long string (100+ characters)
   - Contains dots (.)

4. **Click "Connect"**

### Option B: Username & Password

1. **In LoginView, select "Username & Password"**
2. **Enter credentials**
3. **App will create a long-lived token automatically**
4. **Token is saved in Keychain for future use**

## Token Security

### Stored Securely
- Token is saved in iOS Keychain
- Encrypted by the system
- Not accessible to other apps
- Survives app reinstalls

### Token Protection
- Never share your token
- Treat it like a password
- Revoke if compromised
- Create device-specific tokens

### Revoking a Token

If your token is compromised:

1. **Go to Music Assistant Settings → Users**
2. **Find the token in the list**
3. **Click "Revoke" or "Delete"**
4. **Create a new token**
5. **Update the app with new token**

## Troubleshooting

### "Invalid Token" Error

**Causes:**
- Token was revoked on server
- Token expired
- Token not copied completely
- Server URL mismatch

**Solution:**
- Generate a new token
- Copy entire token (check for truncation)
- Verify server URL matches

### "Connection Failed" Error

**Causes:**
- Server URL incorrect
- Server offline
- Network issues
- Reverse proxy misconfiguration

**Solution:**
- Test server URL in browser
- Check server is running
- Verify network connectivity
- Check reverse proxy logs

### Token Not Working After Server Upgrade

**Cause:**
- Tokens may be invalidated during MA upgrades

**Solution:**
- Generate a new token
- Update in app

## Comparison: Token vs Credentials

| Aspect | Long-Lived Token | Username & Password |
|--------|-----------------|---------------------|
| Security | ✅ Better | ⚠️ Password stored temporarily |
| Convenience | ✅ No repeated logins | ❌ Manual login needed |
| Revocability | ✅ Easy to revoke | ⚠️ Must change password |
| Setup | ⚠️ Initial setup required | ✅ Simple |
| Recommended | ✅ Yes | ⚠️ For first setup only |

## Best Practices

1. **Use Long-Lived Tokens** for production
2. **Create device-specific tokens** (one per iPhone/iPad)
3. **Name tokens clearly** (e.g., "iPhone 15 Pro")
4. **Set reasonable expiration** (e.g., 1 year)
5. **Rotate tokens periodically** (every 6-12 months)
6. **Revoke unused tokens** to reduce security risk

## Token Format

A Music Assistant token looks like:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTIzIiwiaWF0IjoxNjc4ODg1MjAwLCJleHAiOjE5OTQyNDUyMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
```

**Structure:**
- Three parts separated by dots (.)
- Base64-encoded JSON
- Signed by server
- Contains user ID and expiration

**Do NOT:**
- Manually edit the token
- Share it publicly
- Commit to git repositories
- Include in screenshots

## Integration with App

The app handles tokens automatically:

```swift
// Token is saved securely
service.authManager.saveToken(serverURL: url, token: token)

// Token is used for all API calls
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")

// Token persists across app restarts
// Loaded automatically from Keychain
```

## Advantages Over Password

1. **Granular Control**
   - Different tokens for different devices
   - Revoke one without affecting others

2. **Audit Trail**
   - See which tokens are active
   - Track last used time
   - Monitor token usage

3. **No Password Exposure**
   - Password never leaves browser
   - Token can't be used to change password
   - Limited scope of damage if compromised

4. **Performance**
   - No password hashing on each request
   - Direct token validation
   - Faster authentication

## Summary

**For Regular Use:**
→ Use **Long-Lived Token** method
→ Create token via web interface
→ Copy/paste into app
→ Store in Keychain
→ Enjoy seamless authentication!

**For Initial Setup:**
→ Use **Username & Password** once
→ App creates token automatically
→ Switch to token method for security
→ Revoke password-created tokens if needed