Spotify Account Addition Technical Reference

This document details the exact network requests performed by the Bose SoundTouch “Stockholm” application and the SoundTouch speaker when adding a new Spotify account. This information is based on analysis of the Stockholm firmware version 27.0.13-4277-8963611.

Flow Overview

1. User Authorization Initiation: The app opens the system browser to Spotify’s authorization page.
2. Redirect Handling: After authorization, Spotify redirects back to the app via a custom URI scheme, delivering an authorization code.
3. OAuth Token Exchange: The app sends this code to the background worker, which exchanges it for a Bose-mediated token.
4. Cloud Source Registration: The app registers the Spotify account as a “source” in the user’s Bose Cloud (Marge) profile.
5. Local Device Sync: The app notifies the local SoundTouch speaker about the new source, which then updates its internal configuration.

0. User Authorization Initiation

The process begins in the Stockholm UI when the user selects Spotify to add a new account.

Request Details (App to Browser)

• Action: Open System Browser
• Base URL: [SPOTIFY_AUTH_URL] (e.g., https://accounts.spotify.com/authorize)
• Query Parameters:
  • client_id: Bose Spotify Client ID
  • response_type: code
  • redirect_uri: http://localhost (often used as a placeholder or specifically handled by the app’s internal webview/proxy)
  • scope: user-read-private user-read-email ...
  • state: A base64-encoded JSON object containing metadata, e.g., {"service": "SPOTIFY"}.

Redirect (Browser to App)

Upon successful login and authorization, Spotify redirects the browser to a URL that the SoundTouch app intercepts.

• URL Format: soundtouch://bose/musicservice/spotify/login?code=[AUTH_CODE]&state=[STATE]
• App Action: The UIMain component (in ui_main.js) handles this “deep link”. It extracts the code from the query parameters and prepares to send it to the background worker.

1. OAuth Token Exchange (Bose Cloud)

After the UI intercepts the redirect and extracts the code, it sends a createOAuthAccountRequest to the background SpotifyWorker. The worker then performs the exchange for a Bose-mediated token.

What is a “Bose-mediated token”?

The “Bose-mediated token” is a token issued by the Bose OAuth proxy. When the app (or device) requests a token via oauth.streaming.bose.com, Bose’s service performs the actual OAuth2 exchange with Spotify.

• It is not directly a Spotify refresh token: Instead, it is a Bose-issued token that represents the underlying Spotify session.
• Token Version 3: Modern firmware uses token_version_3, which signifies that the device doesn’t store the raw Spotify tokens but instead uses a Bose-specific “secret” that the Bose Cloud uses to fetch fresh Spotify access tokens on the device’s behalf.
• Access vs Refresh: The initial response from the .../token/cs endpoint typically contains an access_token (valid for ~1 hour) and a token_type: "Bearer". The Bose cloud service manages the persistent refresh token internally.

Internal Message (UI to Worker)

• Message Type: createOAuthAccountRequest
• Payload:

  {
    "source": "SPOTIFY",
    "code": "[AUTH_CODE_FROM_REDIRECT]",
    "credentialType": "token_version_3"
  }

Outgoing Request (Worker to Bose OAuth Proxy)

• Endpoint: https://oauth.streaming.bose.com/oauth/account/[ACCOUNT_ID]/music/musicprovider/15/token/cs
• Method: POST
• Headers:
  • Content-Type: application/json
  • Accept: application/json
  • Authorization: Bearer [SESSION_TOKEN] (The user’s Bose account session token)

Payload (JSON)

{
  "grant_type": "authorization_code",
  "code": "[AUTH_CODE_FROM_SPOTIFY]",
  "redirect_uri": "http://localhost"
}

curl Example

curl -X POST "https://oauth.streaming.bose.com/oauth/account/[ACCOUNT_ID]/music/musicprovider/15/token/cs" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer [SESSION_TOKEN]" \
     -d '{
       "grant_type": "authorization_code",
       "code": "[AUTH_CODE_FROM_SPOTIFY]",
       "redirect_uri": "http://localhost"
     }'

