Key Management

This guide covers the complete PQC key lifecycle in Qpher: generating key pairs, listing keys, finding the active key, rotating to a new version, and retiring old keys.

Prerequisites

• A Qpher account with an active API key
• Understanding of which algorithm you need:
  • Kyber768 for encryption/decryption (KEM)
  • Dilithium3 for signing/verification

Key Lifecycle Overview

Active

Encrypt ✓

Decrypt ✓

Sign ✓

Verify ✓

→

Retired

Encrypt ✗

Decrypt ✓

Sign ✗

Verify ✓

→

Archived

All operations ✗

Rotate: Creates new active key, old key becomes retired. Archive: Retired key becomes archived (no operations allowed).

🔒Private Keys Never Leave the Enclave

All private keys are generated, stored, and used exclusively inside the KMS-Orchestrator secure enclave. Private keys are encrypted at rest with AES-256-GCM. No API endpoint can export private key material.

Generate a Key Pair

Generate your first PQC key pair. Each tenant can have one active key per algorithm at a time.

POST/api/v1/kms/keys/generateGenerate a new PQC key pair

Generate a Key Pair

curl -X POST https://api.qpher.ai/api/v1/kms/keys/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: qph_your_key_here" \
  -d '{
    "algorithm": "Kyber768"
  }'

RequestPOST/api/v1/kms/keys/generate

Content-Type: application/json
x-api-key: qph_your_key_here

{
  "algorithm": "Kyber768"
}

Response201

{
  "data": {
    "key_version": 1,
    "algorithm": "Kyber768",
    "status": "active",
    "public_key": "base64-encoded-public-key...",
    "created_at": "2026-02-15T10:00:00Z"
  },
  "request_id": "aaa-bbb-ccc",
  "timestamp": "2026-02-15T10:00:00Z"
}

To generate a Dilithium3 key pair for signing, replace "Kyber768" with "Dilithium3".

List All Keys

Retrieve all key versions for your tenant, across all algorithms and statuses.

GET/api/v1/kms/keysList all PQC keys for your tenant

List All Keys

curl -X GET https://api.qpher.ai/api/v1/kms/keys \
  -H "x-api-key: qph_your_key_here"

Get the Active Key

Retrieve the currently active key for a specific algorithm.

GET/api/v1/kms/keys/active?algorithm=Kyber768Get the active key for an algorithm

Get Active Key

curl -X GET "https://api.qpher.ai/api/v1/kms/keys/active?algorithm=Kyber768" \
  -H "x-api-key: qph_your_key_here"

Rotate a Key

Key rotation creates a new active key version. The previous active key is moved to retired status. Retired keys can still be used for decryption and signature verification.

POST/api/v1/kms/keys/rotateRotate to a new key version

⚠️Plan-Based Rotation Limits

The maximum number of key versions you can maintain depends on your plan tier. Free plans allow up to 3 versions, while Enterprise plans have no limit. Check your plan details for specific quotas.

Rotate a Key

curl -X POST https://api.qpher.ai/api/v1/kms/keys/rotate \
  -H "Content-Type: application/json" \
  -H "x-api-key: qph_your_key_here" \
  -d '{
    "algorithm": "Kyber768"
  }'

Retire a Key

Manually retire a specific key version. Retired keys can no longer encrypt or sign, but can still decrypt and verify.

POST/api/v1/kms/keys/retireRetire a specific key version

Retire a Key

curl -X POST https://api.qpher.ai/api/v1/kms/keys/retire \
  -H "Content-Type: application/json" \
  -H "x-api-key: qph_your_key_here" \
  -d '{
    "algorithm": "Kyber768",
    "key_version": 1
  }'

Error Handling

HTTP Status	Error Code	Cause	Resolution
400	ERR_INVALID_001	Invalid algorithm name	Use "Kyber768" or "Dilithium3"
401	ERR_AUTH_001	Invalid or missing API key	Check your x-api-key header
404	ERR_KMS_003	Key version not found	Verify the key_version exists for your tenant
409	ERR_KMS_004	Active key already exists for this algorithm	Use rotate instead of generate to create a new version
409	ERR_KMS_005	Cannot retire the only active key	Generate or rotate a new key before retiring the current one
429	ERR_RATE_001	Rate limit exceeded	Reduce request frequency or upgrade your plan

Related Guides

• Key Versioning — Understand why explicit key versions matter
• Encrypt Data — Use your KEM keys for encryption
• Sign Documents — Use your signing keys for digital signatures
• Migration Guide — Plan your PQC migration strategy