# How to Configure Multi-Instance Providers for Multiple Accounts in Music Assistant

> Learn how to configure multi-instance providers for multiple accounts in Music Assistant. Enable multiple instances with true and assign unique instance IDs for seamless integration.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-13

---

**Music Assistant supports running multiple instances of the same provider simultaneously by setting `"multi_instance": true` in the provider's [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) and supplying a unique `instance_id` for each account configuration.**

The music-assistant/server repository enables users to connect multiple accounts from the same streaming service through its multi-instance provider architecture. When you configure multi-instance providers for multiple accounts, the system creates isolated provider objects that route playback, metadata retrieval, and library indexing to the correct credentials.

## Understanding Multi-Instance Provider Architecture

### Manifest Configuration

Each provider’s capabilities are declared in `music_assistant/providers/<provider>/manifest.json`. The `multi_instance` boolean flag determines whether the framework allows multiple concurrent instances. For example, the Spotify provider sets this flag at line 11 of its manifest file, signaling that users may add several Spotify accounts.

### Instance Identification and Validation

The `ProviderManifest` dataclass in [`music_assistant/models/provider.py`](https://github.com/music-assistant/server/blob/main/music_assistant/models/provider.py) defines the `multi_instance` attribute that drives this behavior. When parsing configurations, [`music_assistant/controllers/config.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/config.py) enforces validation around line 1025, ensuring that entries for multi-instance providers include a distinct `instance_id` field to prevent collision between accounts.

## Provider Registration Logic

During startup, [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) handles provider instantiation at approximately line 969. The registration logic evaluates the condition `existing and prov_manifest and not prov_manifest.multi_instance`. 

- For **single-instance** providers, this check blocks duplicate registrations.
- For **multi-instance** providers, the system bypasses this restriction and creates a new `MusicProvider` object for every unique `instance_id` encountered in the configuration database.

## Library Item Mapping

After all providers load, [`music_assistant/controllers/music.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/music.py) executes `correct_multi_instance_provider_mappings()` at approximately line 3483. This method constructs a lookup table that maps library items—such as tracks, albums, and playlists—to their specific provider instances. This ensures that a "Discover Weekly" playlist from your work account routes through the correct provider instance rather than your personal account.

## How to Configure Multi-Instance Providers via API

To programmatically add multiple accounts for the same provider, create configuration entries with unique `instance_id` values.

**Adding a second Spotify account:**

```python
await mass.config_entries.create(
    domain="spotify",
    data={
        "username": "user2@example.com",
        "password": "secure-token",
        "instance_id": "spotify-work"
    }
)

```

**Retrieving a specific instance:**

```python
provider = await mass.get_provider(
    domain="spotify",
    instance_id="spotify-work"
)
await provider.login()

```

**Accessing provider-specific media:**

```python
playlist = await provider.get_playlist_by_name("My Favorites")
await music_controller.play_media_item(playlist.tracks[0])

```

## Summary

- Set `"multi_instance": true` in the provider's [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) to enable support for multiple accounts per the `ProviderManifest` dataclass.
- Supply a unique `instance_id` for each account configuration to prevent registration collisions.
- The registration logic in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) (line ~969) creates isolated provider instances by checking `existing and prov_manifest and not prov_manifest.multi_instance`.
- Use `correct_multi_instance_provider_mappings()` in [`music_assistant/controllers/music.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/music.py) (line ~3483) to maintain proper routing between library items and their respective provider instances.
- Access specific instances programmatically using `await mass.get_provider(domain, instance_id)`.

## Frequently Asked Questions

### Can I add multiple accounts for any provider in Music Assistant?

No. Only providers that declare `"multi_instance": true` in their [`manifest.json`](https://github.com/music-assistant/server/blob/main/manifest.json) support multiple concurrent accounts. Single-instance providers will reject additional configuration entries if an existing instance is already registered for that domain.

### What happens if I use the same instance_id for two different accounts?

The system treats duplicate `instance_id` values as identical instances. In [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py), the registration logic skips configurations that would create duplicates, potentially ignoring the second account's credentials and preventing login.

### How do I access a specific account when using the Music Assistant API?

Use the `get_provider()` method with both the `domain` and `instance_id` parameters: `await mass.get_provider("spotify", instance_id="personal-account")`. This returns the specific provider instance associated with those credentials, allowing you to interact with that account's library.

### Do library items from different accounts remain separate?

Yes. The `correct_multi_instance_provider_mappings()` method in [`music_assistant/controllers/music.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/music.py) maintains discrete mappings for each provider instance. Tracks, playlists, and metadata from your work account remain distinct from your personal account, preventing cross-contamination between libraries.