Merge pull request #254 from watson-developer-cloud/update-authentication-instructions

Update readme with Allen's suggestions

Author: mediumTaj

README.md

@@ -39,6 +39,76 @@ You can get the latest SDK packages through NuGet. Installation instructions can
 
 Or manually [here][latest_release].
 
+## Authentication
+Watson services are migrating to token-based Identity and Access Management (IAM) authentication.
+
+- With some service instances, you authenticate to the API by using **[IAM](#iam)**.
+- In other instances, you authenticate by providing the **[username and password](#username-and-password)** for the service instance.
+- Visual Recognition uses a form of [API key](#api-key) only with instances created before May 23, 2018. Newer instances of Visual Recognition use [IAM](#iam).
+
+### Getting credentials
+To find out which authentication to use, view the service credentials. You find the service credentials for authentication the same way for all Watson services:
+
+1.  Go to the IBM Cloud **[Dashboard][watson-dashboard]** page.
+1.  Either click an existing Watson service instance or click **Create**.
+1.  Click **Show** to view your service credentials.
+1.  Copy the `url` and either `apikey` or `username` and `password`.
+
+In your code, you can use these values in the service constructor or with a method call after instantiating your service.
+
+### IAM
+
+Some services use token-based Identity and Access Management (IAM) authentication. IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for approximately one hour and must be regenerated.
+
+You supply either an IAM service **API key** or an **access token**:
+
+- Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
+- Use the access token if you want to manage the lifecycle yourself. For details, see [Authenticating with IAM tokens](https://console.bluemix.net/docs/services/watson/getting-started-iam.html). If you want to switch to API key override your stored IAM credentials with an IAM API key.
+
+#### Supplying the IAM API key
+```cs
+void Example()
+{
+    TokenOptions iamAssistantTokenOptions = new TokenOptions()
+    {
+        IamApiKey = "<iam-apikey>",
+        IamUrl = "<service-endpoint>"
+    };
+
+    _assistant = new AssistantService(iamAssistantTokenOptions, "<version-date>");
+}
+```
+
+#### Supplying the access token
+```cs
+void Example()
+{
+    TokenOptions iamAssistantTokenOptions = new TokenOptions()
+    {
+        IamAccessToken = "<iam-access-token>"
+    };
+
+    _assistant = new AssistantService(iamAssistantTokenOptions, "<version-date>");
+}
+```
+
+### Username and password
+```cs
+void Example()
+{
+    _assistant = new AssistantService("<username>", "<password>", "<version-date>");
+}
+```
+
+### API key
+**Important**: This type of authentication works only with Visual Recognition instances created before May 23, 2018. Newer instances of Visual Recognition use [IAM](#iam).
+```cs
+void Example()
+{
+    _visualRecognition = new VisualRecognitionService("<apikey>", "<version-date>");
+}
+```
+
 ## Custom Request Headers
 You can send custom request headers by adding them to the `customData` object.
 ```cs
@@ -72,24 +142,6 @@ void Example()
 }
 ```
 
-## IAM Authentication
-You can authenticate using IAM rather than username and password or apikey. You can either allow the SDK to manage the token by providing your IAM apikey or manage the token yourself by providing an access token.
-```cs
-void Example()
-{
-    //  Provide either an iamApiKey or iamAccessToken to authenticate the service.
-    TokenOptions iamAssistantTokenOptions = new TokenOptions()
-    {
-        IamApiKey = "<iam-apikey>",
-        IamAccessToken = "<iam-access-token>",
-        IamUrl = "<service-endpoint>"
-    };
-
-    _assistant = new AssistantService(iamAssistantTokenOptions, "<version-date>");
-    var results = assistant.Message("<workspace-id>", "<message-request>");
-}
-```
-
 ## Documentation
 Click [here][dotnet-standard-sdk-documentation] for documentation by release and branch.
 

src/IBM.WatsonDeveloperCloud.Assistant.v1/README.md

@@ -26,19 +26,6 @@ You complete these steps to implement your application:
 
 * Develop your application. You code your application to connect to the Assistant workspace through API calls. You then integrate your app with other systems that you need, including back-end systems and third-party services such as chat services or social media.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-// create an Assistant Service instance
-AssistantService _assistant = new AssistantService();
-
-// set the credentials
-_assistant.SetCredential(<username>, <password>);
-
-// set the VersionDate
-_assistant.VersionDate = "<version-date>";
-```
-
 #### List workspaces
 List existing workspaces for the service instance.
 ```cs

src/IBM.WatsonDeveloperCloud.Conversation.v1/README.md

@@ -26,19 +26,6 @@ You complete these steps to implement your application:
 
 * Develop your application. You code your application to connect to the Conversation workspace through API calls. You then integrate your app with other systems that you need, including back-end systems and third-party services such as chat services or social media.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-// create a Conversation Service instance
-ConversationService _conversation = new ConversationService();
-
-// set the credentials
-_conversation.SetCredential(<username>, <password>);
-
-// set the VersionDate
-_conversation.VersionDate = "<version-date>";
-```
-
 #### List workspaces
 List existing workspaces for the service instance.
 ```cs

src/IBM.WatsonDeveloperCloud.Discovery.v1/README.md

@@ -21,19 +21,6 @@ PM > Install-Package IBM.WatsonDeveloperCloud.Discovery.v1
 ### Usage
 The IBM Watson™ [Discovery][discovery] Service uses data analysis combined with cognitive intuition in order to take your unstructured data and enrich it so that you can query it to return the information that you need from it.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-// create a Discovery Service instance
-DiscoveryService _discovery = new DiscoveryService();
-
-// set the credentials
-_discovery.SetCredential("<username>", "<password>");
-
-// set the VersionDate
-_discovery.VersionDate = "<version-date>";
-```
-
 #### Create an environment
 Creates an environment for the service instance. Note: You can create only one environment per service instance. Attempting to create another environment for the same service instance results in an error. See the [Discovery service home page][discovery-sizing] for additional information about sizing and pricing. To create a free trial environment, specify the value of size as 0 (zero).
 ```cs

src/IBM.WatsonDeveloperCloud.LanguageTranslator.v2/README.md

@@ -22,28 +22,6 @@ PM > Install-Package IBM.WatsonDeveloperCloud.LanguageTranslator.v2
 ### Usage
 Select a domain, then identify or select the language of text, and then translate the text from one supported language to another.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and api key or access token must be set.
-```cs
-TokenOptions tokenOptions = new TokenOptions()
-{
-    IamApiKey = "<iam-apikey>",
-    IamAccessToken = "<iam-access-token>",
-    IamUrl = "<service-endpoint>"
-};
-
-var _languageTranslator = new LanguageTranslator(tokenOptions, "<version-date>");
-```
-
-Services created before `2018-06-15` are authenticated using username and password.
-```cs
-// create a Language Translator Service instance
-LanguageTranslationService _languageTranslator = new LanguageTranslationService();
-
-// set the credentials
-_languageTranslator.SetCredential("<username>", "<password>");
-```
-
 #### Translate
 Translates input text from the source language to the target language.
 ```cs

src/IBM.WatsonDeveloperCloud.LanguageTranslator.v3/README.md

@@ -22,19 +22,6 @@ PM > Install-Package IBM.WatsonDeveloperCloud.LanguageTranslator.v3
 ### Usage
 Select a domain, then identify or select the language of text, and then translate the text from one supported language to another.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and api key or access token must be set.
-```cs
-TokenOptions tokenOptions = new TokenOptions()
-{
-    IamApiKey = "<iam-apikey>",
-    IamAccessToken = "<iam-access-token>",
-    IamUrl = "<service-endpoint>"
-};
-
-var _languageTranslator = new LanguageTranslator(tokenOptions, "<version-date>");
-```
-
 #### Translate
 Translates input text from the source language to the target language.
 ```cs

src/IBM.WatsonDeveloperCloud.NaturalLanguageClassifier.v1/README.md

@@ -23,29 +23,6 @@ IBM Watson™ Natural Language Classifier can help your application understand t
 
 You can create and train a classifier in less than 15 minutes.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and api key or access token must be set.
-```cs
-TokenOptions tokenOptions = new TokenOptions()
-{
-    IamApiKey = "<iam-apikey>",
-    IamAccessToken = "<iam-access-token>",
-    IamUrl = "<service-endpoint>"
-};
-
-var _naturalLanguageClassifierService = new NaturalLanguageClassifierService(tokenOptions);
-
-```
-
-You can also authenticate using username and password.
-```cs
-// create a Natural Language Classifier Service instance
-NaturalLanguageClassifierService _naturalLanguageClassifierService = new NaturalLanguageClassifierService();
-
-// set the credentials
-_naturalLanguageClassifierService.SetCredential("<username>", "<password>");
-```
-
 #### Analyze
 Analyze features of natural language content.
 ```cs

src/IBM.WatsonDeveloperCloud.NaturalLanguageUnderstanding.v1/README.md

@@ -23,19 +23,6 @@ Natural Language Understanding uses natural language processing to analyze seman
 
 You can create [custom models][custom_models] with Watson Knowledge Studio that can be used to detect custom [entities][entities] and [relations][relations] in Natural Language Understanding.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-// create a Natural Language Understanding Service instance
-NaturalLanguageUnderstandingService _naturalLanguageUnderstandingService = new NaturalLanguageUnderstandingService();
-
-// set the credentials
-_naturalLanguageUnderstandingService.SetCredential("<username>", "<password>");
-
-//  set the VersionDate
-_naturalLanguageUnderstandingService.VersionDate = "2017-02-27";
-```
-
 #### Analyze
 Analyze features of natural language content.
 ```cs

src/IBM.WatsonDeveloperCloud.PersonalityInsights.v3/README.md

@@ -26,16 +26,6 @@ PM > Install-Package IBM.WatsonDeveloperCloud.PersonalityInsights.v3
 ### Usage
 The service offers a single `profile` method that accepts up to 20 MB of input data and produces results in JSON or CSV format. The service accepts input in Arabic, English, Japanese, or Spanish and can produce output in a variety of languages.
 
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-// create a Personality Insights Service instance
-PersonalityInsightsService _personalityInsights = new PersonalityInsightsService();
-
-// set the credentials
-_personalityInsights.SetCredential("<username>", "<password>");
-```
-
 #### Profile
 Extract personality characteristics based on how a person writes.
 ```cs

src/IBM.WatsonDeveloperCloud.SpeechToText.v1/README.md

@@ -37,17 +37,7 @@ The Speech to Text API consists of the following groups of related calls:
 * Custom corpora provides an HTTP interface for managing the corpora associated with a custom language model. You add a corpus to a custom model to extract words from the corpus into the model's vocabulary.
 
 * Custom words provides an HTTP interface for managing individual words in a custom language model. You can add, list, and delete words from a custom model.
-
-#### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-//  create a Speech to Text Service instance
-SpeechToTextService _speechToText = new SpeechToTextService();
-
-//  set the credentials
-_speechToText.SetCredential("<username>", "<password>");
-```
-
+* 
 #### Get models
 Retrieves a list of all models available for use with the service. The information includes the name of the model and its minimum sampling rate in Hertz, among other things.
 ```cs