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:

# 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:

// 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