2. Cloud Source Registration (Marge)

The app now registers the Spotify account with the Bose “Marge” service. This makes the source available across all devices linked to the same Bose account.

Request Details

• Endpoint: https://streaming.bose.com/streaming/account/[ACCOUNT_ID]/source
• Method: POST
• Headers:
  • Content-Type: application/vnd.bose.streaming-v1.1+xml
  • Authorization: [MARGE_TOKEN]
  • GUID: [DEVICE_GUID]
  • ClientType: Stockholm

Payload (XML)

<?xml version="1.0" encoding="UTF-8"?>
<source>
    <username>[SPOTIFY_USER_ID]</username>
    <sourceproviderid>15</sourceproviderid>
    <credential type="token_version_3">[SECRET_TOKEN_OBTAINED_IN_STEP_1]</credential>
    <sourcename>[DISPLAY_NAME_E_G_EMAIL]</sourcename>
</source>

curl Example

curl -X POST "https://streaming.bose.com/streaming/account/[ACCOUNT_ID]/source" \
     -H "Content-Type: application/vnd.bose.streaming-v1.1+xml" \
     -H "Authorization: [MARGE_TOKEN]" \
     -d '<?xml version="1.0" encoding="UTF-8"?><source><username>[USER]</username><sourceproviderid>15</sourceproviderid><credential type="token_version_3">[TOKEN]</credential><sourcename>[NAME]</sourcename></source>'

Local Device Sync (LISA API)

The app notifies the physical SoundTouch speaker about the new source. This is usually done via the device’s management API on port 8090.

Modern Flow (OAuth)

• Endpoint: http://[DEVICE_IP]:8090/setMusicServiceOAuthAccount
• Method: POST
• Payload:

<OAuthCredentials source="SPOTIFY" displayName="[DISPLAY_NAME]">
    <user>[SPOTIFY_USER_ID]</user>
    <code>[AUTH_CODE_OR_TOKEN]</code>
    <version>token_version_3</version>
</OAuthCredentials>

Marge-Sync Notification (Fall-back)

If the speaker returns 1029 UNKNOWN_ACTION_ERROR, it signifies the LISA API version is too old for the OAuth flow. Stockholm-based firmware often expects the account to be registered in Marge first, followed by a notification to sync.

• Endpoint: http://[DEVICE_IP]:8090/notification
• Method: POST
• Payload:

<updates deviceID="[DEVICE_UID]">
    <sourcesUpdated></sourcesUpdated>
</updates>

Legacy Flow (Fall-back)

For older firmware that doesn’t use Marge for Spotify:

• Endpoint: http://[DEVICE_IP]:8090/setMusicServiceAccount
• Method: POST
• Payload:

<credentials source="SPOTIFY" displayName="Spotify Premium">
    <user>[USER]</user>
    <pass>[TOKEN]</pass>
</credentials>

Implementation in SoundTouch-Service

This project implements the “Bose-mediated token” flow as follows:

1. Surrogate Secrets: When a user links their Spotify account via soundtouch-service, the service generates a 32-character hex string (a “Bose Secret”).
2. Marge & LISA registration: This secret is sent to the speaker and stored in the emulated Marge cloud as the credential. The raw Spotify refresh token never leaves the server.
3. Token Refresh Proxy: When the speaker needs a fresh Spotify access_token, it calls the soundtouch-service proxy (/oauth/device/.../token/cs3) providing this secret. The server maps the secret back to the actual Spotify account, performs the refresh with Spotify, and returns a fresh short-lived access_token to the speaker.

Placeholders and Constants

Resulting Persistence

Once these requests succeed, the device updates its /mnt/nv/BoseApp-Persistence/1/Sources.xml file:

<source displayName="user@example.com" secret="[SECRET_BLOB]" secretType="token_version_3">
    <sourceKey type="SPOTIFY" account="user" />
</source>