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

Update readme with Allen's suggestions

Author: mediumTaj

README.md

@@ -75,50 +75,44 @@ To get started with the Watson Services in Unity, click on each service below to
 * [Visual Recognition](/Scripts/Services/VisualRecognition/v3)
 
 ## Authentication
-Before you can use a service, it must be authenticated with the service instance's `username`, `password` and `url`.
+Watson services are migrating to token-based Identity and Access Management (IAM) authentication.
 
-```cs
-using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
-using IBM.Watson.DeveloperCloud.Utilities;
+- 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).
 
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    Assistant _assistant = new Assistant(credentials);
-}
-```
+### 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:
 
-For services that authenticate using an apikey, you can instantiate the service instance using a `Credential` object with an `apikey` and `url`.
+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`.
 
-**Important**: Instantiation with `apikey` works only with Visual Recognition service instances created before May 23, 2018. Visual Recognition instances created after May 22 use IAM.
+In your code, you can use these values in the service constructor or with a method call after instantiating your service.
 
-```cs
-using IBM.Watson.DeveloperCloud.Services.VisualRecognition.v3;
-using IBM.Watson.DeveloperCloud.Utilities;
+### IAM
 
-void Start()
-{
-    Credentials credentials = new Credentials(<apikey>, <url>);
-    VisualRecognition _visualRecognition = new VisualRecognition(credentials);
-}
-```
+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**:
 
-You can also authenticate a service using IAM authentication. You can either supply a valid access token in the `iamTokenOptions` or get an access token using an `apikey`.
+- 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, in a coroutine, override your stored IAM credentials with an IAM API key and yield until the credentials object `HasIamTokenData()` returns `true`.
 
+#### Supplying the IAM API key
 ```cs
