Skip to main contentIBM Quantum Documentation

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.

Select an IBM Quantum channel

You have the option to access IBM Quantum hardware through either IBM Quantum Platform or IBM Cloud.

IBM Quantum Platform

IBM Quantum Platform has Open (free access) and Premium (enterprise subscription) plans. See IBM Quantum access plans for details.

Before setting up with IBM Quantum Platform, make sure you have the Qiskit SDK and Qiskit Runtime installed.

Available plans:

  • Open Plan - Run your quantum circuits on the world's best QPUs for free (up to 10 minutes quantum time per month).

  • 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 for details.

IBM Cloud has Lite (free access) and Standard (pay-as-you-go access) plans. See Qiskit Runtime plans on IBM Cloud for details.

This channel does not support a cloud-based development environment. Therefore, you will need to install and set up Qiskit and Qiskit Runtime and set up to use IBM Cloud.

Available plans:

  • Standard (Pay-as-you-go) Plan - Run quantum circuits on the world's best QPUs and pay only for the quantum time you use.

  • Lite plan: Debug and learn about quantum circuits using free simulators.

Set up to use IBM Quantum Platform

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

  2. 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 (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.

    Note

    The Instances section in your IBM Quantum account page lists the instances that you can access.

    Caution

    Protect your API token! Never include your token in source code, Python script, or 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 next 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 step 4.

  3. Retrieve your API token from the IBM Quantum account page, and activate your Python virtual environment. See the installation instructions if you do not already have a virtual environment set up.

    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 Quantum Platform.) To use save_account(), run python in your shell to open a REPL (read-eval-print loop), then enter the following:

    token = "<your-token>"
    from qiskit_ibm_runtime import QiskitRuntimeService
 
QiskitRuntimeService.save_account(
  token=token,
  channel="ibm_quantum" # `channel` distinguishes between different account types
)
    Tip

    Alternatively, you can copy the code for accessing a specific instance, then paste it into your code. Go to the Instances section of your IBM Quantum account page and click the vertical ellipses at the end of an instance's column to copy the code.

    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().

    # Load saved credentials
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 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.

  4. 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 expiring it on the IBM Quantum Platform dashboard (click the refresh button in the API token field) to reduce risk. To initialize the service in this situation, you can use code like the following:

    from qiskit_ibm_runtime import QiskitRuntimeService
 
# After using the following code, go to your dashboard (https://quantum.ibm.com/)
# and expire your API token (click the refresh button in the API token field)
service = QiskitRuntimeService(channel="ibm_quantum", token="<MY_IBM_QUANTUM_TOKEN>")
    Caution

    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 expiring it on the IBM Quantum Platform dashboard (click the refresh button in the API token field) to reduce risk.

  5. Test your setup. Run a simple circuit using Sampler to ensure that your environment is set up properly:

from qiskit import QuantumCircuit
from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler
 
# Create empty circuit
example_circuit = QuantumCircuit(2)
example_circuit.measure_all()
 
# You'll need to specify the credentials when initializing QiskitRuntimeService, if they were not previously saved.
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)
 
sampler = Sampler(backend)
job = sampler.run([example_circuit])
print(f"job id: {job.job_id()}")
result = job.result()
print(result)

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

    Note

    The Instances section in your IBM Quantum account page lists the instances that you can access.

  2. Retrieve your API token from the IBM Quantum account page.

  3. Because of the security risks posed by executing code that contains your API token, 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 if you are not using a trusted environment, such as a shared or public computer.

    To set the IQP_API_TOKEN environment variable in your system, you can add the following line to your shell profile (for example, .bashrc or .zshrc) or by setting it directly in your terminal:

    export IQP_API_TOKEN=<your-token>

    When you invoke the environment variable in your code, include import os, as in this example request:

    import os
 
import requests
 
req_url = "https://api.quantum-computing.ibm.com/runtime/jobs?limit=10&offset=0&exclude_params=true"
 
headers_list = {
  "Accept": "application/json",
  "Authorization": f"Bearer {os.environ['IQP_API_TOKEN']}"
}
 
payload = ""
 
response = requests.request("GET", req_url, data=payload,  headers=headers_list)
 
print(response.json())

    Note that when creating an environment variable, your API token is still stored locally in plain text, and should be safeguarded.

  4. 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 rotating it on the IBM Quantum Platform dashboard (click the refresh button in the API token field). To initialize the service in this situation, use your API token directly:

    # Refresh your API token on the dashboard after using the code as follows:
"Authorization": "Bearer <your-token>"
    Caution

    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 expiring it on the IBM Quantum Platform dashboard (click the refresh button in the API token field) to reduce risk.

Use a temporary access 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. Follow the same precautions previously mentioned about securely using the environment variable.

    import os
 
import requests
 
url = 'https://auth.quantum-computing.ibm.com/api/users/loginWithToken'
payload = {"apiToken": os.environ["IQP_API_TOKEN"]}
auth_response = requests.post(url, json=payload)
auth_id=auth_response.json()['id']

  2. View your available backends:

    url_backends = 'https://api.quantum-computing.ibm.com/runtime/backends'
headers = {'Content-Type': 'application/json',
            'x-access-token':auth_id}
 
backends_response = requests.get(url_backends, headers=headers)
 
print(backends_response.json()['devices'][:5],"...")

    You can then transpile circuits using REST API and run them using either the Sampler or the Estimator primitives.

  3. After your experiments are complete, you can proceed to invalidate your token and then test its invalidation.

    logout_url = 'https://auth.quantum-computing.ibm.com/api/users/logout'
headers = {'x-access-token':auth_id}
logout_response = requests.post(logout_url, headers=headers)
print("response ok?:",logout_response.ok,logout_response.text)

    This should yield an error (Error 401) once the access token is invalidated.

    logout_url = 'https://auth.quantum-computing.ibm.com/api/users/logout'
headers = {'x-access-token':auth_id}
logout_response = requests.post(logout_url, headers=headers)
 
if logout_response.status_code == 200:
    job_id = logout_response.json().get('id')
    print("Job created:",logout_response.text)
elif logout_response.status_code == 401:
    print("invalid credentials. Access token should be successfully invalidated.")
else:
    print(logout_response.text,"\n")
    print(f"Error: {logout_response.status_code}")

    Output

      invalid credentials. Access token should be successfully invalidated.

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 from the IBM Cloud Registration page.

  3. Create a service instance, if necessary. Open your IBM Cloud Instances page. If you have one or more instances shown, continue to the next step. Otherwise, click Create instance. When creating your instance you can name it, tag it, select a resource group for it, and select a performance strategy. Next, agree to the license agreements by checking the box in the bottom right corner of the page, and click Create.

    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 to open a read-eval-print loop (REPL), and enter the following:

    token = "<your-token>"
    service = QiskitRuntimeService(
    channel="ibm_cloud", # `channel` distinguishes between different account types
    token=token, # Your token is confidential.
    # Take care not to share your token in public code.
    instance="<IBM Cloud CRN>",
    name="<account-name>",
)

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

    from qiskit_ibm_runtime import QiskitRuntimeService
 
# Load saved credentials
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 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.

  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 expiring it on the IBM Quantum Platform dashboard (click the refresh button in the API token field) to reduce risk.

    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>"
  )

Next steps

Recommendations
Was this page helpful?
Report a bug or request content on GitHub.