API Reference

Complete v2 REST API documentation. All endpoints are under https://api.quantaseal.io/api/v2/

Base URL:https://api.quantaseal.ioVersion:v2Format:JSON

Authentication#

Use the X-API-Key header for API key authentication. JWT tokens from /auth/login use Authorization: Bearer.

bash

X-API-Key: qs_live_your_key_here

POST/api/v2/auth/loginNone

Exchange email + password for a JWT access token (30 min) and refresh token (7 days). Sets httpOnly cookies.

Request Body

email: string (required)

password: string (required)

Response

access_token: string - JWT (HS256 + optional ML-DSA-65 PQC layer)

expires_in: number - seconds until expiry

user: object - id, email, role, tenant_id

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

POST/api/v2/auth/registerNone

Create a new user and tenant. Starts a 14-day free trial. Sends verification email via Resend.

Request Body

email: string (required)

password: string (required)

tenant_name: string (required)

Response

user_id: string

tenant_id: string

message: string - verification email sent

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "strong_pass", "tenant_name": "Acme Corp"}'

POST/api/v2/auth/refreshCookie (refreshToken)

Exchange a valid refresh token cookie for a new access token. Called automatically by the SDK on 401.

Response

access_token: string - new JWT

expires_in: number

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/auth/refresh \
  -H "Cookie: refreshToken=<your_refresh_token>"

Vault API#

Store and retrieve credentials with 3-layer PQC encryption: ML-KEM-768 → AWS KMS-wrap → AES-256-GCM. All vault endpoints return a uniform 403 on any error to prevent credential enumeration.

POST/api/v2/vault/sealRequired

Store a credential with 3-layer PQC encryption. Returns credential_id.

Request Body

credential_type: string (required) - api_key | oauth2_token | basic_auth | ...

values: object (required) - key/value credential payload

ttl_days: number (optional) - auto-expire after N days

Response

credential_id: string - UUID

credential_type: string

created_at: string - ISO 8601

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/vault/seal \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-production-key",
    "credential_type": "api_key",
    "values": {"key": "sk_live_abc123"},
    "ttl_days": 90
  }'

GET/api/v2/vault/listRequired

List all vault entries for the authenticated tenant. Returns metadata only - no plaintext values.

Response

entries: array - [{credential_id, name, credential_type, created_at, expires_at}]

total: number

Example

bash

curl https://api.quantaseal.io/api/v2/vault/list \
  -H "X-API-Key: qs_live_..."

GET/api/v2/vault/{credential_id}Required

Unseal (decrypt and retrieve) a credential. Verifies ML-DSA-65 + HMAC-SHA-512 before decryption. Returns uniform 403 on any error.

Response

credential_id: string

values: object - decrypted key/value payload

algorithm: ML-KEM-768

Example

bash

curl https://api.quantaseal.io/api/v2/vault/cred_abc123 \
  -H "X-API-Key: qs_live_..."

POST/api/v2/vault/rotate/{credential_id}Required

Re-encrypt a vault entry with a new ML-KEM-768 key pair. Old ciphertext is securely deleted.

Response

credential_id: string

rotated_at: string - ISO 8601

new_key_id: string

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/vault/rotate/cred_abc123 \
  -H "X-API-Key: qs_live_..."

DELETE/api/v2/vault/{credential_id}Required

Permanently delete a vault entry and its ciphertext. Logged to the immutable audit chain.

Response

deleted: boolean

credential_id: string

Example

bash

curl -X DELETE https://api.quantaseal.io/api/v2/vault/cred_abc123 \
  -H "X-API-Key: qs_live_..."

Encryption API#

Encrypt and sign arbitrary data. Hybrid mode is mandatory: ML-KEM-768 encap → HKDF-SHA-512 → AES-256-GCM. Both signatures (ML-DSA-65 + HMAC-SHA-512) are verified with bitwise & - neither short-circuits.

POST/api/v2/encryption/encryptRequired

Encrypt arbitrary data using ML-KEM-768 + AES-256-GCM hybrid encryption (NIST FIPS 203).

Request Body

data: string (required) - plaintext to encrypt

algorithm: string (optional) - default: ML-KEM-768

Response

ciphertext_kem: string - base64, exactly 1088 bytes ML-KEM-768

ciphertext_data: string - base64, AES-256-GCM ciphertext

