Authentication

Open Quantum uses SDK keys to authenticate API requests. SDK keys are managed through the Open Quantum Portal and exchanged for short-lived JWT tokens via the Open Quantum identity server.

SDK Key Authentication

An SDK key consists of two parts:

• Client ID -- A public identifier (format: s_<uuid>). Safe to log or display.
• Client Secret -- A private secret. Must be kept confidential.

These credentials are used with the OAuth 2.0 client_credentials grant to obtain a JWT access token.

Creating SDK Keys

1. Log in to the Open Quantum Portal.
2. Go to the SDK Keys page.
3. Click Create SDK Key.
4. Copy both the Client ID and Client Secret.

Warning

The Client Secret is displayed only once at creation time. Store it securely. If you lose it, delete the key and create a new one.

You can create up to 2 SDK keys per user account. Keys can be enabled, disabled, or deleted from the SDK Keys page. See SDK Keys for more on key management, rotation, and best practices.

Authentication Methods

ClientCredentials + ClientCredentialsAuth (Core SDK)

The Core SDK uses ClientCredentials and ClientCredentialsAuth for authentication:

from openquantum_sdk.auth import ClientCredentials, ClientCredentialsAuth

creds = ClientCredentials(
    client_id="s_your_client_id",
    client_secret="your_client_secret",
)

auth = ClientCredentialsAuth(creds=creds)

Pass the auth object to any client:

from openquantum_sdk.clients import SchedulerClient, ManagementClient

scheduler = SchedulerClient(auth=auth)
management = ManagementClient(auth=auth)

Token-Based Auth

If you already have a JWT token (obtained externally), pass it directly:

from openquantum_sdk.clients import SchedulerClient

scheduler = SchedulerClient(token="your_jwt_token")

Note

You cannot provide both token and auth to the same client. Use one or the other.

Saved Accounts (Qiskit Plugin)

The Qiskit plugin's OpenQuantumService supports saving and loading account credentials to disk:

Save an Account

from openquantum_sdk.auth import ClientCredentials
from openquantum_sdk_qiskit import OpenQuantumService

OpenQuantumService.save_account(
    name="default",
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
)

Credentials are stored in ~/.openquantum/accounts.json (or the platform-appropriate config directory). If the keyring package is installed, secrets are stored in the system keyring instead of on disk.

Load a Saved Account

service = OpenQuantumService.from_saved_account(name="default")

Or let OpenQuantumService() auto-load the default saved account:

service = OpenQuantumService()  # Automatically loads "default" account if saved

List and Delete Saved Accounts

accounts = OpenQuantumService.saved_accounts()
print(accounts)

OpenQuantumService.delete_account(name="default")

Login Shortcut

The login() class method creates a service and optionally saves credentials in one call:

service = OpenQuantumService.login(
    creds=ClientCredentials(
        client_id="s_your_client_id",
        client_secret="your_client_secret",
    ),
    save=True,
    name="default",
)

SDK Key File

You can store credentials in a JSON file instead of passing them inline. This is the recommended approach for the CLI and is also useful for scripts.

Create a JSON file (e.g., sdk-key.json):

{
    "client_id": "s_your_client_id",
    "client_secret": "your_client_secret"
}

Use it with the CLI:

python -m openquantum_sdk --sdk-key sdk-key.json --input circuit.qasm ...

Or load it programmatically:

from openquantum_sdk.__main__ import load_creds_from_file
from openquantum_sdk.clients import SchedulerClient
from openquantum_sdk.auth import ClientCredentialsAuth

creds = load_creds_from_file("sdk-key.json")
scheduler = SchedulerClient(auth=ClientCredentialsAuth(creds=creds))

You can also point to the file via the OPENQUANTUM_SDK_KEY environment variable:

export OPENQUANTUM_SDK_KEY="/path/to/sdk-key.json"

Credential Resolution Order

When using the CLI, credentials are resolved in this order:

1. --sdk-key <file.json> CLI flag
2. OPENQUANTUM_SDK_KEY environment variable (path to JSON file)
3. --client-id / --client-secret CLI flags
4. OPENQUANTUM_CLIENT_ID / OPENQUANTUM_CLIENT_SECRET environment variables

The first source that provides valid credentials is used.

Environment Variables

All SDKs read credentials from environment variables as a fallback:

Variable	Description
OPENQUANTUM_CLIENT_ID	SDK key Client ID
OPENQUANTUM_CLIENT_SECRET	SDK key Client Secret
OPENQUANTUM_SDK_KEY	Path to a JSON file containing client_id and client_secret
OPENQUANTUM_ORGANIZATION_ID	Your organization UUID (used by PennyLane plugin)

export OPENQUANTUM_CLIENT_ID="s_your_client_id"
export OPENQUANTUM_CLIENT_SECRET="your_client_secret"

Token Caching and Auto-Refresh

ClientCredentialsAuth manages JWT tokens automatically:

1. On the first API call, the SDK exchanges your SDK key for a JWT token.
2. The token is cached in memory for the lifetime of the auth object.
3. Before each API call, the SDK checks if the token will expire within the next 30 seconds.
4. If the token is about to expire, a new one is obtained automatically.

You do not need to manage tokens manually.

Organization ID

Every job on Open Quantum belongs to an organization. The Organization ID is a UUID that identifies which organization's credits and job quotas to use. Most users have a single default organization and don't need to set this.

If you do not specify an organization ID, all SDKs auto-discover your organization. If you belong to multiple organizations, the SDK will warn you and pick the first one — pass organization_id explicitly to choose.

Where to find it:

• In the Open Quantum Portal, go to your Account page.
• From the Qiskit plugin: service.organizations() returns a list of your organizations with their IDs and names.
• From the Core SDK: management.list_user_organizations() returns the same information.

Setting it:

Core SDKQiskit PluginPennyLane Plugin

config = JobSubmissionConfig(
    organization_id="your-org-uuid",
    ...
)

backend.run(qc, organization_id="your-org-uuid")

dev = qml.device("openquantum.device", ..., organization_id="your-org-uuid")

Or set the OPENQUANTUM_ORGANIZATION_ID environment variable.

Security Best Practices

• Never commit credentials to version control. Use environment variables or saved accounts.
• Do not hardcode secrets in notebooks or scripts. Use .env files (excluded from git via .gitignore) or environment variables.
• Rotate keys periodically. Delete old SDK keys and create new ones in the portal.
• Disable unused keys. If you are not actively using a key, disable it from the portal to prevent unauthorized use.
• Use one key per environment. Create separate SDK keys for development and production.

Troubleshooting

If authentication fails, see the Troubleshooting page for common error messages and solutions.

Next Steps

• Installation -- Install the SDK and plugins.
• Quick Start -- Submit your first quantum job.