Update Spotify integration auth information (#23613)

source/_integrations/spotify.markdown

@@ -16,45 +16,76 @@ ha_platforms:
 ha_integration_type: integration
 ---
 
-The Spotify media player integration allows you to control [Spotify](https://www.spotify.com/) playback from Home Assistant.
+The Spotify media player integration lets you control your Spotify
+account playback and browse the [Spotify](https://www.spotify.com/) media
+library from Home Assistant.
 
 ## Prerequisites
 
-- Spotify account
+- An active Spotify account. A premium is not required, but recommended.
-- (Optional) Spotify developer application configured for Home Assistant (see [below](#create-a-spotify-application))
+  Premium accounts can be controlled (pause, play, next, etc.), while
+  free accounts can only be used for browsing and current playback status.
 - Spotify compatible playback [source](#selecting-output-source) device
-
+- A Spotify Developer application. Instructions for that are in
-<div class='note'>
+  the next step.
-  Spotify integrated media controls (pause, play, next, etc.) require a Premium account.
+ 
-  If you do not have a Premium account, the frontend will not show the controls.
-</div>
-
-{% include integrations/config_flow.md %}
-
-Unless configured otherwise, Home Assistant will use account linking provided by
-Nabu Casa for authenticating with Spotify. If this is not working or you don't
-want to use it, follow the steps for configuring a [developer application](#create-a-spotify-application)
-before configuring Spotify.
-
-<div class='note'>
-
-  If you receive an `INVALID_CLIENT: Invalid redirect URI` error while trying to
-  authenticate with your Spotify account, check the Redirect URI in
-  the address bar after adding the new integration. Compare this value with the
-  Redirect URI defined in the Spotify Developer Portal.
-
-</div>
-
 ### Create a Spotify application
 
-- Login to [Spotify Developer](https://developer.spotify.com) via Dashboard.
+For Home Assistant to communicate with Spotify, we need to create
-- Visit the [My Applications](https://developer.spotify.com/my-applications/#!/applications) page.
+an application at Spotify using the Spotify Developer website. This will
-- Select **Create An App**. Enter any name and description.
+provide you with the Spotify application credentials Home Assistant needs
-- Once your application is created, view it and copy your **Client ID** and **Client Secret**, which are used in the Home Assistant [configuration file below](#configuration).
+to allow you to log in with your Spotify account.
-- Enter the **Edit Settings** dialog of your newly-created application and add a *Redirect URI*:
+
-  `https://my.home-assistant.io/redirect/oauth`.
+1. Log in to the [Spotify Developer](https://developer.spotify.com) Dashboard.
-  Note: Spotify does a case-sensitive match of the fields above, as such ensure the Redirect URI is all lower case.
+2. Visit the [My Applications](https://developer.spotify.com/my-applications/#!/applications) page.
-- Click **Save** after adding the URI.
+3. Click the **CREATE AN APP** button in the top right. Enter a name and
+   description; feel free to use any name and description you like.
+
+  ![Creating a Spotify Application](/images/integrations/spotify/create-spotify-application.png)
+
+4. Check the box to agree with the requirements and click the **CREATE** button
+   to confirm the application creation.
+5. Spotify will now show the new application you have just created. Click on
+   the **EDIT SETTINGS** button to configure it. You will  need to make a final
+   adjustment to this new application for it to work correctly.
+
+  ![Edit the Spotify Application settings](/images/integrations/spotify/edit-settings.png)
+
+6. Next, we need to set the _"Redirect URI"_ to the following:
+   
+   `https://my.home-assistant.io/redirect/oauth`
+
+   Please copy and paste the exact URL above. You **do not** have to change it.
+
+  ![Add a redirect URI to the Spotify Application](/images/integrations/spotify/redirect-uri.png)
+
+  Enter the above redirect URL into the _"Redirect URI"_  field (marked as 1).
+  and be sure to press the **ADD** button (marked as 2).
+
+7. Save the application settings by scrolling down the current page and
+   clicking the **SAVE** button at the bottom left.
+
+  ![Make sure to save the Spotify Application settings changes](/images/integrations/spotify/save-application.png)
+
+8. You now have successfully created a Spotify application! Before we
+   can start configuring Home Assistant, we need to grab the application
+   credentials Home Assistant needs.
+
+  Click on the **SHOW CLIENT SECRET** button to reveal the client secret.
+
+  ![Show the client secret of the Spotify Application](/images/integrations/spotify/show-client-secret.png)
+
+9. The _"Client ID"_ and _"Client Secret"_ are the two pieces of information
+   that Home Assistant needs to communicate with Spotify and is what we
+   call: Application credentials.
+
+  ![Get the application credentials from the Spotify Application](/images/integrations/spotify/application-credentials.png)
+
+   You will need the _"Client ID"_ and _"Client Secret"_ during the Spotify
+   integration setup process in Home Assistant.
+
+You can now continue with the next chapter to configure the Spotify integration
+in Home Assistant.
 
 {% details "I have manually disabled My Home Assistant" %}
 
@@ -69,17 +100,20 @@ Internal examples: `http://192.168.0.2:8123/auth/external/callback`, `http://hom
 
 {% enddetails %}
 
-See [Application Credentials](/integrations/application_credentials) for instructions on how to configure your *Client ID* and *Client Secret*.
+{% include integrations/config_flow.md %}
 
 ## Using multiple Spotify accounts
 
 This integration supports multiple Spotify accounts at once. You don't need to
-create another Spotify application in the Spotify Developer Portal and no
+create another Spotify application in the Spotify Developer Portal.
-modification to the `configuration.yaml` file is needed. Multiple Spotify
+Multiple Spotify accounts can be linked to a _single_ Spotify application.
-accounts can be linked to a _single_ Spotify application. You will have to add those accounts into the **Users and Access** section of your application in the Spotify Developer Portal.
 
-To add an additional Spotify account to Home Assistant, go to the Spotify website and log out, then repeat _only_ the steps
+You will have to add those accounts into the **Users and Access** section of
-in the [Configuration](#configuration) section. 
+your application in the Spotify Developer Portal.
+
+To add an additional Spotify account to Home Assistant, go to the Spotify
+website, log out, and then repeat _only_ the steps in the
+[Configuration](#configuration) section. 
 
 ## Selecting output source