algorithm: ML-KEM-768

tenant_id: string

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/encrypt \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "sensitive customer PII", "algorithm": "ML-KEM-768"}'

POST/api/v2/encryption/decryptRequired

Decrypt a ciphertext envelope produced by /encrypt. Signature verification runs before decryption.

Request Body

ciphertext_kem: string (required)

ciphertext_data: string (required)

nonce: string (required)

Response

data: string - decrypted plaintext

algorithm: string

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/decrypt \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ciphertext_kem": "...", "ciphertext_data": "...", "nonce": "..."}'

POST/api/v2/encryption/signRequired

Sign data with ML-DSA-65 (NIST FIPS 204) + HMAC-SHA-512. Returns both signatures - both must be present.

Request Body

data: string (required) - data to sign

Response

pqc_signature: string - base64, ~3309 bytes ML-DSA-65

hmac_signature: string - base64, 64 bytes HMAC-SHA-512

algorithm: ML-DSA-65+HMAC-SHA-512

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/sign \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "payload to sign"}'

POST/api/v2/encryption/verifyRequired

Verify ML-DSA-65 + HMAC-SHA-512 signatures. Both must pass - verified with bitwise & (no short-circuit).

Request Body

data: string (required)

pqc_signature: string (required)

hmac_signature: string (required)

Response

valid: boolean - true only if both signatures pass

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/verify \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "payload", "pqc_signature": "...", "hmac_signature": "..."}'

Compliance API#

Generate compliance reports from the immutable audit hash chain. Supported frameworks: soc2, iso27001, pci_dss, hipaa, gdpr, nist_csf, fedramp, apra, nist_800_53

GET/api/v2/compliance/score?framework=soc2Required

Get the compliance score (0–100) for a framework. Reads from the live audit hash chain.

Response

framework: string - soc2 | iso27001 | pci_dss | ...

score: number - 0 to 100

controls_passed: number

controls_total: number

Example

bash

curl "https://api.quantaseal.io/api/v2/compliance/score?framework=soc2" \
  -H "X-API-Key: qs_live_..."

GET/api/v2/compliance/report?framework=soc2Required

Generate a PDF compliance report with evidence citations. Returns a signed S3 URL (1h expiry).

Response

framework: string

score: number

pdf_url: string - signed S3 URL, expires in 1 h

generated_at: string - ISO 8601

Example

bash

curl "https://api.quantaseal.io/api/v2/compliance/report?framework=soc2" \
  -H "X-API-Key: qs_live_..."

Audit API#

Query the immutable audit log. Every entry is ML-DSA-65 signed and chained with SHA3-256 hashes. Supports filtering by event type, user, and time range.

GET/api/v2/audit/logsRequired

Retrieve audit log entries from the SHA3-256 hash chain. Immutable - every entry is ML-DSA-65 signed.

Response

logs: array - [{id, event_type, tenant_id, user_id, prev_hash, current_hash, created_at}]

total: number

Example

bash

curl "https://api.quantaseal.io/api/v2/audit/logs?event_type=CREDENTIAL_UNSEALED&hours=24" \
  -H "X-API-Key: qs_live_..."

Error Codes#

Standard HTTP response codes. Error details are never included in response bodies - only generic messages. This prevents information leakage.

Code	Name	Description
`400`	Bad Request	Invalid request parameters or malformed JSON
`401`	Unauthorized	Missing or invalid API key / expired access token
`403`	Forbidden	Insufficient permissions - vault endpoints always return 403 to prevent enumeration
`422`	Unprocessable Entity	Request body failed Pydantic validation - check field types
`429`	Too Many Requests	Rate limit exceeded - check Retry-After header (jittered)
`500`	Internal Server Error	Server error - details are never included in the response body
`503`	Service Unavailable	Temporary disruption - retry with exponential backoff

Error response envelope:

json

{
  "success": false,
  "error": {
    "code": 403,
    "message": "Access denied",
    "request_id": "req_abc123",
    "timestamp": "2026-05-24T10:30:00Z"
  }
}

Rate Limits#

Rate limits are enforced per tenant per minute. Responses include rate limit headers. On 429, a jittered Retry-After header is present.

1,000

req/min

Starter

5,000

req/min

Professional

10,000

req/min

Growth

Unlimited

Enterprise

