Set up your IBM Cloud account

If you have an invitation to join an account, follow the steps in Set up your IBM Cloud account - invited users instead.

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.

Your user account is associated with one or more instances, identified by Cloud Resource Names (CRNs) that give access to IBM Quantum services. Additionally, a unique API token (also called a key) is assigned to each account, allowing for IBM Quantum access from Qiskit. For instructions to choose a specific instance, see Connect to an instance.

Set up to use IBM Cloud

Before you begin

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

   Note

   You can have multiple IBM Cloud accounts. You can access any of your IBM Cloud accounts at any time from the account switcher in the header of the IBM Quantum Platform interface.

2. Log in to IBM Quantum Platform with an IBMid or Google account. If you don't have one, you are guided through creating one.

3. Make sure that the correct account and region are selected in the account switcher in the header, as shown in the following image.

   The region controls where your jobs are run and where the job data is kept. You can access either region by using the same API key, but you can only see and access the instances that were created in the region that you're logged in to.

   

1. Create an instance

Go to the IBM Quantum Platform dashboard. If you have one or more instances shown, skip this step. Otherwise, follow these steps to create an instance.

1. Make sure that the correct account and region are selected from the account and region switchers in the header, as shown in the following image.

   • You can have multiple accounts. If you don't see the instances or jobs you're expecting, try a different account.
   • The region controls where your jobs are run and where the job data is kept. You can access either region by using the same API key, but you can only see and access the instances that were created in the region that you're logged in to.
   • If you want to create an Open instance, you must choose the us-east region.

   

2. Click Create instance.

   • Choose a name and the plan to use.
   • If you are creating an instance of the Pay-As-You-Go Plan, it is recommended that you set the total cost limit or the usage limit. (These values can be updated later.)
   • 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.

3. 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.

4. Choose whether you want an access group to be created for this instance and click Create instance. This access group allows other users (collaborators) to share the time allocated to this instance. Collaborators can be added on the Users page.

   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.

   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.

2. Find your access credentials

1. Find your API key. From the dashboard, create your API key, then copy it to a secure location so you can use it for authentication. Note that you can use the same API key to connect to any region.
2. Optional: Find the instance you want to use from the Instances page. Click the icon to copy its CRN, then save it in a secure location so you can use it to identify the instance.

3. Save your access credentials

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, then use them to initialize the service.

1. Ensure you are working in an active Python environment with the Qiskit SDK and Qiskit Runtime installed.

2. Activate the Python virtual environment, run Python in your virtual environment, and enter the following:

   token = "<your-API-token>"

3. Save your credentials. Run this once per account you want to save.

  from qiskit_ibm_runtime import QiskitRuntimeService
 
  QiskitRuntimeService.save_account(
    token="token",
    instance="<IBM Cloud CRN or instance name>", # Optional
    plans_preference="['open', 'premium']", # Optional
    region="<region>", # Optional
    name="<account-name>", # Optional
    set_as_default=True, # Optional
    overwrite=True, # Optional
  )

Options:

-token: IBM Cloud API key. Your token is confidential. Do not share your token in public code. -instance: Optionally specify the instance to use. -plans_preference: Optionally set the types of plans to prioritize. This is ignored if the instance is specified. Available options are 'open' and 'premium'. Instances of a certain plan type are excluded if the plan name is not specified. For example, if [open] is passed in, only open plan instances are available. -region: Optionally set the region to use. Accepted values are 'us-east' and 'eu-de'. This is ignored if the instance is specified. -name: Optionally name this set of account credentials. -set_as_default: Set the value to True to save these as your default credentials. If you save only one account, it is automatically set as the default. -overwrite: Set this value to True to update your default credentials.

Considerations

• 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.
• If you manually specify your credentials, a saved account will not be used.

4. Initialize the service

Every time you need to instantiate a QiskitRuntimeService with the default saved account, run the following:

   from qiskit_ibm_runtime import QiskitRuntimeService
 
   service = QiskitRuntimeService()
   ...

See the Initialize the service guide for more details about instantiating the QiskitRuntimeService.

Next steps