SDK Overview

Thin wrappers over Qpher API for Python, Node.js and Go.

Python SDK · Node.js SDK

Qpher provides official SDKs for three languages. Each SDK is a thin wrapper around the Qpher REST API — the high-level encrypt / sign methods run cryptography server-side at Qpher, where your private keys are generated and used only inside the isolated key service (KMS-Orchestrator), while the encapsulate and key/wrap methods support client-side encryption, where your plaintext never leaves your environment. The SDKs handle authentication, serialization, retries, and error mapping so you can integrate post-quantum cryptography in minutes.

Design Philosophy

Qpher SDKs follow a strict set of principles:

• Server-side by default, client-side when you need it. The high-level encrypt / decrypt / sign methods use server-side mode. Sent to Qpher over TLS, processed in memory, never stored. Nothing to compile, no native dependencies. When plaintext must never leave your environment, the encapsulate / key/wrap methods enable client-side encryption (you run AES-256-GCM locally; your plaintext is never sent to Qpher). Either way, private keys are generated and used only inside Qpher's isolated key service. See Where does my data go?.
• HTTP client under the hood. Every SDK method maps directly to a single REST API call. There is no hidden state, no local caching of keys, and no background threads. If you already have an HTTP client you prefer, you can call the REST API directly.
• Consistent across languages. Method names, parameter shapes, and error codes are the same in Python, Node.js, and Go. Code examples in one language translate naturally to the others.

Available SDKs

pip install qpher

Language	Package	Registry	Min Version	Reference
Python	qpher	PyPI	Python 3.9+	Python SDK
Node.js	@qpher/sdk	npm	Node 18+	Node.js SDK
Go	github.com/qpher/qpher-go	Go Modules	Go 1.21+	Go SDK

Features

Every Qpher SDK includes the following capabilities out of the box:

Authentication

Pass your API key once when you create the client. The SDK attaches it as the X-API-Key header on every request. No manual header management required.

KEM Encryption and Decryption

Encrypt arbitrary data with Kyber768 (ML-KEM-768) and decrypt it later. The SDK accepts raw bytes and returns raw bytes — base64 encoding for the wire format is handled automatically.

Digital Signatures

Sign messages with Dilithium3 (ML-DSA-65) and verify signatures. Signatures are returned as bytes; encoding and decoding happen transparently.

Key Management

Generate new key pairs, list keys, retrieve the currently active key or a specific version, rotate to a new key version, and retire old versions — all through the SDK.

Typed Errors

Every SDK defines a dedicated error class (QpherError in Python and Node.js, qpher.Error in Go) with structured fields:

Field	Description
error_code	Machine-readable code such as ERR_AUTH_001 or ERR_KEM_005
message	Human-readable description of the problem
status_code	HTTP status code from the API
request_id	UUID for the request, useful when contacting support

Automatic Base64 Encoding

PQC ciphertexts and signatures are binary data. The SDK automatically base64-encodes outgoing binary fields and base64-decodes incoming fields so you work with native byte types in your language.

Retries with Backoff

Transient failures (HTTP 429, 502, 503, 504) are retried automatically with exponential backoff. You can configure max_retries (default: 3) and timeout (default: 30 seconds) when creating the client.

Request ID Propagation

Every response includes a request_id. If you supply your own X-Request-ID header, the SDK forwards it for end-to-end tracing through Qpher's infrastructure.

Quick Comparison

Initialize the client

from qpher import Qpher

client = Qpher(api_key="qph_your_key_here")

Encrypt data with Kyber768

result = client.kem.encrypt(plaintext=b"sensitive data", key_version=1)
print(result.ciphertext)  # bytes

ℹ️Hybrid algorithms available (Pro/Enterprise)

Qpher supports hybrid PQC + classical algorithms: X-Wing (X25519 + ML-KEM-768) for encryption and Composite ML-DSA (ECDSA P-256 + ML-DSA-65) for signatures. Pass the optional algorithm parameter to opt in. Existing code without this parameter continues to use PQC-only algorithms.

Why hybrid? Hybrid mode provides defense-in-depth: if a lattice cryptanalysis breakthrough weakens PQC algorithms, the classical component still protects your data. This approach is used by AWS, Google Cloud, and Cloudflare.

See Security Architecture for details.

Next Steps

• Python SDK Reference — full API, error handling, and examples
• Node.js SDK Reference — TypeScript types and async patterns
• Go SDK Reference — context-based API and error unwrapping
• REST API Reference — raw HTTP and cURL for any language

💡Which SDK should I choose?

Pick the language your backend is written in. All three SDKs have feature parity. If your stack is not Python, Node.js, or Go, use the REST API directly — every SDK operation maps to a single HTTP call.