http

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1748080800
Retry-After: 12   # jittered - present only on 429

Getting Started CLI Reference

API Reference

Complete v2 REST API documentation. All endpoints are under https://api.quantaseal.io/api/v2/

Base URL:https://api.quantaseal.ioVersion:v2Format:JSON

Authentication#

Use the X-API-Key header for API key authentication. JWT tokens from /auth/login use Authorization: Bearer.

bash

X-API-Key: qs_live_your_key_here

POST/api/v2/auth/loginNone

Exchange email + password for a JWT access token (30 min) and refresh token (7 days). Sets httpOnly cookies.

Request Body

email: string (required)

password: string (required)

Response

access_token: string - JWT (HS256 + optional ML-DSA-65 PQC layer)

expires_in: number - seconds until expiry

user: object - id, email, role, tenant_id

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'

POST/api/v2/auth/registerNone

Create a new user and tenant. Starts a 14-day free trial. Sends verification email via Resend.

Request Body

email: string (required)

password: string (required)

tenant_name: string (required)

Response

user_id: string

tenant_id: string

message: string - verification email sent

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "strong_pass", "tenant_name": "Acme Corp"}'

POST/api/v2/auth/refreshCookie (refreshToken)

Exchange a valid refresh token cookie for a new access token. Called automatically by the SDK on 401.

Response

access_token: string - new JWT

expires_in: number

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/auth/refresh \
  -H "Cookie: refreshToken=<your_refresh_token>"

Vault API#

Store and retrieve credentials with 3-layer PQC encryption: ML-KEM-768 → AWS KMS-wrap → AES-256-GCM. All vault endpoints return a uniform 403 on any error to prevent credential enumeration.

POST/api/v2/vault/sealRequired

Store a credential with 3-layer PQC encryption. Returns credential_id.

Request Body

credential_type: string (required) - api_key | oauth2_token | basic_auth | ...

values: object (required) - key/value credential payload

ttl_days: number (optional) - auto-expire after N days

Response

credential_id: string - UUID

credential_type: string

created_at: string - ISO 8601

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/vault/seal \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "stripe-production-key",
    "credential_type": "api_key",
    "values": {"key": "sk_live_abc123"},
    "ttl_days": 90
  }'

GET/api/v2/vault/listRequired

List all vault entries for the authenticated tenant. Returns metadata only - no plaintext values.

Response

entries: array - [{credential_id, name, credential_type, created_at, expires_at}]

total: number

Example

bash

curl https://api.quantaseal.io/api/v2/vault/list \
  -H "X-API-Key: qs_live_..."

GET/api/v2/vault/{credential_id}Required

Unseal (decrypt and retrieve) a credential. Verifies ML-DSA-65 + HMAC-SHA-512 before decryption. Returns uniform 403 on any error.

Response

credential_id: string

values: object - decrypted key/value payload

algorithm: ML-KEM-768

Example

bash

curl https://api.quantaseal.io/api/v2/vault/cred_abc123 \
  -H "X-API-Key: qs_live_..."

POST/api/v2/vault/rotate/{credential_id}Required

Re-encrypt a vault entry with a new ML-KEM-768 key pair. Old ciphertext is securely deleted.

Response

credential_id: string

rotated_at: string - ISO 8601

new_key_id: string

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/vault/rotate/cred_abc123 \
  -H "X-API-Key: qs_live_..."

DELETE/api/v2/vault/{credential_id}Required

Permanently delete a vault entry and its ciphertext. Logged to the immutable audit chain.

Response

deleted: boolean

credential_id: string

Example

bash

curl -X DELETE https://api.quantaseal.io/api/v2/vault/cred_abc123 \
  -H "X-API-Key: qs_live_..."

Encryption API#

POST/api/v2/encryption/encryptRequired

Encrypt arbitrary data using ML-KEM-768 + AES-256-GCM hybrid encryption (NIST FIPS 203).

Request Body

data: string (required) - plaintext to encrypt

algorithm: string (optional) - default: ML-KEM-768

Response

ciphertext_kem: string - base64, exactly 1088 bytes ML-KEM-768

ciphertext_data: string - base64, AES-256-GCM ciphertext

algorithm: ML-KEM-768

tenant_id: string

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/encrypt \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "sensitive customer PII", "algorithm": "ML-KEM-768"}'

POST/api/v2/encryption/decryptRequired

