Skip to main content

API Overview

Qpher API gives your organization's systems the engine behind Qpher Vault: encrypt, sign, verify and manage keys over REST.

Authentication · Error codes

The Qpher API gives you programmatic access to post-quantum cryptographic operations — key encapsulation (KEM), key wrapping, digital signatures, hash-based signatures, key management, and tenant administration — through a single, consistent REST interface.

Base URL​

All API requests are made to:

https://api.qpher.ai

Every endpoint is prefixed with /api/v1/. For example, the KEM encrypt endpoint is:

POST https://api.qpher.ai/api/v1/kem/encrypt

Authentication​

Authenticate every request by including your API key in the X-API-Key header.

Authenticated request
curl -X GET https://api.qpher.ai/api/v1/kms/keys/active?algorithm=Kyber768 \
  -H "X-API-Key: qph_your_key_here" \
  -H "Content-Type: application/json"
Keep your API key secret

Your API key is shown only once at creation time. Store it in a secrets manager or environment variable — never commit it to source control.

Content Type​

All request and response bodies use JSON. Set the Content-Type header on every request:

Content-Type: application/json

Response Format​

Success responses​

Every successful response follows this structure:

{
"data": {
},
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2026-01-15T10:30:00.000Z"
}
FieldTypeDescription
dataobjectThe endpoint-specific result payload.
request_idstring (UUID)Unique identifier for this request. Use it when contacting support.
timestampstring (ISO 8601)UTC timestamp of when the response was generated.

Error responses​

Errors return an error object instead of data:

{
"error": {
"error_code": "ERR_AUTH_001",
"message": "Missing or invalid API key"
},
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": "2026-01-15T10:30:00.000Z"
}
FieldTypeDescription
error.error_codestringA stable, machine-readable code like ERR_KEM_001. See the Error Codes reference.
error.messagestringA human-readable description of what went wrong.
request_idstring (UUID)Same request ID — always include it in bug reports.
timestampstring (ISO 8601)UTC timestamp of the error.

Rate Limiting​

Rate limits are enforced per tenant using a sliding window. The limit depends on your plan: the Developer plan has one band; Qpher Vault Organization has three bands that grow with the organization's seat count; Institution limits are set in the agreement. Key generation and rotation (/kms/keys/generate, /kms/keys/rotate) are limited separately to one request per minute per algorithm. The figures are published in the Acceptable Use Policy, Section 3, which is the authority when this page and the policy differ. Calls made from a Qpher Console session to PQC paths count against the organization's plan band; organizations on a plan that is no longer sold use the seat bands.

When you exceed the limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:

RequestPOST/api/v1/kem/encrypt
X-API-Key: qph_your_key_here
Content-Type: application/json
{
  "plaintext": "SGVsbG8="
}
Response429
{
  "error": {
    "error_code": "ERR_RATE_LIMIT_001",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  },
  "request_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "timestamp": "2026-01-15T10:30:05.000Z"
}
Handling rate limits

Implement exponential backoff in your client. Respect the Retry-After header value to avoid cascading failures.

Rate limits by plan​

PlanHow the limit is set
DeveloperOne fixed band for every Developer tenant
Qpher Vault OrganizationThree bands by the organization's seat count; SLH-DSA and Composite-PQC signing have their own, lower band
InstitutionSet in the agreement

The numbers for each band are in the Acceptable Use Policy, Section 3.

Request IDs​

Every response includes a request_id (UUID). If you send an X-Request-ID header with your request, the API will use your value; otherwise it generates one automatically.

Request IDs are essential for debugging. Always log them on your side, and include them in any support ticket:

X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

HTTP Status Codes​

CodeMeaning
200Success
400Bad request — invalid input or parameters
401Unauthorized — missing or invalid API key
403Forbidden — policy denied the request
404Not found — resource does not exist
409Conflict — duplicate or concurrent operation
422Unprocessable entity — valid JSON but invalid values
429Too many requests — rate limit exceeded
500Internal server error
502Bad gateway — downstream service failure
503Service unavailable — fail-closed safety mode
504Gateway timeout

