API Keys

2026-02-20 2026-02-20 v0.1.x-beta

1. What is it?

API Keys are bearer tokens that grant programmatic access to the QuantumAPI platform. Each key carries a defined set of scopes, an optional expiry date, IP allowlists, and environment bindings. When created, the raw key value is automatically saved to QuantumVault so it can be retrieved later via its VaultSecretId.

2. What is it for?

CI/CD pipelines

Authenticate automated scripts and pipelines without embedding long-lived user passwords.

SDK & CLI access

Pass the key via --api-key or the QUANTUMAPI_KEY environment variable to authenticate all SDK and CLI calls.

Scoped service accounts

Grant each microservice only the permissions it needs (e.g. encrypt:invoke only, no key management).

Credential rotation

Create a new key, update applications, then revoke the old key without changing code.

3. Key concepts

Term	Definition
API Key	A randomly generated bearer token prefixed with qapi_ used to authenticate REST API, SDK, and CLI requests.
Scope	A permission tag that limits what the key can do. Examples: encrypt:invoke, keys:read, secrets:write.
Prefix	The first 8 characters of the key (e.g. qapi_abc1) shown in the UI to identify the key without revealing the secret.
Key hash	The stored Argon2id hash of the full key. The raw value is never stored; only the hash is kept for verification.
Rate limit	Maximum number of API requests per minute allowed for this key (0 = platform default).
IP allowlist	A list of CIDR ranges from which requests using this key are accepted. Requests from other IPs are rejected.
Environment binding	Restricts the key to a specific environment (production, staging, development) so it cannot be used outside its intended context.
VaultSecretId	The ID of the vault secret where the raw key value is automatically saved on creation. Use this to retrieve the key from the vault later.
Revocation	Permanently disabling a key. Revoked keys are immediately rejected by the API and cannot be re-enabled.

4. How to use it

Creating an API key

Open API Keys

Go to QuantumVault → Keys → API Keys and click New API Key.

Enter a name

Give the key a descriptive name (e.g. my-service-prod). Names must be unique within the tenant.

Select scopes

Choose the minimum set of permissions required. You can select multiple scopes. See the field reference for available scopes.

Set expiry (optional)

Set an expiry date to auto-expire the key. Leave blank for a non-expiring key.

Add restrictions (optional)

Add IP allowlist, environment binding, or referrer restrictions to further limit the key.

Copy the key

The full key value is shown exactly once. Copy it immediately and store it securely. The key is also saved to your Vault automatically (see VaultSecretId below).

Retrieving the key from the Vault

After creation, locate the VaultSecretId on the key detail page. Use it to retrieve the raw value from the vault:

Retrieve raw key value from Vault

GET /api/v1/secrets/{vaultSecretId}/value
Authorization: Bearer <token>

5. Field reference

Field	Type	Required	Description
Name	string	Yes	Human-readable identifier. Unique within the tenant. Max 100 characters.
Scopes	string[]	Yes	List of permission scopes. At least one scope required.
Rate limit	integer	No	Max requests per minute. 0 uses the platform default.
Expires at	ISO 8601 datetime	No	Automatic expiry date. Null for no expiry.
Allowed IPs	CIDR[]	No	IP allowlist. Empty = all IPs allowed.
Environment	production \| staging \| development	No	Restricts key to one environment.
Allowed referrers	string[]	No	HTTP Referer header allowlist for browser-side usage.
Labels	string[]	No	Freeform tags for organisation. Max 10.
VaultSecretId	UUID	Auto	Read-only. Vault secret ID where the raw key is saved on creation.

6. Relationships

QuantumVault

The raw key value is stored as a vault secret on creation. Use VaultSecretId to retrieve it.

Encryption Keys

API Keys authenticate requests that operate on encryption keys (create, rotate, export).

Settings › Usage

Per-key API usage metrics and quota consumption are visible in Settings → Usage.

Access Policies

Access policies on vault resources independently of the API key scopes. Both must allow an operation for it to succeed.

7. FAQ

I lost my API key — can I recover it via VaultSecretId?

Yes. Navigate to QuantumVault → Secrets and open the secret whose ID matches the VaultSecretId on the key detail page. Reveal the value there. If you deleted the vault secret, the key cannot be recovered and must be revoked and re-created.

How do I scope a key for read-only access?

Select only the read-tier scopes when creating the key (e.g. secrets:read, keys:read). Omit any :write or :invoke scopes.

What happens to a key when it expires?

Requests using an expired key receive HTTP 401. The key cannot be renewed — create a new key instead.

Can I have multiple API keys for different environments?

Yes. Create one key per environment and set the Environment binding field accordingly. This prevents a staging key from accidentally being used in production.

Can I temporarily disable a key?

Revocation is permanent. If you need a temporary suspension, set the Expires at field to a date in the past, then update it when you want to re-enable. Alternatively, create a new key when needed.

8. API / CLI reference

Method	Endpoint	Description
GET	/api/v1/api-keys	List all API keys for the tenant.
POST	/api/v1/api-keys	Create a new API key.
GET	/api/v1/api-keys/{id}	Get details for an API key.
PUT	/api/v1/api-keys/{id}	Update name, scopes, or restrictions.
DELETE	/api/v1/api-keys/{id}	Revoke (delete) an API key.

CLI examples

qapi keys list
qapi keys create --name my-service --scopes encrypt:invoke,secrets:read --expires 2027-01-01
qapi keys revoke <key-id>