Set up your IBM Cloud account

You can run workloads on IBM® quantum processing units (QPUs) by setting up an account on IBM Cloud®. You will also need to install and set up Qiskit and Qiskit Runtime.

Available IBM Cloud plans:

• Premium Plan - Run quantum circuits on the world's best QPUs using an enterprise quantum time subscription.
• Standard (Pay-as-you-go) Plan - Run quantum circuits on the world's best QPUs and pay only for the quantum time you use.
• Open Plan: Run your quantum circuits on the world's best QPUs for free (up to 10 minutes quantum time per month).
  Note

  During early access, users on the Open Plan get 10 minutes per 28-day period.

Set up to use IBM Cloud

1. Before setting up with IBM Cloud, ensure you are working in an active Python environment with the Qiskit SDK and Qiskit Runtime installed.

2. If you do not already have one, set up an IBM Cloud account.

3. Create an instance, if necessary. Go to the IBM Quantum Platform dashboard. If you have one or more instances shown, continue to the next step.

   1. Click Create instance. Choose a name and the plan to use. Next, scroll down to see the Terms link. After reading the terms, agree to the license agreements by checking the box in the bottom right corner of the page, and click Next.

   2. On the Plan inheritance page, leave the default setting (toggle is not enabled) and click Next if you're setting up an Open instance. If you are not setting up an Open instance and you want different QPUs to be available on this instance, enable the "Customize allocated compute resources" toggle, choose the QPUs you want this instance to be able to access, then click Next.

      Note

      If you customize the allocated compute resources, the available QPUs will never be automatically updated, regardless of any changes made to the parent plan. However, you can manually add or remove QPUs later.

   3. Choose whether you want an access group to be created for this instance and click Create instance. For an Open instance, you probably don't need this access group, although creating one won't impact your usage unless you add another user to the group. This access group allows other users (collaborators) to share the time allocated to this instance. Collaborators can be added on the Users page.

      You can add or remove access groups at any time from IBM Cloud. See Setting up access groups for instructions.

   Note

   If you are an administrator who needs to set up Qiskit Runtime on Cloud for your organization, refer to Plan Qiskit Runtime for an organization.

4. Find your access credentials.

   1. Find your API key. From the API keys page, 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 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.

5. 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 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 if you do not already have a virtual environment set up). Then, run Python in your virtual environment and enter the following:

   token = "<your-API-token>"

   from qiskit_ibm_runtime import QiskitRuntimeService
   service = QiskitRuntimeService.save_account(
       channel="ibm_cloud", # `channel` distinguishes between different account types
       token=token, # Your token is confidential.
       # Do not share your token in public code.
       instance="<IBM Cloud CRN>",
       name="<account-name>", # Optionally name this set of account credentials.
       set_as_default=True, # Optionally set these as your default credentials.
   )

6. Type 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:

   from qiskit_ibm_runtime import QiskitRuntimeService
    
   # If you named your credentials, optionally specify the name here, as follows:
   # QiskitRuntimeService(name='account-name')
   # If you don't specify a name, the default credentials are loaded.
   service = QiskitRuntimeService()

   • 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, 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.

7. Avoid executing code on an untrusted machine or an external 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 and creating a new one.

   Caution

   Protect your API token! Never include your token in source code, Python script, or notebook file. When sharing code with others, ensure that your API token is not embedded directly within the Python script. Instead, share the script without the token and provide instructions for securely setting it up.

   If you accidentally share your token with someone or include it in version control like Git, immediately revoke your token by following the Deleting an API key topic on IBM Cloud.

   To initialize the service in this situation, you can use code like the following:

   from qiskit_ibm_runtime import 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>"
     )

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. If you do not already have a user account, get one at the IBM Quantum login page. Your user account is associated with one or more instances that give access to IBM Quantum services. Additionally, a unique token is assigned to each account -- known as a Cloud Resource Name (CRN) -- allowing for IBM Quantum access from Qiskit. For instructions to choose a specific instance, see Connect to an instance.

   Note

   The IBM Quantum Platform dashboard and the Instances page list the instances that you can access.

2. Create an API key on the dashboard.

3. Once you have an API key, you'll then need to generate an IBM Cloud Identity and Access Management (IAM) bearer token. These are short-lived tokens which are used to authenticate requests to the REST API. To generate one, call the IAM Identity Services API as shown in the following sample request:

curl -X POST 'https://iam.cloud.ibm.com/identity/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=MY_APIKEY'

{
   "access_token": "eyJhbGciOiJIUz......sgrKIi8hdFs",
   "refresh_token": "SPrXw5tBE3......KBQ+luWQVY=",
   "token_type": "Bearer",
   "expires_in": 3600,
   "expiration": 1473188353
}

# Use 'service' to invoke operations.
import requests
import json
 
url = 'https://iam.cloud.ibm.com/identity/token'
api_key = 'MY_APIKEY'
headers = {
 'Content-Type': 'application/x-www-form-urlendcoded',
}
data = f'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={api_key}'
response = requests.post(url, headers=headers, data=data)
 
# Bearer token to authorize requests to the REST API
bearer_token = response.json()['access_token']

export IQP_API_TOKEN=<your-token>

import os
api_token = os.environ['IQP_API_TOKEN']

# Refresh your API key on the dashboard after using the code as follows:
api_key = "<your-key>"

4. Lastly, once you have an IAM bearer token, you can authenticate requests to the Qiskit Runtime REST API by including the CRN and bearer token to the request's headers.

curl -X 'GET' \
   'https://quantum.cloud.ibm.com/api/qiskit-runtime-rest/usage' \
   '-H accept: application/json' \
   '-H authorization: Bearer <BEARER_TOKEN>' \
   '-H Service-CRN: crn:v1:bluemix:public:quantum-computing:us-east:a/b947c1c5a9378d64aed96696e4d76e8e:a3a7f181-35aa-42c8-94d6-7c8ed6e1a94b::'

Next steps