Supported Algorithms​

Qpher supports the following PQC and hybrid algorithms:

AlgorithmStandardAPI OperationsPlans
ML-KEM-768 (wire value Kyber768)FIPS 203/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrapAll (Key Wrap: paid plans; Key Unwrap: all plans)
ML-DSA-65 (wire value Dilithium3)FIPS 204/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashAll
X-Wing (X25519 + ML-KEM-768)IETF CFRG draft/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrapPaid plans
Composite-ML-DSA (ECDSA P-256 + ML-DSA-65)IETF LAMPS draft/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashPaid plans
ML-KEM-1024 (NIST Category 5)FIPS 203/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulateAll plans
ML-DSA-87 (NIST Category 5)FIPS 204/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashAll plans
SLH-DSA-SHA2 (128s / 128f / 192s / 256s)FIPS 205/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashPaid plans

The Plans column applies to the write side of each operation. Reading what you already protected — /kem/decrypt, /kem/decapsulate, /kem/key/unwrap, /signature/verify and /signature/verify-hash — works on every plan for every algorithm listed, including after a subscription ends, within the Developer plan's monthly limit and rate.

Hybrid PQC + classical algorithms (paid plans)

Hybrid algorithms combine a PQC algorithm with a classical algorithm for defense-in-depth. Add "algorithm": "X-Wing" or "algorithm": "Composite-ML-DSA" to your request body. Omitting the parameter defaults to PQC-only (Kyber768 or Dilithium3). See Security Architecture for details.

CNSA 2.0 algorithm alignment (all plans)

ML-KEM-1024 and ML-DSA-87 are the NIST Category 5 (highest-strength) parameter sets — the algorithms named in the NSA CNSA 2.0 suite for key establishment and digital signatures. The Qpher SDKs expose a single compliance_profile="cnsa-2.0" selector that pins every operation to ML-KEM-1024 + ML-DSA-87 + AES-256-GCM (pure post-quantum — hybrid is off under this profile) and rejects any non-Category-5 override. That pinning is applied by the SDK, on every request. The SDK also sends an X-Compliance-Profile: cnsa-2.0 header to signal intent, but the API does not consume it today — there is no server-side gate that rejects a non-Category-5 algorithm on the basis of the profile.

This is algorithm alignment with the CNSA 2.0 suite — it is not a compliance certification or accreditation. See your SDK's compliance_profile parameter on the SDKs overview.

SLH-DSA — hash-based signatures (FIPS 205, paid plans)

SLH-DSA (Stateless Hash-Based Digital Signature Algorithm) is the third NIST PQC signature standard. Unlike ML-DSA (lattice-based), its security rests on hash functions, giving cryptographic diversification — a break in lattice cryptanalysis does not affect it. Qpher implements the four SHA2 parameter sets:

ValueNIST LevelSignature sizeUse case
SLH-DSA-SHA2-128s1~7.8 KBGeneral hash-based signing (smallest)
SLH-DSA-SHA2-128f1~17 KBLatency-sensitive Level 1
SLH-DSA-SHA2-192s3~16 KBLong-term / archival documents
SLH-DSA-SHA2-256s5~30 KBTop-tier archival

Pass the value in "algorithm" on the signature endpoints. Signatures are larger and signing is slower (~0.3–2 s) than ML-DSA — choose it when you want hash-based diversification or long-term assurance. Qpher implements the FIPS 205 algorithms; this is not a FIPS validation or certification.

OpenAPI Specification​

Download machine-readable OpenAPI 3.1 specs for use with code generators, API clients, or AI tools:

SpecOperationsDownload
Unified (all APIs)18 operationsqpher-api.yaml
KEM API6 operationskem.yaml
Signature API4 operationssignature.yaml
Key Management API5 operationskms.yaml
Tenant API3 operationstenant.yaml
AI-friendly specs

All specs include example values on every field, making them ideal for AI coding assistants and LLM-powered API clients. Point your tool at the unified spec for complete coverage.

Next Steps​