From 00ff054565b761ca00a4fb4d306f08eba731cdcf Mon Sep 17 00:00:00 2001 From: AppVeyor Doc Generation Date: Mon, 18 Mar 2019 16:21:19 +0000 Subject: [PATCH] Built docs | AppVeyor Build 375 --- SpotifyWebAPI/auth/index.html | 105 ++++++++++++++++++++++++++++++++-- mkdocs/search_index.json | 31 +++++++++- sitemap.xml | 34 +++++------ 3 files changed, 145 insertions(+), 25 deletions(-) diff --git a/SpotifyWebAPI/auth/index.html b/SpotifyWebAPI/auth/index.html index aaed6734..4d40c277 100644 --- a/SpotifyWebAPI/auth/index.html +++ b/SpotifyWebAPI/auth/index.html @@ -169,6 +169,8 @@
  • ImplicitGrantAuth
    • +
  • TokenSwapAuth
    • +
  • AutorizationCodeAuth
  • ClientCredentialsAuth
    • @@ -189,16 +191,19 @@ If you want to know more, you can read to the whole auth-process -

    Now you can start with the User-authentication, Spotify provides 3 ways:

    +

    Now you can start with the user-authentication, Spotify provides 3 ways (4 if you consider different implementations):

    Notes

    @@ -207,8 +212,8 @@ If you want to know more, you can read to the whole auth-process

    After implementing one of the provided auth-methods, you can start doing requests with the token you get from one of the auth-methods.

    ImplicitGrantAuth

    -

    With this approach, you directly get a Token object after the user authed your application. -You won't be able to refresh the token. If you want to use the internal Http server, make sure the redirect URI is in your spotify application redirects.

    +

    This way is recommended and the only auth-process which does not need a server-side exchange of keys. With this approach, you directly get a Token object after the user authed your application. +You won't be able to refresh the token. If you want to use the internal Http server, please add "http://localhost" to your application redirects.

    More info: here

    static async void Main(string[] args)
 {
@@ -225,6 +230,96 @@ You won't be able to refresh the token. If you want to use the internal Http ser
 }
    +

    TokenSwapAuth

    +

    This way uses server-side code or at least access to an exchange server, otherwise, compared to other +methods, it is impossible to use.

    +

    With this approach, you provide the URI/URL to your desired exchange server to perform all necessary +requests to Spotify, as well as requests that return back to the "server URI".

    +

    The exchange server must be able to:

    + +

    The good news is that you do not need to code it yourself.

    +

    The advantages of this method are that the client ID and redirect URI are very well hidden and almost unexposed, but more importantly, your client secret is never exposed and is completely hidden compared to other methods (excluding ImplicitGrantAuth +as it does not deal with a client secret). This means +your Spotify app cannot be spoofed by a malicious third party.

    +

    Using TokenSwapWebAPIFactory

    +

    The TokenSwapWebAPIFactory will create and configure a SpotifyWebAPI object for you.

    +

    It does this through the method GetWebApiAsync asynchronously, which means it will not halt execution of your program while obtaining it for you. If you would like to halt execution, which is synchronous, use GetWebApiAsync().Result without using await.

    +
    TokenSwapWebAPIFactory webApiFactory;