Decrypt a ciphertext envelope produced by /encrypt. Signature verification runs before decryption.

Request Body

ciphertext_kem: string (required)

ciphertext_data: string (required)

nonce: string (required)

Response

data: string - decrypted plaintext

algorithm: string

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/decrypt \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ciphertext_kem": "...", "ciphertext_data": "...", "nonce": "..."}'

POST/api/v2/encryption/signRequired

Sign data with ML-DSA-65 (NIST FIPS 204) + HMAC-SHA-512. Returns both signatures - both must be present.

Request Body

data: string (required) - data to sign

Response

pqc_signature: string - base64, ~3309 bytes ML-DSA-65

hmac_signature: string - base64, 64 bytes HMAC-SHA-512

algorithm: ML-DSA-65+HMAC-SHA-512

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/sign \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "payload to sign"}'

POST/api/v2/encryption/verifyRequired

Verify ML-DSA-65 + HMAC-SHA-512 signatures. Both must pass - verified with bitwise & (no short-circuit).

Request Body

data: string (required)

pqc_signature: string (required)

hmac_signature: string (required)

Response

valid: boolean - true only if both signatures pass

Example

bash

curl -X POST https://api.quantaseal.io/api/v2/encryption/verify \
  -H "X-API-Key: qs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"data": "payload", "pqc_signature": "...", "hmac_signature": "..."}'

Compliance API#

Generate compliance reports from the immutable audit hash chain. Supported frameworks: soc2, iso27001, pci_dss, hipaa, gdpr, nist_csf, fedramp, apra, nist_800_53

GET/api/v2/compliance/score?framework=soc2Required

Get the compliance score (0–100) for a framework. Reads from the live audit hash chain.

Response

framework: string - soc2 | iso27001 | pci_dss | ...

score: number - 0 to 100

controls_passed: number

controls_total: number

Example

bash

curl "https://api.quantaseal.io/api/v2/compliance/score?framework=soc2" \
  -H "X-API-Key: qs_live_..."

GET/api/v2/compliance/report?framework=soc2Required

Generate a PDF compliance report with evidence citations. Returns a signed S3 URL (1h expiry).

Response

framework: string

score: number

pdf_url: string - signed S3 URL, expires in 1 h

generated_at: string - ISO 8601

Example

bash

curl "https://api.quantaseal.io/api/v2/compliance/report?framework=soc2" \
  -H "X-API-Key: qs_live_..."

Audit API#

Query the immutable audit log. Every entry is ML-DSA-65 signed and chained with SHA3-256 hashes. Supports filtering by event type, user, and time range.

GET/api/v2/audit/logsRequired

Retrieve audit log entries from the SHA3-256 hash chain. Immutable - every entry is ML-DSA-65 signed.

Response

logs: array - [{id, event_type, tenant_id, user_id, prev_hash, current_hash, created_at}]

total: number

Example

bash

curl "https://api.quantaseal.io/api/v2/audit/logs?event_type=CREDENTIAL_UNSEALED&hours=24" \
  -H "X-API-Key: qs_live_..."

Error Codes#

Standard HTTP response codes. Error details are never included in response bodies - only generic messages. This prevents information leakage.

Code	Name	Description
`400`	Bad Request	Invalid request parameters or malformed JSON
`401`	Unauthorized	Missing or invalid API key / expired access token
`403`	Forbidden	Insufficient permissions - vault endpoints always return 403 to prevent enumeration
`422`	Unprocessable Entity	Request body failed Pydantic validation - check field types
`429`	Too Many Requests	Rate limit exceeded - check Retry-After header (jittered)
`500`	Internal Server Error	Server error - details are never included in the response body
`503`	Service Unavailable	Temporary disruption - retry with exponential backoff

Error response envelope:

json

{
  "success": false,
  "error": {
    "code": 403,
    "message": "Access denied",
    "request_id": "req_abc123",
    "timestamp": "2026-05-24T10:30:00Z"
  }
}

Rate Limits#

Rate limits are enforced per tenant per minute. Responses include rate limit headers. On 429, a jittered Retry-After header is present.

1,000

req/min

Starter

5,000

req/min

Professional

10,000

req/min

Growth

Unlimited

Enterprise

http

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1748080800
Retry-After: 12   # jittered - present only on 429

Getting Started CLI Reference