Spotify OAuth Integration

The SoundTouch service supports Spotify OAuth integration to broker access tokens for SoundTouch speakers. This is particularly useful for maintaining Spotify Connect functionality after the Bose cloud shutdown (scheduled for May 2026).

OAuth Flows

The service supports two primary OAuth flows: a browser-based flow and a mobile app-based flow (specifically for the ueberboese app).

1. Browser-based Flow

The user initiates the flow, completes authorization in their browser, and is redirected back to the service.

sequenceDiagram
    participant Client as Client (curl/app)
    participant Service as Service
    participant Spotify as Spotify Auth Server
    participant Browser as User's Browser

    Client->>Service: POST /mgmt/spotify/init [Basic Auth]
    Service-->>Client: {"redirectUrl": "https://accounts.spotify.com/authorize?..."}
    
    Client->>Browser: User opens URL
    Browser->>Spotify: User logs in & grants access
    Spotify-->>Browser: Redirect to /mgmt/spotify/callback?code=abc
    
    Browser->>Service: GET /mgmt/spotify/callback?code=abc
    Note over Service: No auth needed for callback
    
    Service->>Spotify: POST /api/token (exchange code)
    Spotify-->>Service: {access_token, refresh_token}
    
    Service->>Spotify: GET /v1/me (fetch profile)
    Spotify-->>Service: {id, display_name, email}
    
    Note over Service: Store account to disk
    
    Service-->>Browser: HTML: "Spotify Connected. You can close this window."

2. Mobile App Flow (ueberboese)

The mobile app handles the redirect via a deep link and then confirms the authorization with the service.

sequenceDiagram
    participant App as ueberboese Flutter App
    participant Service as Service
    participant Spotify as Spotify Auth Server

    App->>Service: POST /mgmt/spotify/init [Basic Auth]
    Service-->>App: {"redirectUrl": "https://..."}
    
    App->>Spotify: Open in-app browser (User authorizes)
    Spotify-->>App: Deep link redirect: ueberboese-login://spotify?code=abc
    
    App->>Service: POST /mgmt/spotify/confirm?code=abc [Basic Auth]
    
    Service->>Spotify: POST /api/token (exchange code)
    Spotify-->>Service: {access_token, refresh_token}
    
    Service->>Spotify: GET /v1/me (fetch profile)
    Spotify-->>Service: {profile}
    
    Service-->>App: {"ok": true}

3. Token Retrieval (Boot Primer / Speaker Setup)

Once an account is linked, access tokens can be retrieved for use with speakers (e.g., via the addUser ZeroConf command).

sequenceDiagram
    participant Primer as Boot Primer Script
    participant Service as Service
    participant Spotify as Spotify Token API
    participant Speaker as Speaker (Bose ST 20)

    Primer->>Service: GET /mgmt/spotify/token [Basic Auth]
    
    alt Token expired
        Service->>Spotify: POST /api/token (refresh)
        Spotify-->>Service: new tokens
    end
    
    Service-->>Primer: {"access_token": "...", "username": "..."}
    
    Note over Primer: Spotify Connect ZeroConf
    Primer->>Speaker: POST /SpotifyConnect (addUser with token)
    Speaker-->>Primer: OK
    Note over Speaker: Speaker now has Spotify access

Boot Primer Script

A boot primer script that uses these endpoints to feed Spotify tokens to speakers via ZeroConf is available in the scripts/spotify/ directory: spotify-boot-primer.sh.

This script can be installed on the speaker itself (which runs embedded Linux) to automatically prime Spotify Connect at boot time. See README.md and INSTALL.md for instructions.

Automated Installation via Service

The SoundTouch service provides a dedicated management endpoint to automatically handle the installation of the Spotify boot primer on the speaker: POST /mgmt/devices/{deviceId}/spotify/install-primer

Automated Installation Steps

When you run the Spotify primer installation, the service performs the following:

1. Directories: Creates /mnt/nv/bin and /mnt/nv/BoseApp-Persistence/1 on the speaker.
2. Binary: Uploads the spotify-boot-primer script to the speaker.
3. Configuration: Automatically generates and uploads spotify-primer.conf containing the service’s URL and management credentials.
4. Boot Hook: Injects a call to the primer in the speaker’s /mnt/nv/rc.local using idempotent markers.
5. Environment: Updates /mnt/nv/.profile to include /mnt/nv/bin in the PATH for easier manual troubleshooting via SSH.

• Idempotent Patching: The service uses explicit markers to inject the hook, ensuring it doesn’t corrupt existing content.
• Coexistence: The service-injected hook is designed to coexist with a manually installed rc.local (e.g., from the community gist). It only adds a call to /mnt/nv/bin/spotify-boot-primer if it’s not already managed by a service-controlled block.
• Markers: Look for the following markers in your speaker’s /mnt/nv/rc.local:
  • # --- Aftertouch Spotify hook START ---
  • # --- Aftertouch Spotify hook END ---
• Cleanup: Reverting a migration via the service will cleanly remove these marker-delimited blocks.

Endpoints

Method	Path	Auth	Purpose
POST	/mgmt/devices/{deviceId}/spotify/install-primer	Basic	Install Spotify boot primer on speaker (deviceId or IP)
GET	/mgmt/spotify/callback	None	Browser OAuth callback (redirect from Spotify, returns HTML)
POST	/mgmt/spotify/init	Basic	Start OAuth flow, returns authorization URL
POST	/mgmt/spotify/confirm	Basic	Mobile app confirm (ueberboese deep link delivers code, returns JSON)
GET	/mgmt/spotify/accounts	Basic	List linked Spotify accounts (tokens stripped)
GET	/mgmt/spotify/token	Basic	Get fresh access token (auto-refreshes if expired)
POST	/mgmt/spotify/entity	Basic	Resolve Spotify URI to name + image URL

Security

• /mgmt/spotify/callback is intentionally outside Basic Auth to allow direct redirects from Spotify’s authorization server.
• All other /mgmt/* endpoints require Basic Auth as configured by --mgmt-username and --mgmt-password.
• Tokens are persisted to disk as JSON with restricted file permissions (0600).
• The GetAccounts endpoint strips sensitive tokens from the response.