Add instructions to securely manage token

docs/guides/functions.ipynb

@@ -73,7 +73,7 @@
    "id": "42843fcd-1779-4a74-8d6a-7d00c22e374e",
    "metadata": {},
    "source": [
-    "Optionally, you can use the `save_account()` method to save your credentials for easy access later on, before initializing the service. This saves your credentials in the same place as `QiskitRuntimeService.save_account()`, so you can skip this step if you had previously used `QiskitRuntimeService` to save your account. *Note that account credentials are saved in plain text, so only do so if you are using a trusted device.*"
+    "Optionally, you can use the `save_account()` method to save your credentials for easy access later on, before initializing the service. This saves your credentials in the same place as `QiskitRuntimeService.save_account()`, so you can skip this step if you had previously used `QiskitRuntimeService` to save your account."
    ]
   },
   {

docs/guides/setup-channel.mdx

@@ -5,7 +5,7 @@ description: Installation and setup instructions for IBM Quantum Platform or IBM
 
 # Set up an IBM Quantum channel
 
-You can access IBM® quantum processing units (QPUs) by using the IBM Quantum Platform or IBM Cloud® _channel_.  _Channel_ is the term used to describe the method you use to access IBM Quantum services.
+You can access IBM® quantum processing units (QPUs) by using the IBM Quantum Platform or IBM Cloud® channel.  _Channel_ is the term used to describe the method you use to access IBM Quantum services.
 
 ## Select an IBM Quantum channel
 
@@ -23,7 +23,6 @@ Available plans:
 
 * **Premium Plan** - Run quantum circuits on the world's best QPUs using an enterprise quantum time subscription.
 
-
 ### IBM Cloud
 
 IBM Cloud offers pay-as-you-go access plans. See [IBM Quantum access plans](https://www.ibm.com/quantum/access-plans) for details.
@@ -49,55 +48,47 @@ Available plans:
       The Instances section in your [IBM Quantum account page](https://quantum.ibm.com/account) lists the instances that you can access.
     </Admonition>
 
-1. Retrieve your IBM Quantum token from the [IBM Quantum account page](https://quantum.ibm.com/account).
-
-1. <span id="save-account"></span>Authenticate to the service by calling `QiskitRuntimeService` with your IBM Quantum API key and CRN:
-
-   ```python
-   from qiskit_ibm_runtime import QiskitRuntimeService
-
-   service = QiskitRuntimeService(channel="ibm_quantum", token="<MY_IBM_QUANTUM_TOKEN>")
+1. Retrieve your API token from the [IBM Quantum account page](https://quantum.ibm.com/account), and activate your Python virtual environment.  See the [installation instructions](/guides/install-qiskit#local) if you do not already have a virtual environment set up. 
 
-   ```
-
-   Or, optionally use the `save_account()` method to save your credentials for easy access later on, before initializing the service.
+    <span id="save-account"></span>**If you are working in a trusted Python environment (such as on a personal laptop or workstation),** use the `save_account()` method to save your credentials locally. ([Skip to the next step](#untrusted-machine) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.) To use `save_account()`, run Python in your virtual environment to open a read-eval-print loop (REPL), then enter the following:
 
     ```python
     from qiskit_ibm_runtime import QiskitRuntimeService
 
-    # Save an IBM Quantum account and set it as your default account.
     QiskitRuntimeService.save_account(
-        channel="ibm_quantum",
-        token="<MY_IBM_QUANTUM_TOKEN>",
-        set_as_default=True,
-        # Use `overwrite=True` if you're updating your token.
-        overwrite=True,
+      token="<your-token">,
+      channel="ibm_quantum", # `channel` distinguishes between different account types
+      overwrite=True # Use `overwrite=True` if you're updating your token
     )
+    ```
+
+    Close out of the REPL with `exit()`. From now on, whenever you need to authenticate to the service, you can load your credentials with `QiskitRuntimeService()`.
 
+    ```python
     # Load saved credentials
     service = QiskitRuntimeService()
     ```
 
-    * If you save your credentials to disk, you can use `QiskitRuntimeService()` in the future to initialize your account. The `channel` parameter distinguishes between different account types.
-    * If you are saving multiple accounts per channel, consider using the `name` parameter to differentiate them.
-    * Credentials are saved to `$HOME/.qiskit/qiskit-ibm.json`.  Do not manually edit this file.
-    * If you don't save your credentials, you must specify them every time you start a new session.
-    * The `channel` parameter allows you to distinguish between different account types. When initializing the account, IBM Cloud is the default account used if have saved credentials for an IBM Quantum Platform and an IBM Cloud account.
+      * If you have saved credentials for both an IBM Quantum Platform account and an IBM Cloud account, IBM Cloud is the default account used when you initialize your account, unless you specify `set_as_default=True` in your IBM Quantum Platform account when you use the `save_account()` method.
+      * If you are saving multiple accounts per channel, consider using the `name` parameter to differentiate them.
+      * Credentials are saved to `$HOME/.qiskit/qiskit-ibm.json`.  Do not manually edit this file.
 
-    <Admonition type="caution">
-      Account credentials are saved in plain text, so only do so if you are using a trusted device.
+    <Admonition type="warning">
+      **Protect your API token!** Never include your token in plain text in a notebook file. If you are working in a trusted Python environment (such as on a personal laptop or workstation), use the `save_account()` method described in the previous step to store your credentials, keeping in mind that your token will still be stored as plain text on your local drive. If you are executing code in a Python environment that is not trusted, see the [instructions in the next step](#untrusted-machine).
     </Admonition>
 
-    <Admonition type="note">
-    IBM Cloud is the default account used if you don't specify a different channel or account name.
-    </Admonition>
+1. <span id="untrusted-machine"></span>**Avoid executing code on an external or random cloud Python environment to minimize security risks.** If you must use an untrusted environment (on, for example, a public computer), change your API token after each use by rotating it on the [IBM Quantum Platform dashboard](https://quantum.ibm.com/) (click the refresh button in the API token field). To initialize the service in this situation, you can use code like the following:
 
-    <CodeAssistantAdmonition
-      tagLine="If you forget the setup code, try asking Qiskit Code Assistant."
-      prompts={[
-        "# Set up my IBM Runtime account using TOKEN for my token"
-      ]}
-    />
+    ```python
+    from qiskit_ibm_runtime import QiskitRuntimeService
+
+    # Refresh your API token on the dashboard after using the code as follows:
+    service = QiskitRuntimeService(channel="ibm_quantum", token="<MY_IBM_QUANTUM_TOKEN>")
+    ```
+
+    <Admonition type="warning">
+      When sharing code with others, ensure that your API token is not embedded directly within the Python script in plain text. Instead, share the script without the token and provide instructions for securely setting it up.
+    </Admonition>
 
 1. Test your setup.  Run a simple circuit using Sampler to ensure that your environment is set up properly:
 
@@ -121,20 +112,61 @@ print(result)
   ```
 
 <span id="iqp-rest-api"></span>
-## Set up to use IBM Quantum Platform with REST API
+### Set up to use IBM Quantum Platform with REST API
 
 Alternatively, you can also access quantum processors with REST APIs, enabling you to work with QPUs using any programming language or framework. 
 
-1. Retrieve your IBM Quantum token from the [IBM Quantum account page](https://quantum.ibm.com/account).
-
-2. If you do not already have a user account, get one at the [IBM Quantum login page.](https://quantum.ibm.com/login)  Your user account is associated with one or more [instances](./instances) (in the form hub / group / project) that give access to IBM Quantum services. Additionally, a unique token is assigned to each account, allowing for IBM Quantum access from Qiskit. The instructions in this section use our default instance.  For instructions to choose a specific instance, see [Connect to an instance](./instances#connect-instance).
+1. If you do not already have a user account, get one at the [IBM Quantum login page.](https://quantum.ibm.com/login)  Your user account is associated with one or more [instances](./instances) (in the form hub / group / project) that give access to IBM Quantum services. Additionally, a unique token is assigned to each account, allowing for IBM Quantum access from Qiskit. The instructions in this section use our default instance.  For instructions to choose a specific instance, see [Connect to an instance](./instances#connect-instance).
 
     <Admonition type="note">
       The Instances section in your [IBM Quantum account page](https://quantum.ibm.com/account) lists the instances that you can access.
     </Admonition>
 
+1. Retrieve your API token from the [IBM Quantum account page](https://quantum.ibm.com/account).
+
+1. Because of the security risks posed by executing code that contains your API token in plain text, the recommended authentication method is to first create an environment variable for your API token, but only do so **if you are working in a trusted Python environment (such as on a personal laptop or workstation).** [Skip to the next step](#rest-untrusted) if you are not using a trusted environment, such as a shared or public computer.
+
+    The following demonstrates creating an environment variable:
+
+    ```shell
+    export IQP_API_TOKEN=<your-token>
+    ```
+    When you invoke the environment variable in your code, include `import os`, as in this example request:
+
+    ```python
+    import os
+    import requests
+
+    reqUrl = "https://api.quantum-computing.ibm.com/runtime/jobs?limit=10&offset=0&exclude_params=true"
+
+    headersList = {
+      "Accept": "application/json",
+      "Authorization": "Bearer os.environ.pop(IQP_API_TOKEN)"
+    }
+
+    payload = ""
+
+    response = requests.request("GET", reqUrl, data=payload,  headers=headersList)
+
+    print(response.json())
+    ```
+
+    Note that when creating an environment variable, your API token is still stored locally in plain text, and should be safeguarded.
+
+1. <span id="rest-untrusted"></span>**Avoid executing code on an external or random cloud Python environment to minimize security risks.** If you must use an untrusted environment (on, for example, a public computer), change your API token after each use by rotating it on the [IBM Quantum Platform dashboard](https://quantum.ibm.com/) (click the refresh button in the API token field). To initialize the service in this situation, use your API token directly: 
+
+    ```python
+    # Refresh your API token on the dashboard after using the code as follows:
+    "Authorization": "Bearer <your-token>" 
+    ```
+
+    <Admonition type="warning">
+      When sharing code with others, ensure that your API token is not embedded directly within the Python script in plain text. Instead, share the script without the token and provide instructions for securely setting it up.
+    </Admonition>
+
+#### Use a temporary access token
 
-3. Optionally obtain a temporary access token by supplying the API token obtained above. This is especially useful if you would like control over tokens, such as token invalidation. Alternatively, you can work directly with your IBM Quantum Platform API token.
+1. Optionally obtain a temporary access token by supplying your API token. This is especially useful if you would like control over tokens, such as token invalidation.
 
     ```python
     import requests
@@ -145,7 +177,7 @@ Alternatively, you can also access quantum processors with REST APIs, enabling y
     auth_id=auth_response.json()['id']
     ```
 
-4. View your available backends:
+1. View your available backends:
 
     ```python
     url_backends = 'https://api.quantum-computing.ibm.com/runtime/backends'
@@ -160,7 +192,7 @@ Alternatively, you can also access quantum processors with REST APIs, enabling y
 
     You can then [transpile circuits using REST API](./transpile-rest-api) and run them using either the [Sampler or the Estimator primitives](./primitives-rest-api).   
 
-5. After your experiments are complete, you can proceed to invalidate your token and then test its invalidation.
+1. After your experiments are complete, you can proceed to invalidate your token and then test its invalidation.
 
     ```python
     logout_url = 'https://auth.quantum-computing.ibm.com/api/users/logout'
@@ -205,50 +237,50 @@ Alternatively, you can also access quantum processors with REST APIs, enabling y
     1. Find your API key. From the [API keys page](https://cloud.ibm.com/iam/apikeys), view or create your API key, then copy it to a secure location so you can use it for authentication.
     2. Find your Cloud Resource Name (CRN). Open the [Instances page](https://cloud.ibm.com/quantum/instances) and click your instance. In the page that opens, click the icon to copy your CRN. Save it in a secure location so you can use it for authentication.
 
-<span id="cloud-save"></span>
-1. Authenticate to the service by calling `QiskitRuntimeService` with your saved credentials or with your IBM Cloud API key and CRN:
+1. <span id="cloud-save"></span>**If you are working in a trusted Python environment (such as on a personal laptop or workstation),** use the `save_account()` method to save your credentials locally. ([Skip to the next step](#cloud-untrusted) if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Cloud.) To use `save_account()`, activate a Python virtual environment (see the [installation instructions](/guides/install-qiskit#local) if you do not already have a virtual environment set up). Then run Python in your virtual environment to open a read-eval-print loop (REPL), and enter the following:
 
-   ```python
-   from qiskit_ibm_runtime import QiskitRuntimeService
+    ```python
+    from qiskit_ibm_runtime import QiskitRuntimeService
 
-   service = QiskitRuntimeService(channel="ibm_cloud", token="<IBM Cloud API key>", instance="<IBM Cloud CRN>")
-   ```
+    service = QiskitRuntimeService(
+    channel="ibm_cloud",
+    token="<IBM Cloud API key>", # Your token is confidential.
+    # Take care not to share your token in public code.
+    instance="<IBM Cloud CRN>",
+    name="<account-name>",
+    overwrite=True, # Use `overwrite=True` if you're updating your token.
+    )
+    ```
 
-   You can optionally use the `save_account()` method to save your credentials for easy access later on, before initializing the service.
+1. Close out of the REPL with `exit()`. From now on, whenever you need to authenticate to the service, you can load your credentials with `QiskitRuntimeService()`.  Test your setup and ensure that you can connect to the service:
 
-   ```python
+    ```python
     from qiskit_ibm_runtime import QiskitRuntimeService
 
-    # Save account to disk.
-    QiskitRuntimeService.save_account(
-        channel="ibm_cloud",
-        token="<IBM Cloud API key>",
-        instance="<IBM Cloud CRN>",
-        name="<account-name>",
-        # Use `overwrite=True` if you're updating your token.
-        overwrite=True,
-    )
-
     # Load saved credentials
-    service = QiskitRuntimeService(name="<account-name>")
+    service = QiskitRuntimeService()
     ```
 
-    * If you save your credentials to disk, you can use `QiskitRuntimeService()` in the future to initialize your account. The `channel` parameter distinguishes between different account types. When initializing the account, IBM Cloud is the default account used if you have saved credentials for both an IBM Quantum Platform and an IBM Cloud account.
-    * If you are saving multiple accounts per channel, consider using the `name` parameter to differentiate them.
-    * Credentials are saved to `$HOME/.qiskit/qiskit-ibm.json`.  Do not manually edit this file.
-    * If you don't save your credentials, you must specify them every time you start a new session.
-
-    <Admonition type="caution">
-        Account credentials are saved in plain text, so only do so if you are using a trusted device.
-    </Admonition>
+      * If you have saved credentials for both an IBM Quantum Platform account and an IBM Cloud account, IBM Cloud is the default account used when you initialize your account, unless you specify `set_as_default=True` in your IBM Quantum Platform account when you use the `save_account()` method.
+      * If you are saving multiple accounts per channel, consider using the `name` parameter to differentiate them.
+      * Credentials are saved to `$HOME/.qiskit/qiskit-ibm.json`.  Do not manually edit this file.
+      * If you don't save your credentials, you must specify them every time you start a new session.
 
- 1. Test your setup.  Ensure that you can connect to the service:
+1. <span id="cloud-untrusted"></span>**Avoid executing code on an external or random cloud Python environment to minimize security risks.** If you must use an untrusted environment (on, for example, a public computer), change your API token after each use by deleting it on the [API keys page](https://cloud.ibm.com/iam/apikeys) and creating a new one. To initialize the service in this situation, you can use code like the following:
 
-   ```python
+    ```python
     from qiskit_ibm_runtime import QiskitRuntimeService
-
-    service = QiskitRuntimeService()
-  ```
+
+    service = QiskitRuntimeService(
+      channel="ibm_cloud", 
+      # Delete your token on the API keys page after entering this code:
+      token="<IBM Cloud API key>", 
+      instance="<IBM Cloud CRN>"
+      )
+    ```
+    <Admonition type="warning">
+      When sharing code with others, ensure that your API token is not embedded directly within the Python script in plain text. Instead, share the script without the token and provide instructions for securely setting it up.
+    </Admonition>
 
 ## Next steps