メインコンテンツまでスキップ

API Access Tokens

API Access Tokens enable secure, programmatic access to Quapp Functions without requiring interactive login. They are designed for developers who want to integrate Quapp into external systems, automation workflows, backend services, or CI/CD pipelines.

Each access token is scoped to a specific project and specific functions, ensuring controlled and auditable access.

What is an API Access Token?​

An API Access Token is a credential that allows your application to:

  • Invoke Quapp Functions via REST APIs
  • Submit quantum jobs programmatically
  • Query job execution results
  • Integrate Quapp into external systems

Tokens are project-scoped, permission-based, and revocable.

Token Ownership and Permissions​

  • API Access Tokens can only be created by Project Admins

  • Each token is associated with:

    • A single project
    • One or more selected functions
    • An optional expiration date

  • Tokens cannot access functions outside their assigned scope

This design ensures that API access follows the same security and permission model as the Quapp UI.

Token Lifecycle Overview​

An API Access Token goes through the following lifecycle:

  1. Created by a Project Admin
  2. Used by external clients to invoke functions
  3. Expires automatically (if an expiration date is set)
  4. Rotated or refreshed using a refresh token
  5. Revoked when no longer needed

For security reasons, the token value is only shown once at creation time.

Required Identifiers for API Invocation​

To invoke a function using an API Access Token, the following identifiers are required:

  • Project ID – Identifies the project context
  • Function Name – Specifies which function to execute
  • Device ID – Defines the target execution device

These identifiers are available through the Quapp UI and developer tools and remain consistent with what is shown in the web application.

Invoking Functions via API​

Quapp provides a dedicated API endpoint for invoking functions using API Access Tokens.

The invocation request includes:

  • Authorization via Bearer Token

  • Project context via X-Project-Id

  • Function execution parameters such as:

    • Function name
    • Target device
    • Number of shots
    • Input payload

Once invoked, the system immediately returns a Job ID, which represents the execution request.

Job Execution and Monitoring​

Every API invocation creates a job that follows Quapp’s standard execution lifecycle.

Jobs may transition through multiple states, including:

  • Created
  • Queued
  • Running
  • Completed
  • Failed

Job details can be retrieved via a dedicated API endpoint using the Job ID returned at invocation time. This allows external systems to monitor execution progress and retrieve results once the job is complete.

Job Status Reference​

Jobs executed via API follow the same status model as jobs submitted from the UI:

  • NEW – Job created
  • INITIALIZING – Resources are being prepared
  • IN_QUEUE – Waiting for execution
  • RUNNING – Currently executing
  • DONE – Successfully completed
  • ERROR – Execution failed
  • IN_DEAD_LETTER_QUEUE – Failed after multiple retries

This unified model ensures consistency across UI and API usage.

Rate Limiting​

To ensure platform stability and fair usage, API invocations are rate-limited:

  • 3 requests per 10 seconds per token

If the limit is exceeded, the API responds with an HTTP 429 error. Clients are expected to implement retry logic and respect rate limits.

Refreshing Access Tokens​

API Access Tokens are paired with a Refresh Token.

When an access token expires or is about to expire, a refresh token can be used to request a new access token without recreating the token configuration.

Key points:

  • Refresh tokens are exchanged for new access tokens
  • A new refresh token is issued with every refresh request
  • Clients must always store the latest refresh token

This mechanism supports long-running integrations without compromising security.

Security Best Practices​

When using API Access Tokens, Quapp recommends:

  • Assigning tokens only to required functions
  • Setting expiration dates whenever possible
  • Rotating tokens periodically
  • Storing tokens securely (environment variables or secret managers)
  • Revoking unused or compromised tokens immediately

When to Use API Access Tokens​

API Access Tokens are ideal for:

  • Backend services invoking quantum functions
  • Automated workflows and pipelines
  • Integration with external platforms
  • Scheduled or batch execution of quantum jobs

They are not intended for end-user interactive access, which should continue to use the Quapp web interface.