Skip to content

Authentication

QLAM uses OAuth2 for authentication. This guide helps you choose the right authentication method for your use case.

For technical details on each flow, see the Authentication Reference.

Choosing an Authentication Method

Method Use Case
Authorization Code Users at a workstation with browser access
Device Code SSH sessions, containers, remote servers, HPC Environments
Machine-to-Machine CI/CD pipelines, service accounts, batch jobs, HPC Environments
Token Refresh Extending sessions without re-authenticating

Note

Refresh tokens can be used with any initial authentication method to obtain a new access token without user interaction.

Interactive Users

Method: OAuth2 Authorization Code Flow

Use this when a user is working interactively at a workstation with browser access.

Typical scenarios:

  • Developer running experiments from their laptop
  • Researcher submitting jobs from a desktop workstation
  • Anyone using QLAM Shell interactively

How it works:

  1. Run qsh auth login
  2. Browser opens for authentication
  3. Credentials are cached locally for future use

This is the default method used by QLAM Shell and Bloqade SDK.

Headless Environments

Method: Device Code Flow

Use this when you need to authenticate but don't have direct browser access on the machine.

Typical scenarios:

  • HPC Environments (one-time login + Refresh; e.g., Slurm, PBS)
  • SSH session to a remote compute cluster
  • Running inside a Docker container
  • Jupyter notebook on a remote server

How it works:

  1. Application displays a code and URL
  2. User visits the URL on any device (phone, laptop)
  3. User enters the code and authenticates
  4. Application receives credentials

This allows authentication from any environment while keeping credentials secure. If used with refresh tokens, this is a one-time login on the device.

Automated Systems

Method: Machine-to-Machine (M2M)

Use this for automated systems that run without user interaction.

Typical scenarios:

  • HPC Environments (e.g. Slurm, PBS)
  • CI/CD pipelines running quantum benchmarks
  • Scheduled batch jobs submitting tasks overnight
  • Backend services integrating with QLAM
  • Automated testing frameworks

How it works:

  1. Obtain M2M credentials (client ID + secret/private-key) from your QLAM administrator
  2. Application authenticates directly using credentials
  3. No user interaction required

Important considerations:

  • M2M credentials are long-lived secrets—store them securely.
  • Credentials do not support supplying user context with requests. This means all requests are performed as the machine account.
  • Use environment variables or secret managers, never commit to code
  • Cache M2M tokens until expiration—the identity provider enforces a monthly limit on token requests. See the M2M reference for details.

Long-Running Sessions

Method: Token Refresh

Use refresh tokens to extend your session without re-authenticating.

Typical scenarios:

  • Long-running scripts that may outlive the access token (24 hours)
  • Applications that need to maintain access across multiple days
  • Avoiding interruption for re-authentication during batch processing

How it works:

  1. Initial authentication provides both access and refresh tokens
  2. Before access token expires, use refresh token to get a new one
  3. Each refresh also provides a new refresh token (rotation)

Note

QLAM Shell, QLAM Core, and Bloqade are able to handle token refresh automatically by invoking the correct method. You only need to manage this manually when using Direct API access or building custom integrations.

Enterprise SSO

For enterprise environments with existing identity providers, see SSO Integration.

Roadmap

We're working on additional authentication methods:

  • Certificate Authentication - mTLS client certificates for high-security environments

Need an authentication method we don't support yet? Let us know!

Next Steps