Skip to main content

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​

Private Keys Are Never Exported

Private keys are generated and used only inside Qpher's isolated key service. No API can export them. At rest they are encrypted with a Google Cloud KMS key.

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
Version limit

Each algorithm can hold up to 100 key versions that still hold a private key (active or retired). To make room, an organization owner or admin archives retired versions in Qpher Portal, confirming with a fresh second factor (a TOTP code, or the account password when MFA is off). A version can be archived 24 hours after it is retired, and not while Qpher Vault data still depends on it. Archive is irreversible and is not available through the API, SDKs, CLI or MCP server.

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 StatusError CodeCauseResolution
400ERR_INVALID_001Generate while the algorithm already has an active key, or retire a key that is not activeUse rotate to create a new version
401ERR_AUTH_001Invalid or missing API keyCheck your x-api-key header
403ERR_POLICY_001Your plan does not include this operation or algorithmCheck your plan in Qpher Portal
403ERR_KMS_020Archive requested with an API keyAn organization owner or admin archives keys in Qpher Portal
403ERR_KMS_025Archive, or its pre-check, requested in Qpher Portal by an organization member who is not an owner or adminAsk an organization owner or admin
404ERR_NOT_FOUND_001Key version not found, or no active key to rotateList your keys with GET /api/v1/kms/keys; generate a key first
409ERR_KMS_021The algorithm already has 100 key versions that still hold a private key (active or retired)An organization owner or admin archives retired versions in Qpher Portal, then generate or rotate
422ERR_INVALID_001Invalid request body, for example an unknown algorithm nameCheck the algorithm name and required fields
429ERR_RATE_LIMIT_001Rate limit exceededRetry after the Retry-After interval