Documentation

API Reference & Guides

Everything you need to integrate PostQ into your applications and infrastructure.

Introduction

PostQ provides a REST API and SDKs for integrating quantum-safe cryptography into your applications. The API supports hybrid signing (classical + post-quantum), key management, cryptographic scanning, and policy enforcement.

All API endpoints are available at https://api.postq.io/v1 and require authentication via Bearer token.

💡

Base URL: All API paths in this documentation are relative to https://api.postq.io/v1

Quickstart

Install the PostQ SDK and create your first hybrid signature in under 5 minutes.

1. Install the SDK

Terminal

npm install @postq/sdk

2. Sign and verify

app.ts

import { PostQ } from "@postq/sdk";

const pq = new PostQ({
  apiKey: process.env.POSTQ_API_KEY,
  environment: "production"
});

// Sign a message with hybrid cryptography
const signature = await pq.sign({
  payload: Buffer.from("Hello Quantum World"),
  algorithm: "dilithium3+ed25519",
  keyId: "vault://signing/production"
});

console.log(signature.algorithm);
// → "dilithium3+ed25519"

// Verify the hybrid signature
const isValid = await pq.verify({
  payload: Buffer.from("Hello Quantum World"),
  signature: signature.combined,
  keyId: "vault://signing/production"
});

console.log(isValid);
// → true

Authentication

All API requests must include a Bearer token in the Authorization header. You can generate API keys from the PostQ dashboard under Settings → API Keys.

auth-example.ts

// All API requests require a Bearer token
const headers = {
  "Authorization": "Bearer pq_live_sk_...",
  "Content-Type": "application/json"
};

// Test your authentication
const response = await fetch("https://api.postq.io/v1/whoami", {
  headers
});

const { org, environment, permissions } = await response.json();
// → org: "acme-corp"
// → environment: "production"
// → permissions: ["sign", "verify", "scan", "policy:read"]

⚠️

Security: Never expose your API keys in client-side code. Use environment variables and server-side API calls only.

POST /v1/sign

Create a hybrid signature that combines a classical signature with a post-quantum signature. The resulting composite signature is valid if either component is verified.

POST /v1/sign

POST /v1/sign

Request:
{
  "payload": "base64-encoded-data",
  "algorithm": "dilithium3+ed25519",
  "key_id": "vault://signing/production",
  "context": {
    "service": "payment-api",
    "environment": "production"
  }
}

Response (200 OK):
{
  "signature": "base64-combined-signature",
  "classical_sig": "base64-ed25519-signature",
  "pq_sig": "base64-dilithium3-signature",
  "algorithm": "dilithium3+ed25519",
  "key_id": "vault://signing/production",
  "timestamp": "2026-04-05T12:00:00Z",
  "policy_compliant": true
}

POST /v1/verify

Verify a hybrid signature. Returns the validity of both the classical and post-quantum components independently.

POST /v1/verify

POST /v1/verify

Request:
{
  "payload": "base64-encoded-data",
  "signature": "base64-combined-signature",
  "key_id": "vault://signing/production"
}

Response (200 OK):
{
  "valid": true,
  "classical_valid": true,
  "pq_valid": true,
  "algorithm": "dilithium3+ed25519",
  "key_id": "vault://signing/production"
}

GET /v1/keys

List all cryptographic keys managed by PostQ, including their algorithm type, backend, and PQ-readiness status.

GET /v1/keys

GET /v1/keys

Response (200 OK):
{
  "keys": [
    {
      "id": "vault://signing/production",
      "algorithm": "dilithium3+ed25519",
      "created_at": "2026-01-15T08:00:00Z",
      "status": "active",
      "backend": "azure-key-vault",
      "pq_ready": true
    },
    {
      "id": "vault://signing/staging",
      "algorithm": "ed25519",
      "created_at": "2025-06-01T10:00:00Z",
      "status": "active",
      "backend": "hashicorp-vault",
      "pq_ready": false
    }
  ]
}

POST /v1/scan

Trigger a quantum risk scan across specified targets. Returns a comprehensive report of cryptographic algorithm usage and risk assessment.

POST /v1/scan

POST /v1/scan

Request:
{
  "targets": ["kubernetes://production", "azure://subscription-id"],
  "depth": "full",
  "include": ["tls", "signing", "encryption"]
}

Response (200 OK):
{
  "scan_id": "scan_abc123",
  "status": "completed",
  "summary": {
    "total_endpoints": 4184,
    "quantum_vulnerable": 3012,
    "risk_score": 72,
    "recommendation": "Begin hybrid migration for signing keys"
  }
}

Hybrid Signatures

Hybrid signatures combine two independent signature algorithms into a single composite signature. This approach is recommended by NIST during the transition period to post-quantum cryptography.

Supported algorithm combinations

Algorithm	Classical	Post-Quantum	Security Level
dilithium3+ed25519	Ed25519	ML-DSA-65	NIST Level 3
dilithium5+p384	ECDSA P-384	ML-DSA-87	NIST Level 5
falcon512+ed25519	Ed25519	Falcon-512	NIST Level 1