-void IEnumerator TokenExample()
+IEnumerator TokenExample()
 {
     //  Create IAM token options and supply the apikey. 
-    //  Alternatively you can supply an access token.
     TokenOptions iamTokenOptions = new TokenOptions()
     {
         IamApiKey = "<iam-api-key>",
-        IamAccessToken = "<iam-access-token>",
         IamUrl = "<service-url>"
     };
 
     //  Create credentials using the IAM token options
-     _credentials = new Credentials(iamTokenOptions, "<service-url");
+    _credentials = new Credentials(iamTokenOptions, "<service-url");
     while (!_credentials.HasIamTokenData())
         yield return null;
 
@@ -138,6 +132,61 @@ private void OnFail(RESTConnector.Error error, Dictionary<string, object> custom
 }
 ```
 
+#### Supplying the access token
+```cs
+void TokenExample()
+{
+    //  Create IAM token options and supply the access token.
+    TokenOptions iamTokenOptions = new TokenOptions()
+    {
+        IamAccessToken = "<iam-access-token>"
+    };
+
+    //  Create credentials using the IAM token options
+     _credentials = new Credentials(iamTokenOptions, "<service-url");
+
+    _assistant = new Assistant(_credentials);
+    _assistant.VersionDate = "2018-02-16";
+    _assistant.ListWorkspaces(OnListWorkspaces, OnFail);
+}
+
+private void OnListWorkspaces(WorkspaceCollection response, Dictionary<string, object> customData)
+{
+    Log.Debug("OnListWorkspaces()", "Response: {0}", customData["json"].ToString());
+}
+
+private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
+{
+    Log.Debug("OnFail()", "Failed: {0}", error.ToString());
+}
+```
+
+### Username and password
+```cs
+using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
+using IBM.Watson.DeveloperCloud.Utilities;
+
+void Start()
+{
+    Credentials credentials = new Credentials(<username>, <password>, <url>);
+    Assistant _assistant = new Assistant(credentials);
+}
+```
+
+### 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
+using IBM.Watson.DeveloperCloud.Services.VisualRecognition.v3;
+using IBM.Watson.DeveloperCloud.Utilities;
+
+void Start()
+{
+    Credentials credentials = new Credentials(<apikey>, <url>);
+    VisualRecognition _visualRecognition = new VisualRecognition(credentials);
+}
+```
+
+
 ## Callbacks
 Success and failure callbacks are required. You can specify the return type in the callback.  
 ```cs
@@ -324,3 +373,4 @@ See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
 [ibm_cloud_registration]: http://console.bluemix.net/registration?cm_sp=WatsonPlatform-WatsonServices-_-OnPageNavLink-IBMWatson_SDKs-_-Unity
 [get_unity]: https://unity3d.com/get-unity
 [documentation]: https://watson-developer-cloud.github.io/unity-sdk/
+[watson-dashboard]: https://console.bluemix.net/dashboard/apps?category=watson

Scripts/Services/Assistant/v1/README.md

@@ -9,28 +9,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
-using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    Assistant _assistant = new Assistant(credentials);
-}
-```
-
-### Fail handler
-These examples use a common fail handler.
-```cs
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleAssistant.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
 ### Message
 Send a message to the Assistant instance
 ```cs

Scripts/Services/Conversation/v1/README.md

@@ -9,28 +9,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
-using IBM.Watson.DeveloperCloud.Services.Conversation.v1;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    Conversation _conversation = new Conversation(credentials);
-}
-```
-
-### Fail handler
-These examples use a common fail handler.
-```cs
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleConversation.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
 ### Message
 Send a message to the Conversation instance
 ```cs

Scripts/Services/Discovery/v1/README.md

@@ -4,30 +4,6 @@ The IBM Watson™ [Discovery][discovery] service makes it possible to rapidly bu
 ## 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
-using IBM.Watson.DeveloperCloud.Services.Discovery.v1;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    Discovery _discovery = new Discovery(credentials);
-}
-```
-
-### Fail handler
-These examples use a common fail handler.
-```cs
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleDiscovery.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
-
-
 ### 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

Scripts/Services/LanguageTranslator/v2/README.md

@@ -7,59 +7,6 @@
 ## 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 credentials must be set.
-```cs
-using IBM.Watson.DeveloperCloud.Services.LanguageTranslator.v2;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    LanguageTranslator _languageTranslator = new LanguageTranslator(credentials);
-}
-```
-
-
-You can also authenticate the service with an IAM apikey
-```cs
-using IBM.Watson.DeveloperCloud.Services.LanguageTranslator.v2;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Runnable.Run(CreateService());
-}
-
-IEnumerator CreateService()
-{
-    TokenOptions tokenOptions = new TokenOptions()
-    {
-        IamApiKey = _iamApikey
-    };
-
-    Credentials credentials = new Credentials(tokenOptions);
-
-    //  Wait for tokendata
-    while (!credentials.HasIamTokenData())
-        yield return null;
-        
-    LanguageTranslator _languageTranslator = new LanguageTranslator(credentials);
-}
-```
-
-
-### Fail handler
-These examples use a common fail handler.
-```cs
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleLanguageTranslatorV2.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
-
-
 ### List models
 Lists available models for language translation with option to filter by source or by target language.
 ```cs

Scripts/Services/LanguageTranslator/v3/README.md

@@ -5,54 +5,6 @@
 ## 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 credentials must be set.
-```cs
-using IBM.Watson.DeveloperCloud.Services.LanguageTranslator.v3;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    LanguageTranslator _languageTranslator = new LanguageTranslator(credentials);
-}
-```
-
-
-You can also authenticate the service with an IAM apikey
-```cs
-using IBM.Watson.DeveloperCloud.Services.LanguageTranslator.v3;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-IEnumerator CreateService()
-{
-    TokenOptions tokenOptions = new TokenOptions()
-    {
-        IamApiKey = _iamApikey
-    };
-
-    Credentials credentials = new Credentials(tokenOptions);
-
-    //  Wait for tokendata
-    while (!credentials.HasIamTokenData())
-        yield return null;
-        
-    LanguageTranslator _languageTranslator = new LanguageTranslator("<versionDate>", credentials);
-}
-```
-
-
-### Fail handler
-These examples use a common fail handler.
-```cs
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleLanguageTranslatorV3V3.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
-
-
 ### List models
 Lists available models for language translation with option to filter by source or by target language.
 ```cs

Scripts/Services/NaturalLanguageClassifier/v2/README.md

@@ -5,30 +5,6 @@ Use [Natural Language Classifier][natural_language_classifier] service to create
 ## Usage
 Classify intents in natural language.
 
-### Instantiating and authenticating the service
-Before you can send requests to the service it must be instantiated and credentials must be set.
-```cs
-using IBM.Watson.DeveloperCloud.Services.NaturalLanguageClassifier.v2;
-using IBM.Watson.DeveloperCloud.Utilities;
-
-void Start()
-{
-    Credentials credentials = new Credentials(<username>, <password>, <url>);
-    NaturalLanguageClassifier _naturalLanguageClassifier = new NaturalLanguageClassifier(credentials);
-}
-```
-
-
-### Fail handler
-These examples use a common fail handler.
-```cs
-private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
-{
-    Log.Error("ExampleNaturalLanguageClassifier.OnFail()", "Error received: {0}", error.ToString());
-}
-```
-
-
 ### Listing Classifiers
 Returns an empty array if no classifiers are available.
 ```cs