+SpotifyWebAPI spotify;
+
+// You should store a reference to WebAPIFactory if you are using AutoRefresh or want to manually refresh it later on. New WebAPIFactory objects cannot refresh SpotifyWebAPI object that they did not give to you.
+webApiFactory = new TokenSwapWebAPIFactory("INSERT LINK TO YOUR index.php HERE")
+{
+    Scope = Scope.UserReadPrivate | Scope.UserReadEmail | Scope.PlaylistReadPrivate | Scope.UserLibraryRead | Scope.UserReadPrivate | Scope.UserFollowRead | Scope.UserReadBirthdate | Scope.UserTopRead | Scope.PlaylistReadCollaborative | Scope.UserReadRecentlyPlayed | Scope.UserReadPlaybackState | Scope.UserModifyPlaybackState | Scope.PlaylistModifyPublic,
+    AutoRefresh = true
+};
+// You may want to react to being able to use the Spotify service.
+// webApiFactory.OnAuthSuccess += (sender, e) => authorized = true;
+// You may want to react to your user's access expiring.
+// webApiFactory.OnAccessTokenExpired += (sender, e) => authorized = false;
+
+try
+{
+    spotify = await webApiFactory.GetWebApiAsync();
+    // Synchronous way:
+    // spotify = webApiFactory.GetWebApiAsync().Result;
+}
+catch (Exception ex)
+{
+    // Example way to handle error reporting gracefully with your SpotifyWebAPI wrapper
+    // UpdateStatus($"Spotify failed to load: {ex.Message}");
+}
+
    + +

    Using TokenSwapAuth

    +

    Since the TokenSwapWebAPIFactory not only simplifies the whole process but offers additional functionality too +(such as AutoRefresh and AuthSuccess AuthFailure events), use of this way is very verbose and is only +recommended if you are having issues with TokenSwapWebAPIFactory or need access to the tokens.

    +
    TokenSwapAuth auth = new TokenSwapAuth(
+    exchangeServerUri: "INSERT LINK TO YOUR index.php HERE",
+    serverUri: "http://localhost:4002",
+    scope: Scope.UserReadPrivate | Scope.UserReadEmail | Scope.PlaylistReadPrivate | Scope.UserLibraryRead | Scope.UserReadPrivate | Scope.UserFollowRead | Scope.UserReadBirthdate | Scope.UserTopRead | Scope.PlaylistReadCollaborative | Scope.UserReadRecentlyPlayed | Scope.UserReadPlaybackState | Scope.UserModifyPlaybackState | Scope.PlaylistModifyPublic
+);
+auth.AuthReceived += async (sender, response) =>
+{
+    lastToken = await auth.ExchangeCodeAsync(response.Code);
+
+    spotify = new SpotifyWebAPI()
+    {
+        TokenType = lastToken.TokenType,
+        AccessToken = lastToken.AccessToken
+    };
+
+    authenticated = true;
+    auth.Stop();
+};
+auth.OnAccessTokenExpired += async (sender, e) => spotify.AccessToken = (await auth.RefreshAuthAsync(lastToken.RefreshToken)).AccessToken;
+auth.Start();
+auth.OpenBrowser();
+
    + +

    Token Swap Endpoint

    +

    To keep your client secret completely secure and your client ID and redirect URI as secure as possible, use of a web server (such as a php website) is required.

    +

    To use this method, an external HTTP Server (that you may need to create) needs to be able to supply the following HTTP Endpoints to your application:

    +

    /swap - Swaps out an authorization_code with an access_token and refresh_token - The following parameters are required in the JSON POST Body: +- grant_type (set to "authorization_code") +- code (the authorization_code) +- redirect_uri +- - Important The page that the redirect URI links to must return the authorization code json to your serverUri (default is 'http://localhost:4002') but to the folder 'auth', like this: 'http://localhost:4002/auth'.

    +

    /refresh - Refreshes an access_token - The following parameters are required in the JSON POST Body: +- grant_type (set to "refresh_token") +- refresh_token

    +

    The following open-source token swap endpoint code can be used for your website: +- rollersteaam/spotify-token-swap-php +- simontaen/SpotifyTokenSwap

    +

    Remarks

    +

    It should be noted that GitHub Pages does not support hosting php scripts. Hosting php scripts through it will cause the php to render as plain HTML, potentially compromising your client secret while doing absolutely nothing.

    +

    Be sure you have whitelisted your redirect uri in the Spotify Developer Dashboard otherwise the authorization will always fail.

    +

    If you did not use the WebAPIFactory or you provided a serverUri different from its default, you must make sure your redirect uri's script at your endpoint will properly redirect to your serverUri (such as changing the areas which refer to localhost:4002 if you had changed serverUri from its default), otherwise it will never reach your new serverUri.

    AutorizationCodeAuth

    This way is not recommended and requires server-side code to run securely. With this approach, you first get a code which you need to trade against the access-token. diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json index 350c273f..8423b0e6 100644 --- a/mkdocs/search_index.json +++ b/mkdocs/search_index.json @@ -522,12 +522,12 @@ }, { "location": "/SpotifyWebAPI/auth/", - "text": "Auth-Methods\n\n\nBefore you can use the Web API full functional, you need the user to authenticate your Application.\nIf you want to know more, you can read to the whole auth-process \nhere\n.\n\n\nBefore you start, install \nSpotifyAPI.Web.Auth\n and create an application at Spotify: \nYour Applications\n\n\n\n\nAfter you created your Application, you will have following important values:\n\n\n\n\nClient_Id\n: This is your client_id, you don't have to hide it\n\nClient_Secret\n: Never use this in one of your client-side apps!! Keep it secret!\n\nRedirect URIs\n: Add \"http://localhost\", if you want full support for this API\n\n\n\n\nNow you can start with the User-authentication, Spotify provides 3 ways:\n\n\n\n\n\n\nImplicitGrantAuth\n\n\n\n\n\n\nAutorizationCodeAuth\n\n\n\n\n\n\nClientCredentialsAuth\n\n\n\n\n\n\nNotes\n\n\nGenerally, if you're developing a 100% client-side application, no auth mechanism is totally secure. \nAutorizationCodeAuth\n and \nClientCredentialsAuth\n require your clients to know the \nclient_secret\n, which should be kept secret. For \nImplicitGrantAuth\n to work, \nhttp://localhost\n needs to be added to the redirect uris of your spotify application. Since \nlocalhost\n is not a controlled domain by you, everybody is able to generate API-Keys. However, it is still the best option of all 3.\n\n\nOverview:\n\n\n\nAfter implementing one of the provided auth-methods, you can start doing requests with the token you get from one of the auth-methods.\n\n\nImplicitGrantAuth\n\n\nWith this approach, you directly get a Token object after the user authed your application.\nYou won't be able to refresh the token. If you want to use the internal Http server, make sure the redirect URI is in your spotify application redirects.\n\n\nMore info: \nhere\n\n\nstatic async void Main(string[] args)\n{\n ImplicitGrantAuth auth =\n new ImplicitGrantAuth(_clientId, \nhttp://localhost:4002\n, \nhttp://localhost:4002\n, Scope.UserReadPrivate);\n auth.AuthReceived += async (sender, payload) =\n\n {\n auth.Stop(); // `sender` is also the auth instance\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = payload.TokenType, AccessToken = payload.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}\n\n\n\n\nAutorizationCodeAuth\n\n\nThis way is \nnot recommended\n and requires server-side code to run securely.\nWith this approach, you first get a code which you need to trade against the access-token.\nIn this exchange you need to provide your Client-Secret and because of that it's not recommended.\nA good thing about this method: You can always refresh your token, without having the user to auth it again\n\n\nMore info: \nhere\n\n\nstatic async void Main(string[] args)\n{\n AuthorizationCodeAuth auth =\n new AuthorizationCodeAuth(_clientId, _secretId, \nhttp://localhost:4002\n, \nhttp://localhost:4002\n,\n Scope.PlaylistReadPrivate | Scope.PlaylistReadCollaborative);\n auth.AuthReceived += async (sender, payload) =\n\n {\n auth.Stop();\n Token token = await auth.ExchangeCode(payload.Code);\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = token.TokenType, AccessToken = token.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}\n\n\n\n\nClientCredentialsAuth\n\n\nWith this approach, you make a POST Request with a base64 encoded string (consists of ClientId + ClientSecret). You will directly get the token (Without a local HTTP Server), but it will expire and can't be refreshed.\nIf you want to use it securely, you would need to do it all server-side.\n\nNOTE:\n You will only be able to query non-user-related information e.g search for a Track.\n\n\nMore info: \nhere\n\n\nCredentialsAuth auth = new CredentialsAuth(_clientId, _secretId);\nToken token = await auth.GetToken();\nSpotifyWebAPI api = new SpotifyWebAPI() {TokenType = token.TokenType, AccessToken = token.AccessToken};", + "text": "Auth-Methods\n\n\nBefore you can use the Web API full functional, you need the user to authenticate your Application.\nIf you want to know more, you can read to the whole auth-process \nhere\n.\n\n\nBefore you start, install \nSpotifyAPI.Web.Auth\n and create an application at Spotify: \nYour Applications\n\n\n\n\nAfter you created your Application, you will have following important values:\n\n\n\n\nClient_Id\n: This is your client_id, you don't have to hide it\n\nClient_Secret\n: Never use this in one of your client-side apps!! Keep it secret!\n\nRedirect URIs\n: Add \"http://localhost\", if you want full support for this API\n\n\n\n\nNow you can start with the user-authentication, Spotify provides 3 ways (4 if you consider different implementations):\n\n\n\n\n\n\nImplicitGrantAuth\n\n\n\n\n\n\nTokenSwapAuth\n (\nRecommended\n, server-side code mandatory, most secure method. The necessary code is shown here so you do not have to code it yourself.)\n\n\n\n\n\n\nAutorizationCodeAuth\n (Not recommended, server-side code needed, else it's unsecure)\n\n\n\n\n\n\nClientCredentialsAuth\n (Not recommended, server-side code needed, else it's unsecure)\n\n\n\n\n\n\nNotes\n\n\nGenerally, if you're developing a 100% client-side application, no auth mechanism is totally secure. \nAutorizationCodeAuth\n and \nClientCredentialsAuth\n require your clients to know the \nclient_secret\n, which should be kept secret. For \nImplicitGrantAuth\n to work, \nhttp://localhost\n needs to be added to the redirect uris of your spotify application. Since \nlocalhost\n is not a controlled domain by you, everybody is able to generate API-Keys. However, it is still the best option of all 3.\n\n\nOverview:\n\n\n\nAfter implementing one of the provided auth-methods, you can start doing requests with the token you get from one of the auth-methods.\n\n\nImplicitGrantAuth\n\n\nThis way is \nrecommended\n and the only auth-process which does not need a server-side exchange of keys. With this approach, you directly get a Token object after the user authed your application.\nYou won't be able to refresh the token. If you want to use the internal Http server, please add \"http://localhost\" to your application redirects.\n\n\nMore info: \nhere\n\n\nstatic async void Main(string[] args)\n{\n ImplicitGrantAuth auth =\n new ImplicitGrantAuth(_clientId, \nhttp://localhost:4002\n, \nhttp://localhost:4002\n, Scope.UserReadPrivate);\n auth.AuthReceived += async (sender, payload) =\n\n {\n auth.Stop(); // `sender` is also the auth instance\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = payload.TokenType, AccessToken = payload.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}\n\n\n\n\nTokenSwapAuth\n\n\nThis way uses server-side code or at least access to an exchange server, otherwise, compared to other\nmethods, it is impossible to use.\n\n\nWith this approach, you provide the URI/URL to your desired exchange server to perform all necessary\nrequests to Spotify, as well as requests that return back to the \"server URI\".\n\n\nThe exchange server \nmust\n be able to:\n\n\n\n\nReturn the authorization code from Spotify API authenticate page via GET request to the \"server URI\".\n\n\nRequest the token response object via POST to the Spotify API token page.\n\n\nRequest a refreshed token response object via POST to the Spotify API token page.\n\n\n\n\nThe good news is that you do not need to code it yourself.\n\n\nThe advantages of this method are that the client ID and redirect URI are very well hidden and almost unexposed, but more importantly, your client secret is \nnever\n exposed and is completely hidden compared to other methods (excluding \nImplicitGrantAuth\n\nas it does not deal with a client secret). This means\nyour Spotify app \ncannot\n be spoofed by a malicious third party.\n\n\nUsing TokenSwapWebAPIFactory\n\n\nThe TokenSwapWebAPIFactory will create and configure a SpotifyWebAPI object for you.\n\n\nIt does this through the method GetWebApiAsync \nasynchronously\n, which means it will not halt execution of your program while obtaining it for you. If you would like to halt execution, which is \nsynchronous\n, use \nGetWebApiAsync().Result\n without using \nawait\n.\n\n\nTokenSwapWebAPIFactory webApiFactory;\nSpotifyWebAPI spotify;\n\n// You should store a reference to WebAPIFactory if you are using AutoRefresh or want to manually refresh it later on. New WebAPIFactory objects cannot refresh SpotifyWebAPI object that they did not give to you.\nwebApiFactory = new TokenSwapWebAPIFactory(\nINSERT LINK TO YOUR index.php HERE\n)\n{\n Scope = Scope.UserReadPrivate | Scope.UserReadEmail | Scope.PlaylistReadPrivate | Scope.UserLibraryRead | Scope.UserReadPrivate | Scope.UserFollowRead | Scope.UserReadBirthdate | Scope.UserTopRead | Scope.PlaylistReadCollaborative | Scope.UserReadRecentlyPlayed | Scope.UserReadPlaybackState | Scope.UserModifyPlaybackState | Scope.PlaylistModifyPublic,\n AutoRefresh = true\n};\n// You may want to react to being able to use the Spotify service.\n// webApiFactory.OnAuthSuccess += (sender, e) =\n authorized = true;\n// You may want to react to your user's access expiring.\n// webApiFactory.OnAccessTokenExpired += (sender, e) =\n authorized = false;\n\ntry\n{\n spotify = await webApiFactory.GetWebApiAsync();\n // Synchronous way:\n // spotify = webApiFactory.GetWebApiAsync().Result;\n}\ncatch (Exception ex)\n{\n // Example way to handle error reporting gracefully with your SpotifyWebAPI wrapper\n // UpdateStatus($\nSpotify failed to load: {ex.Message}\n);\n}\n\n\n\n\nUsing TokenSwapAuth\n\n\nSince the TokenSwapWebAPIFactory not only simplifies the whole process but offers additional functionality too\n(such as AutoRefresh and AuthSuccess AuthFailure events), use of this way is very verbose and is only\nrecommended if you are having issues with TokenSwapWebAPIFactory or need access to the tokens.\n\n\nTokenSwapAuth auth = new TokenSwapAuth(\n exchangeServerUri: \nINSERT LINK TO YOUR index.php HERE\n,\n serverUri: \nhttp://localhost:4002\n,\n scope: Scope.UserReadPrivate | Scope.UserReadEmail | Scope.PlaylistReadPrivate | Scope.UserLibraryRead | Scope.UserReadPrivate | Scope.UserFollowRead | Scope.UserReadBirthdate | Scope.UserTopRead | Scope.PlaylistReadCollaborative | Scope.UserReadRecentlyPlayed | Scope.UserReadPlaybackState | Scope.UserModifyPlaybackState | Scope.PlaylistModifyPublic\n);\nauth.AuthReceived += async (sender, response) =\n\n{\n lastToken = await auth.ExchangeCodeAsync(response.Code);\n\n spotify = new SpotifyWebAPI()\n {\n TokenType = lastToken.TokenType,\n AccessToken = lastToken.AccessToken\n };\n\n authenticated = true;\n auth.Stop();\n};\nauth.OnAccessTokenExpired += async (sender, e) =\n spotify.AccessToken = (await auth.RefreshAuthAsync(lastToken.RefreshToken)).AccessToken;\nauth.Start();\nauth.OpenBrowser();\n\n\n\n\nToken Swap Endpoint\n\n\nTo keep your client secret completely secure and your client ID and redirect URI as secure as possible, use of a web server (such as a php website) is required.\n\n\nTo use this method, an external HTTP Server (that you may need to create) needs to be able to supply the following HTTP Endpoints to your application:\n\n\n/swap\n - Swaps out an \nauthorization_code\n with an \naccess_token\n and \nrefresh_token\n - The following parameters are required in the JSON POST Body:\n- \ngrant_type\n (set to \n\"authorization_code\"\n)\n- \ncode\n (the \nauthorization_code\n)\n- \nredirect_uri\n\n- - \nImportant\n The page that the redirect URI links to must return the authorization code json to your \nserverUri\n (default is 'http://localhost:4002') but to the folder 'auth', like this: 'http://localhost:4002/auth'.\n\n\n/refresh\n - Refreshes an \naccess_token\n - The following parameters are required in the JSON POST Body:\n- \ngrant_type\n (set to \n\"refresh_token\"\n)\n- \nrefresh_token\n\n\nThe following open-source token swap endpoint code can be used for your website:\n- \nrollersteaam/spotify-token-swap-php\n\n- \nsimontaen/SpotifyTokenSwap\n\n\nRemarks\n\n\nIt should be noted that GitHub Pages does not support hosting php scripts. Hosting php scripts through it will cause the php to render as plain HTML, potentially compromising your client secret while doing absolutely nothing.\n\n\nBe sure you have whitelisted your redirect uri in the Spotify Developer Dashboard otherwise the authorization will always fail.\n\n\nIf you did not use the WebAPIFactory or you provided a \nserverUri\n different from its default, you must make sure your redirect uri's script at your endpoint will properly redirect to your \nserverUri\n (such as changing the areas which refer to \nlocalhost:4002\n if you had changed \nserverUri\n from its default), otherwise it will never reach your new \nserverUri\n.\n\n\nAutorizationCodeAuth\n\n\nThis way is \nnot recommended\n and requires server-side code to run securely.\nWith this approach, you first get a code which you need to trade against the access-token.\nIn this exchange you need to provide your Client-Secret and because of that it's not recommended.\nA good thing about this method: You can always refresh your token, without having the user to auth it again\n\n\nMore info: \nhere\n\n\nstatic async void Main(string[] args)\n{\n AuthorizationCodeAuth auth =\n new AuthorizationCodeAuth(_clientId, _secretId, \nhttp://localhost:4002\n, \nhttp://localhost:4002\n,\n Scope.PlaylistReadPrivate | Scope.PlaylistReadCollaborative);\n auth.AuthReceived += async (sender, payload) =\n\n {\n auth.Stop();\n Token token = await auth.ExchangeCode(payload.Code);\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = token.TokenType, AccessToken = token.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}\n\n\n\n\nClientCredentialsAuth\n\n\nWith this approach, you make a POST Request with a base64 encoded string (consists of ClientId + ClientSecret). You will directly get the token (Without a local HTTP Server), but it will expire and can't be refreshed.\nIf you want to use it securely, you would need to do it all server-side.\n\nNOTE:\n You will only be able to query non-user-related information e.g search for a Track.\n\n\nMore info: \nhere\n\n\nCredentialsAuth auth = new CredentialsAuth(_clientId, _secretId);\nToken token = await auth.GetToken();\nSpotifyWebAPI api = new SpotifyWebAPI() {TokenType = token.TokenType, AccessToken = token.AccessToken};", "title": "SpotifyAPI.Web.Auth" }, { "location": "/SpotifyWebAPI/auth/#auth-methods", - "text": "Before you can use the Web API full functional, you need the user to authenticate your Application.\nIf you want to know more, you can read to the whole auth-process here . Before you start, install SpotifyAPI.Web.Auth and create an application at Spotify: Your Applications After you created your Application, you will have following important values: Client_Id : This is your client_id, you don't have to hide it Client_Secret : Never use this in one of your client-side apps!! Keep it secret! Redirect URIs : Add \"http://localhost\", if you want full support for this API Now you can start with the User-authentication, Spotify provides 3 ways: ImplicitGrantAuth AutorizationCodeAuth ClientCredentialsAuth", + "text": "Before you can use the Web API full functional, you need the user to authenticate your Application.\nIf you want to know more, you can read to the whole auth-process here . Before you start, install SpotifyAPI.Web.Auth and create an application at Spotify: Your Applications After you created your Application, you will have following important values: Client_Id : This is your client_id, you don't have to hide it Client_Secret : Never use this in one of your client-side apps!! Keep it secret! Redirect URIs : Add \"http://localhost\", if you want full support for this API Now you can start with the user-authentication, Spotify provides 3 ways (4 if you consider different implementations): ImplicitGrantAuth TokenSwapAuth ( Recommended , server-side code mandatory, most secure method. The necessary code is shown here so you do not have to code it yourself.) AutorizationCodeAuth (Not recommended, server-side code needed, else it's unsecure) ClientCredentialsAuth (Not recommended, server-side code needed, else it's unsecure)", "title": "Auth-Methods" }, { @@ -537,9 +537,34 @@ }, { "location": "/SpotifyWebAPI/auth/#implicitgrantauth", - "text": "With this approach, you directly get a Token object after the user authed your application.\nYou won't be able to refresh the token. If you want to use the internal Http server, make sure the redirect URI is in your spotify application redirects. More info: here static async void Main(string[] args)\n{\n ImplicitGrantAuth auth =\n new ImplicitGrantAuth(_clientId, http://localhost:4002 , http://localhost:4002 , Scope.UserReadPrivate);\n auth.AuthReceived += async (sender, payload) = \n {\n auth.Stop(); // `sender` is also the auth instance\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = payload.TokenType, AccessToken = payload.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}", + "text": "This way is recommended and the only auth-process which does not need a server-side exchange of keys. With this approach, you directly get a Token object after the user authed your application.\nYou won't be able to refresh the token. If you want to use the internal Http server, please add \"http://localhost\" to your application redirects. More info: here static async void Main(string[] args)\n{\n ImplicitGrantAuth auth =\n new ImplicitGrantAuth(_clientId, http://localhost:4002 , http://localhost:4002 , Scope.UserReadPrivate);\n auth.AuthReceived += async (sender, payload) = \n {\n auth.Stop(); // `sender` is also the auth instance\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = payload.TokenType, AccessToken = payload.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}", "title": "ImplicitGrantAuth" }, + { + "location": "/SpotifyWebAPI/auth/#tokenswapauth", + "text": "This way uses server-side code or at least access to an exchange server, otherwise, compared to other\nmethods, it is impossible to use. With this approach, you provide the URI/URL to your desired exchange server to perform all necessary\nrequests to Spotify, as well as requests that return back to the \"server URI\". The exchange server must be able to: Return the authorization code from Spotify API authenticate page via GET request to the \"server URI\". Request the token response object via POST to the Spotify API token page. Request a refreshed token response object via POST to the Spotify API token page. The good news is that you do not need to code it yourself. The advantages of this method are that the client ID and redirect URI are very well hidden and almost unexposed, but more importantly, your client secret is never exposed and is completely hidden compared to other methods (excluding ImplicitGrantAuth \nas it does not deal with a client secret). This means\nyour Spotify app cannot be spoofed by a malicious third party.", + "title": "TokenSwapAuth" + }, + { + "location": "/SpotifyWebAPI/auth/#using-tokenswapwebapifactory", + "text": "The TokenSwapWebAPIFactory will create and configure a SpotifyWebAPI object for you. It does this through the method GetWebApiAsync asynchronously , which means it will not halt execution of your program while obtaining it for you. If you would like to halt execution, which is synchronous , use GetWebApiAsync().Result without using await . TokenSwapWebAPIFactory webApiFactory;\nSpotifyWebAPI spotify;\n\n// You should store a reference to WebAPIFactory if you are using AutoRefresh or want to manually refresh it later on. New WebAPIFactory objects cannot refresh SpotifyWebAPI object that they did not give to you.\nwebApiFactory = new TokenSwapWebAPIFactory( INSERT LINK TO YOUR index.php HERE )\n{\n Scope = Scope.UserReadPrivate | Scope.UserReadEmail | Scope.PlaylistReadPrivate | Scope.UserLibraryRead | Scope.UserReadPrivate | Scope.UserFollowRead | Scope.UserReadBirthdate | Scope.UserTopRead | Scope.PlaylistReadCollaborative | Scope.UserReadRecentlyPlayed | Scope.UserReadPlaybackState | Scope.UserModifyPlaybackState | Scope.PlaylistModifyPublic,\n AutoRefresh = true\n};\n// You may want to react to being able to use the Spotify service.\n// webApiFactory.OnAuthSuccess += (sender, e) = authorized = true;\n// You may want to react to your user's access expiring.\n// webApiFactory.OnAccessTokenExpired += (sender, e) = authorized = false;\n\ntry\n{\n spotify = await webApiFactory.GetWebApiAsync();\n // Synchronous way:\n // spotify = webApiFactory.GetWebApiAsync().Result;\n}\ncatch (Exception ex)\n{\n // Example way to handle error reporting gracefully with your SpotifyWebAPI wrapper\n // UpdateStatus($ Spotify failed to load: {ex.Message} );\n}", + "title": "Using TokenSwapWebAPIFactory" + }, + { + "location": "/SpotifyWebAPI/auth/#using-tokenswapauth", + "text": "Since the TokenSwapWebAPIFactory not only simplifies the whole process but offers additional functionality too\n(such as AutoRefresh and AuthSuccess AuthFailure events), use of this way is very verbose and is only\nrecommended if you are having issues with TokenSwapWebAPIFactory or need access to the tokens. TokenSwapAuth auth = new TokenSwapAuth(\n exchangeServerUri: INSERT LINK TO YOUR index.php HERE ,\n serverUri: http://localhost:4002 ,\n scope: Scope.UserReadPrivate | Scope.UserReadEmail | Scope.PlaylistReadPrivate | Scope.UserLibraryRead | Scope.UserReadPrivate | Scope.UserFollowRead | Scope.UserReadBirthdate | Scope.UserTopRead | Scope.PlaylistReadCollaborative | Scope.UserReadRecentlyPlayed | Scope.UserReadPlaybackState | Scope.UserModifyPlaybackState | Scope.PlaylistModifyPublic\n);\nauth.AuthReceived += async (sender, response) = \n{\n lastToken = await auth.ExchangeCodeAsync(response.Code);\n\n spotify = new SpotifyWebAPI()\n {\n TokenType = lastToken.TokenType,\n AccessToken = lastToken.AccessToken\n };\n\n authenticated = true;\n auth.Stop();\n};\nauth.OnAccessTokenExpired += async (sender, e) = spotify.AccessToken = (await auth.RefreshAuthAsync(lastToken.RefreshToken)).AccessToken;\nauth.Start();\nauth.OpenBrowser();", + "title": "Using TokenSwapAuth" + }, + { + "location": "/SpotifyWebAPI/auth/#token-swap-endpoint", + "text": "To keep your client secret completely secure and your client ID and redirect URI as secure as possible, use of a web server (such as a php website) is required. To use this method, an external HTTP Server (that you may need to create) needs to be able to supply the following HTTP Endpoints to your application: /swap - Swaps out an authorization_code with an access_token and refresh_token - The following parameters are required in the JSON POST Body:\n- grant_type (set to \"authorization_code\" )\n- code (the authorization_code )\n- redirect_uri \n- - Important The page that the redirect URI links to must return the authorization code json to your serverUri (default is 'http://localhost:4002') but to the folder 'auth', like this: 'http://localhost:4002/auth'. /refresh - Refreshes an access_token - The following parameters are required in the JSON POST Body:\n- grant_type (set to \"refresh_token\" )\n- refresh_token The following open-source token swap endpoint code can be used for your website:\n- rollersteaam/spotify-token-swap-php \n- simontaen/SpotifyTokenSwap", + "title": "Token Swap Endpoint" + }, + { + "location": "/SpotifyWebAPI/auth/#remarks", + "text": "It should be noted that GitHub Pages does not support hosting php scripts. Hosting php scripts through it will cause the php to render as plain HTML, potentially compromising your client secret while doing absolutely nothing. Be sure you have whitelisted your redirect uri in the Spotify Developer Dashboard otherwise the authorization will always fail. If you did not use the WebAPIFactory or you provided a serverUri different from its default, you must make sure your redirect uri's script at your endpoint will properly redirect to your serverUri (such as changing the areas which refer to localhost:4002 if you had changed serverUri from its default), otherwise it will never reach your new serverUri .", + "title": "Remarks" + }, { "location": "/SpotifyWebAPI/auth/#autorizationcodeauth", "text": "This way is not recommended and requires server-side code to run securely.\nWith this approach, you first get a code which you need to trade against the access-token.\nIn this exchange you need to provide your Client-Secret and because of that it's not recommended.\nA good thing about this method: You can always refresh your token, without having the user to auth it again More info: here static async void Main(string[] args)\n{\n AuthorizationCodeAuth auth =\n new AuthorizationCodeAuth(_clientId, _secretId, http://localhost:4002 , http://localhost:4002 ,\n Scope.PlaylistReadPrivate | Scope.PlaylistReadCollaborative);\n auth.AuthReceived += async (sender, payload) = \n {\n auth.Stop();\n Token token = await auth.ExchangeCode(payload.Code);\n SpotifyWebAPI api = new SpotifyWebAPI() {TokenType = token.TokenType, AccessToken = token.AccessToken};\n // Do requests with API client\n };\n auth.Start(); // Starts an internal HTTP Server\n auth.OpenBrowser();\n}", diff --git a/sitemap.xml b/sitemap.xml index 4f1ae176..a5fa5c01 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -4,7 +4,7 @@ / - 2019-03-16 + 2019-03-18 daily @@ -13,91 +13,91 @@ /SpotifyWebAPI/gettingstarted/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/examples/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/proxy/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/albums/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/artists/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/browse/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/follow/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/library/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/personalization/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/player/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/playlists/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/profiles/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/search/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/tracks/ - 2019-03-16 + 2019-03-18 daily /SpotifyWebAPI/util/ - 2019-03-16 + 2019-03-18 daily @@ -106,7 +106,7 @@ /SpotifyWebAPI/auth/ - 2019-03-16 + 2019-03-18 daily