Works in Flask, FastAPI, Django, scripts, and any Python 3.9+ environment. Type hints included — no separate stubs needed. cryptography>=48.0.0 is included as an automatic dependency — no extra install needed for CA operations or key generation.

pip install fipsign-sdk

pip install fipsign-sdk[async]

from fipsign import PQAuth

pq = PQAuth("pqa_your_api_key")

# Or with all options (see PY 10 for full reference):
# pq = PQAuth(
#     api_key="pqa_your_api_key",
#     base_url="https://api.fipsign.dev",  # default
#     timeout=10,                          # seconds, default 10
#     session=None,                        # custom requests.Session
# )

Signs any payload with ML-DSA (44, 65, or 87 — configured per project at creation). The only required argument is sub — any string identifying the entity. All other keyword arguments are stored in the payload and returned on verify. Cost: 1 token.

result = pq.sign("user_123", email="[email protected]", role="admin", expires_in_seconds=3600)
token  = result.token
meta   = result.meta
usage  = result.usage

result = pq.sign("order_456", amount=299.99, currency="USD", expires_in_seconds=300)

result = pq.sign("doc_789", hash="sha256:abc...", signed_by="alice")

result = pq.sign(
    "agent_summarizer_v2",
    action="document:summarize",
    user_id="user_123",
    trace_id="trace_abc",
)

result = pq.sign("device_iot_001", firmware="2.1.4", location="plant-A")

result = pq.sign("user_123")
print(f"{result.usage.freeRemaining} free · {result.usage.packRemaining} pack")
print(f"charged from: {result.meta.source}")  # "free" | "pack" | "free+pack"
print(f"project: {result.meta.projectId} · account: {result.meta.issuedFor}")

Verifies the ML-DSA signature (algorithm read from the token itself), token expiry, and the revocation list. Never raises — always returns a VerifyResult. Cost: 1 token.

result = pq.verify(token)

if not result.valid:
    if result.failure == "rejected":
        # FIPSign checked the token and refuses it. result.error is one of these (text for your
        # logs: decide on result.failure, do not compare the text):
        #   "Token has been revoked"
        #   "Token expired N seconds ago"
        #   "Invalid signature — token was tampered with or not issued by this server"
        #   "Invalid signature — wrong length for ML-DSA-65 (expected 3309 bytes)"
        #   "Invalid token — signature is not valid base64"
        #   "Unsupported algorithm: X"
        #   "Token payload exceeds the maximum of 16384 characters"
        #   "This is a Mandate token. Verify it with POST /mandate/verify"
        raise PermissionError("Unauthorized")

    # FIPSign could not check the token (result.failure is "rate_limited", "quota_exhausted"
    # or "unavailable"). The token may be fine: do not sign the user out.
    # With "rate_limited", result.retry_after is the seconds to wait (None otherwise).
    raise RuntimeError(f"FIPSign could not check the token: {result.error}")

print(result.payload["sub"])   # "user_123"
print(result.payload["exp"])   # expiry timestamp (Unix)
print(result.payload["iat"])   # issued at timestamp (Unix)
# All custom fields passed to sign() are in payload too

Immediately and permanently invalidates a token. Future verify() calls will reject it even if the signature is valid and it hasn't expired. Cost: 1 token.

result = pq.revoke(token, "user logged out")

print(result.message)    # "Token revoked successfully"
print(result.revokedAt)  # Unix timestamp
print(result.sub)        # subject from the token payload
print(result.expiresAt)  # original expiry from the token
print(result.note)       # "This token will be rejected on any future /verify call"

pq.revoke(token, "order cancelled")
pq.revoke(token, "suspicious activity detected")

Reads Authorization: Bearer <token> and attaches the decoded payload to the request context. Returns 401 when the token is missing or FIPSign refuses it, and 503 when FIPSign could not check it.

from flask import Flask, g, request
from fipsign import PQAuth, flask_middleware
import base64, json
from fipsign.types import PQToken

app  = Flask(__name__)
pq   = PQAuth("pqa_your_api_key")
auth = flask_middleware(pq)

# Stand-in for your own user check. Replace it with your database lookup
# and a real password comparison (bcrypt, argon2…).
def authenticate(email, password):
    if email == "[email protected]" and password == "correct-horse":
        return {"id": "user_123", "email": email, "role": "admin"}
    return None

@app.route("/login", methods=["POST"])
def login():
    body = request.get_json(silent=True) or {}
    user = authenticate(body.get("email"), body.get("password"))
    if user is None:
        return {"error": "Invalid credentials"}, 401
    result = pq.sign(
        user["id"],
        email=user["email"],
        role=user["role"],
        expires_in_seconds=3600,
    )
    # Encode to base64 — this is what the client puts in Authorization: Bearer <encoded>
    encoded = base64.b64encode(json.dumps(result.token.to_dict()).encode()).decode()
    return {"token": encoded}

@app.route("/logout", methods=["POST"])
def logout():
    header = request.headers.get("Authorization", "")
    if header.startswith("Bearer "):
        try:
            token = PQToken.from_dict(json.loads(base64.b64decode(header[7:]).decode()))
            pq.revoke(token, "user logged out")
        except Exception:
            pass  # ignore malformed token
    return {"success": True}

@app.route("/api/profile")
@auth
def profile():
    return {"user": g.fipsign_user}

from fastapi import FastAPI, Depends
from fipsign import PQAuth, fastapi_middleware

app          = FastAPI()
pq           = PQAuth("pqa_your_api_key")
require_auth = fastapi_middleware(pq)

@app.get("/api/profile")
def profile(user=Depends(require_auth)):
    return {"sub": user["sub"], "role": user.get("role")}

All methods are identical to PQAuth but async. Use in FastAPI, aiohttp, or any asyncio-based application. Requires pip install fipsign-sdk[async].

import asyncio
import json
from fipsign.async_client import AsyncPQAuth
from fipsign import generate_key_pair
from fipsign.types import PQCert

async def main():
    async with AsyncPQAuth("pqa_your_api_key") as pq:
        signed = await pq.sign("user_123", role="admin", expires_in_seconds=3600)
        v      = await pq.verify(signed.token)
        print(v.valid, v.payload["sub"])

        # CA operations — network calls are async
        kp   = generate_key_pair()  # generate_key_pair() is synchronous
        cert = await pq.ca.issue(
            subject="device-serial-00123",
            public_key=kp.publicKey,
            expires_in_seconds=365 * 24 * 60 * 60,
        )
        crl = await pq.ca.get_crl()

        # verify_cert() and verify_x509_cert() are synchronous even in AsyncPQAuth
        # — they are pure in-memory operations with no I/O
        with open("root-cert.json") as f:  # the root certificate you saved when the CA was created
            root_cert = PQCert.from_dict(json.load(f))
        check = pq.ca.verify_cert(cert.certificate, root_cert)  # PQCert CA — no await
        # X.509 CA: pq.ca.verify_x509_cert(cert.certificate, root_pem), with the PEM saved at CA creation
        if not check.valid:
            raise PermissionError(check.error)

        if pq.ca.is_cert_revoked(cert.meta.certId, crl.crl):
            raise PermissionError("Device revoked")

asyncio.run(main())

Returns the current token balance, 6-month usage history, and purchased packs. No token cost.

u = pq.usage()

# Current balance
print(f"Month: {u.current.month}")
print(f"Free:  {u.current.freeRemaining} / {u.current.freeLimit}")
print(f"Used:  {u.current.freeUsed} this month")
print(f"Pack:  {u.current.packRemaining}")
print(f"Total: {u.current.totalRemaining}")
print(f"Account: {u.developer['email']}")

# 6-month history (always 6 entries, months with no activity show 0)
for entry in u.monthlyHistory:
    print(f"{entry.month}: {entry.tokensUsed} used ({entry.fromFree} free + {entry.fromPack} pack)")

# Purchased packs
from datetime import datetime
for pack in u.packs:
    date = datetime.fromtimestamp(pack.purchasedAt).strftime("%Y-%m-%d")
    print(f"{pack.packType}: {pack.tokensPurchased} tokens — {date}")
    print(f"  id: {pack.id} — paymentRef: {pack.paymentRef or 'n/a'}")

FIPSign fires webhook events automatically when you call sign(), verify(), or revoke(). The SDK triggers them — you do not call any method to enable them.

Use verify_webhook_signature() from fipsign.middleware to verify the HMAC-SHA256 signature on incoming webhook requests. Each POST from FIPSign includes X-PQAuth-Signature (sha256=...), X-PQAuth-Event, and X-PQAuth-Timestamp headers.

from fipsign.middleware import verify_webhook_signature

# Flask
@app.route("/webhooks/fipsign", methods=["POST"])
def webhook():
    from flask import request
    sig = request.headers.get("X-PQAuth-Signature", "")
    if not verify_webhook_signature(request.data, sig, FIPSIGN_WEBHOOK_SECRET):
        return "Invalid signature", 401
    event = request.json
    kind  = event["event"]
    if kind == "token.signed":
        pass
    elif kind == "token.rejected":
        pass
    elif kind == "token.revoked":
        pass
    elif kind == "limit.warning":
        pass
    elif kind == "limit.reached":
        pass
    return "ok", 200

# FastAPI
from fastapi import Request, HTTPException
@app.post("/webhooks/fipsign")
async def webhook(request: Request):
    body = await request.body()
    sig  = request.headers.get("X-PQAuth-Signature", "")
    if not verify_webhook_signature(body, sig, FIPSIGN_WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")
    event = await request.json()
    return "ok"

verify() never raises — it returns VerifyResult(valid=False, error="...", failure="...") on any failure (PY 03). All other methods raise PQAuthError.

from fipsign import PQAuth, PQAuthError

try:
    result = pq.sign("user_123")
except PQAuthError as err:
    if err.code == "INVALID_API_KEY":    # key missing or doesn't match pqa_ + 64 hex chars
        pass
    elif err.code == "API_ERROR":        # server returned an error (check err.status)
        if err.status == 429:
            # err.server_code is "rate_limited" (wait err.retry_after seconds)
            # or "token_quota_exhausted"
            pass
    elif err.code == "TIMEOUT":          # request exceeded timeout (default: 10s)
        pass
    elif err.code == "NETWORK_ERROR":    # connection failed
        pass
    elif err.code == "MISSING_SUB":      # sign() called without sub
        pass
    print(err.code, err.message, err.status)

import time
from fipsign import PQAuthError

def sign_with_retry(pq, sub):
    try:
        return pq.sign(sub)
    except PQAuthError as err:
        if err.server_code == "rate_limited":
            # retry_after: seconds until the one-minute window ends (from the Retry-After header)
            time.sleep(err.retry_after or 1)
            return pq.sign(sub)    # one retry; if it fails again, the error is raised
        raise    # "token_quota_exhausted" and every other error: waiting will not fix it

pq = PQAuth(
    api_key="pqa_...",                    # required — pqa_ + 64 lowercase hex chars
    base_url="https://api.fipsign.dev",   # optional, override for self-hosting
    timeout=10,                           # optional, seconds (default: 10)
    session=None,                         # optional, custom requests.Session
)

Issue post-quantum certificates for devices, services, or any entity that needs a tamper-proof identity. Built on ML-DSA-65 (NIST FIPS 204) — independent of the ML-DSA variant configured for token signing in each project.

from fipsign import generate_key_pair

kp = generate_key_pair()
# kp.publicKey — base64(1952 bytes raw public key) — pass to ca.issue()
# kp.secretKey — base64(32 bytes, seed form) — store securely on the device

from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA65PrivateKey
import base64

private_key = MLDSA65PrivateKey.from_seed_bytes(base64.b64decode(kp.secretKey))
signature   = private_key.sign(message)   # bytes — 3309 bytes for ML-DSA-65

# ── PQCert CA ──────────────────────────────────────────────────────────────
result = pq.ca.issue(
    subject="device-serial-00123",
    public_key=kp.publicKey,
    expires_in_seconds=365 * 24 * 60 * 60,  # required — whole number, min 60, max 157_680_000 (5 years)
    meta={"model": "lock-v2", "batch": "2026-05"},  # optional, max 10 keys
)
# result.certificate is a PQCert dataclass
print(result.certificate.id)         # cert_...
print(result.certificate.caId)       # ca_...
print(result.certificate.expiresAt)  # Unix timestamp
print(result.meta.certId)            # same as certificate.id
print(result.meta.format)            # "pqcert"
print(result.meta.caExpiry)          # None normally; CaExpiry(truncated=True, requestedExpiresInSeconds=N, resolvedExpiresInSeconds=N) if lifetime was truncated to fit CA root expiry

# ── X.509 CA ───────────────────────────────────────────────────────────────
# Note: publicKey must be exactly 1952 bytes (ML-DSA-65 public key).
# Note: meta is NOT supported for X.509 CAs — passing it returns API_ERROR 400.
result = pq.ca.issue(
    subject="device-serial-00123",
    public_key=kp.publicKey,
    expires_in_seconds=365 * 24 * 60 * 60,
)
# result.certificate is a PEM string
print(type(result.certificate))   # <class 'str'>
print(result.certificate[:27])    # "-----BEGIN CERTIFICATE-----"
print(result.meta.certId)         # cert_... — use this for revocation
print(result.meta.caId)           # ca_...
print(result.meta.expiresAt)      # Unix timestamp
print(result.meta.format)         # "x509"

import json
from fipsign.types import PQCert

with open("root-cert.json") as f:
    root_cert = PQCert.from_dict(json.load(f))

result = pq.ca.verify_cert(device_cert, root_cert)

if not result.valid:
    # Possible error messages:
    #   "Expected a CA_CERT certificate"
    #   "Expected a CA_ROOT certificate"
    #   "Certificate was not issued by this CA (caId mismatch)"
    #   "Root CA certificate has expired"
    #   "Certificate has expired"
    #   "Invalid certificate signature"
    raise PermissionError(result.error)

print(result.cert.subject)   # "device-serial-00123"
print(result.cert.expiresAt) # Unix timestamp

import os

root_pem = os.environ["FIPSIGN_ROOT_CERT_PEM"]  # PEM saved at CA creation

result = pq.ca.verify_x509_cert(cert_pem, root_pem)

if not result.valid:
    # Possible error messages:
    #   "Root CA certificate has expired"
    #   "Certificate has expired"
    #   "Invalid certificate signature — not signed by this root CA"
    #   "Unsupported signature algorithm: <OID>. Expected ML-DSA-65 (2.16.840.1.101.3.4.3.18)"
    #   "Unsupported root CA algorithm: <OID>. Expected ML-DSA-65 (2.16.840.1.101.3.4.3.18)"
    raise PermissionError(result.error)

print(result.cert[:27])  # "-----BEGIN CERTIFICATE-----"

crl_result = pq.ca.get_crl()

# PQCert CA — pass the PQCert dataclass
if pq.ca.is_cert_revoked(device_cert, crl_result.crl):
    raise PermissionError("Device certificate has been revoked")

# X.509 CA — pass the certId string from meta
if pq.ca.is_cert_revoked(result.meta.certId, crl_result.crl):
    raise PermissionError("Device certificate has been revoked")

# certId string also works for PQCert CAs
if pq.ca.is_cert_revoked(result.meta.certId, crl_result.crl):
    raise PermissionError("Device certificate has been revoked")

result = pq.ca.get_crl()

print(f"CA: {result.subject}")
print(f"CA ID: {result.caId}")
print(f"Generated: {result.generatedAt}")
print(f"Format: {result.format}")       # "pqcert" or "x509"
print(f"{len(result.crl)} revoked certificates")

from datetime import datetime
for entry in result.crl:
    # entry.reason may be None if no reason was provided at revocation time
    ts = datetime.fromtimestamp(entry.revokedAt).isoformat()
    print(f"{entry.certId} — {ts} — {entry.reason or 'no reason'}")

# X.509 CAs only: result.raw contains the full signed CRL with ML-DSA-65 signature
# result.raw is None for PQCert CAs
if result.raw:
    print(result.raw["signature"][:16] + "...")  # base64 ML-DSA signature

result = pq.ca.get_cert("cert_...")

print(result.status.revoked)    # bool
print(result.status.expired)    # bool
print(result.status.revokedAt)  # Unix timestamp or None
print(result.status.expiresAt)  # Unix timestamp

# For PQCert CAs, result.certificate is a PQCert dataclass
# For X.509 CAs, result.certificate is a PEM string and result.meta contains
# additional fields (None for PQCert CAs):
if result.meta:
    print(result.meta.certId)    # cert_...
    print(result.meta.caId)      # ca_...
    print(result.meta.subject)   # "device-serial-00123"
    print(result.meta.format)    # "x509"
    print(result.meta.algorithm) # "ML-DSA-44" | "ML-DSA-65" | "ML-DSA-87"

# PQCert CA — use certificate.id
result = pq.ca.revoke_cert(device_cert.id, "device decommissioned")

# X.509 CA — use meta.certId from ca.issue()
result = pq.ca.revoke_cert(meta.certId, "device reported stolen")

# certId string works for both formats
result = pq.ca.revoke_cert("cert_...", "device decommissioned")

print(result.certId)              # cert_...
print(result.revokedAt)           # Unix timestamp
print(result.reason)              # "device decommissioned" (or None if omitted)
print(result.usage.freeRemaining) # tokens remaining after this operation
# result.format == "x509" for X.509 CAs, None for PQCert CAs

import json
from fipsign import PQAuth, generate_key_pair
from fipsign.types import PQCert

pq = PQAuth("pqa_your_api_key")

# root_cert — the PQCert JSON saved once at CA creation, stored securely
with open("root-cert.json") as f:
    root_cert = PQCert.from_dict(json.load(f))

# 1. Factory: generate key pair for the device
kp = generate_key_pair()
# kp.secretKey — store securely on the device (32-byte seed, base64)

# 2. Factory: issue a certificate for the device
result      = pq.ca.issue(
    subject="lock-serial-00123",
    public_key=kp.publicKey,
    expires_in_seconds=365 * 24 * 60 * 60,
    meta={"model": "lock-v3", "batch": "2026-05"},
)
certificate = result.certificate  # PQCert dataclass — store on device

# 3. At runtime: offline signature verification (no API call)
result = pq.ca.verify_cert(certificate, root_cert)
if not result.valid:
    raise PermissionError(result.error)

# 4. At runtime: bulk revocation check (offline, from cached CRL)
crl_result = pq.ca.get_crl()
if pq.ca.is_cert_revoked(certificate, crl_result.crl):
    raise PermissionError("Device revoked")

# 5. Decommission: revoke the certificate
pq.ca.revoke_cert(certificate.id, "device decommissioned")

import os
from fipsign import PQAuth, generate_key_pair

pq = PQAuth("pqa_your_api_key")

# root_pem — the PEM string shown once at CA creation, stored securely
root_pem = os.environ["FIPSIGN_ROOT_CERT_PEM"]

# 1. Factory: generate key pair for the device
kp = generate_key_pair()
# kp.secretKey — store securely on the device (32-byte seed, base64)

# 2. Factory: issue a certificate for the device
result   = pq.ca.issue(
    subject="lock-serial-00123",
    public_key=kp.publicKey,
    expires_in_seconds=365 * 24 * 60 * 60,
)
cert_pem = result.certificate    # PEM string — store on device
cert_id  = result.meta.certId   # store alongside the PEM — needed for revocation

# 3. At runtime: offline signature verification (no API call)
result = pq.ca.verify_x509_cert(cert_pem, root_pem)
if not result.valid:
    raise PermissionError(result.error)

# 4. At runtime: bulk revocation check (offline, from cached CRL)
crl_result = pq.ca.get_crl()
if pq.ca.is_cert_revoked(cert_id, crl_result.crl):
    raise PermissionError("Device revoked")

# 5. Decommission: revoke the certificate using certId
pq.ca.revoke_cert(cert_id, "device decommissioned")

Hash sensitive data locally and sign only the hash — the original data never reaches the API. Convenience wrapper over sign()/verify(); see REST 03b for the full explanation of the pattern.

result = pq.zes.sign({
    "patient":   "Jane Doe",
    "diagnosis": "confidential",
    "record_id": "MR-2026-4491",
})
# result.hash — the 64-char SHA-256 hex digest that was actually signed
# result.token — pass to zes.verify() or revoke() like any token

check = pq.zes.verify(result.token, {
    "patient":   "Jane Doe",
    "diagnosis": "confidential",
    "record_id": "MR-2026-4491",
})
if not check.valid or not check.dataMatches:
    raise PermissionError("invalid or tampered")

Bounded, revocable authorization for AI agents, IoT devices, and automated services. Thin typed wrapper over POST/PATCH/GET /mandate — see Mandate 00 for the full explanation of the immutable/mutable layers, lifecycle, and budget semantics. No dashboard setup needed beyond an API key — unlike CA, there's no separate resource to create first. Identical on pq.mandate (sync) and the async client (see PY 06) — every method below has an await-able async twin with the same name and signature, except list_all(), which is an async generator (async for).

result = pq.mandate.emit(
    agent_id="agent-reporting-v2",
    issued_by="[email protected]",
    scope=["sign", "verify", "read:crm"],
    budget_total=1000,             # abstract units — 0 disables budget checking
    expires_in_seconds=28800,      # whole number, min 60, max 2_592_000 (30 days)
)
print(result.mandate.id)      # mdt_... — use for narrow/suspend/resume/revoke/get
print(result.mandate.status)  # "active"
mandate_token = result.mandate.token  # give this to the agent — not stored server-side, save it now

Optional: pass agent_public_key to require proof of possession — see Proof of possession with the SDK below. The result then carries requiresAgentSignature=True.

check = pq.mandate.verify(mandate_token, "send_reply", 1)  # (token, action, cost)
# Mandates with proof of possession take the agent's signature as a keyword argument — see below

if check.result != "granted":
    # check.reason: "scope_not_authorized" | "budget_exhausted" |
    #               "mandate_suspended" | "mandate_revoked" | "mandate_expired" |
    #               "invalid_signature" |
    #               "agent_signature_required" | "agent_signature_invalid" |
    #               "agent_signature_mismatch" | "agent_signature_replayed" (proof of possession, see below) |
    #               or the real backend error message (e.g. invalid API key, rate limit, token quota)
    raise PermissionError(check.reason)
# granted — check.budgetRemaining and check.expiresInSeconds are also present
do_the_action()

import json

from fipsign import generate_agent_key_pair

# On the agent, once. The default variant is ML-DSA-65.
kp = generate_agent_key_pair()
# Another variant: generate_agent_key_pair("ML-DSA-44")  # or "ML-DSA-87"

# kp.publicKey → goes to your backend, for mandate.emit(agent_public_key=...)
# kp.secretKey → stays on the agent, in a secret store. Never send it anywhere.
# kp.algorithm → "ML-DSA-65" here. Save it next to secretKey (Step 3 needs it)

# Save the two together on the agent (secret store, or a file only the agent's user can read).
# Step 3 reads them back.
saved = json.dumps({"secretKey": kp.secretKey, "algorithm": kp.algorithm})

result = pq.mandate.emit(
    agent_id="agent-reporting-v2",
    issued_by="[email protected]",
    scope=["sign", "send_reply"],
    budget_total=1000,
    expires_in_seconds=28800,
    agent_public_key=kp.publicKey,      # base64, from generate_agent_key_pair()
)
print(result.mandate.requiresAgentSignature)  # True
# Keep result.mandate.id in your database: you need it to narrow, suspend, revoke and inspect.
mandate_token = result.mandate.token  # give this to the agent

A key of the wrong size is rejected with HTTP 400 and nothing is charged, so a mandate that could never be verified cannot be created by mistake. Only the public key travels to your backend; it is stored once and can never change.

import json

from fipsign import sign_agent_call

# On the agent, for EVERY call: no API key needed, nothing is sent to FIPSign.
key = json.loads(saved)         # what Step 1 saved (read it from your secret store)
agent_signature = sign_agent_call(
    mandate_token,              # the mandate token (or just the mandate id)
    "send_reply",               # exactly what mandate.verify() will receive
    1,                          # exactly what mandate.verify() will receive
    key["secretKey"],           # the secretKey from Step 1
    algorithm=key["algorithm"], # required: saved in Step 1, never typed by hand
)
# Send agent_signature to whoever calls mandate.verify() — your executor, or the agent itself

check = pq.mandate.verify(mandate_token, "send_reply", 1, agent_signature=agent_signature)

if check.result != "granted":
    # check.reason also covers the agent's signature:
    # "agent_signature_required" | "agent_signature_invalid" |
    # "agent_signature_mismatch" | "agent_signature_replayed"
    raise PermissionError(check.reason)
do_the_action()

from fipsign import PQAuthError, sign_agent_call

try:
    agent_signature = sign_agent_call(mandate_token, "send_reply", 1, secret_key, algorithm="ML-DSA-65")
except PQAuthError as err:
    print(err.code, err.message)

Generates a key pair, emits a mandate that requires it and runs the four interesting cases against the live API. Save as pop_sdk_demo.py, run pip install fipsign-sdk, then FIPSIGN_API_KEY=pqa_... python pop_sdk_demo.py. Cost: 4 platform tokens — the emit (2) and the one granted verify (2); denied calls are free.

# pop_sdk_demo.py — proof of possession with the SDK, end to end.
# Setup: pip install fipsign-sdk
# Run:   FIPSIGN_API_KEY=pqa_... python pop_sdk_demo.py
import os
from fipsign import PQAuth, generate_agent_key_pair, sign_agent_call

pq = PQAuth(os.environ["FIPSIGN_API_KEY"])

# ── AGENT SIDE ──────────────────────────────────────────────────────────
# The agent creates its own key pair. The secret key never leaves the agent.
kp = generate_agent_key_pair()  # ML-DSA-65 unless you pass another variant

# ── YOUR BACKEND ────────────────────────────────────────────────────────
# 1. Emit the mandate, registering the agent's PUBLIC key.
mandate = pq.mandate.emit(
    agent_id="agent-pop-demo",
    issued_by="[email protected]",
    scope=["sign"],
    budget_total=10,
    expires_in_seconds=3600,
    agent_public_key=kp.publicKey,
).mandate
print("emitted", mandate.id, "· requiresAgentSignature:", mandate.requiresAgentSignature)

# 2. Without agent_signature the mandate token alone is useless.
r = pq.mandate.verify(mandate.token, "sign", 1)
print("no signature   →", r.result, r.reason)

# 3. With the agent's signature over THIS call: granted.
signature = sign_agent_call(mandate.token, "sign", 1, kp.secretKey, algorithm=kp.algorithm)
r = pq.mandate.verify(mandate.token, "sign", 1, agent_signature=signature)
print("with signature →", r.result, "· budgetRemaining:", r.budgetRemaining)

# 4. Sending the same signature again is refused: each signature works once.
r = pq.mandate.verify(mandate.token, "sign", 1, agent_signature=signature)
print("same signature →", r.result, r.reason)

# 5. A signature made for cost 1 cannot be used for cost 9.
other = sign_agent_call(mandate.token, "sign", 1, kp.secretKey, algorithm=kp.algorithm)
r = pq.mandate.verify(mandate.token, "sign", 9, agent_signature=other)
print("cost changed   →", r.result, r.reason)

# Clean up: revoke the demo mandate (free).
pq.mandate.revoke(mandate.id)

emitted mdt_… · requiresAgentSignature: True
no signature   → denied agent_signature_required
with signature → granted · budgetRemaining: 9
same signature → denied agent_signature_replayed
cost changed   → denied agent_signature_mismatch

pq.mandate.narrow(mandate.id, ["read:crm"])  # shrink scope — monotonic, cannot re-widen
pq.mandate.suspend(mandate.id)              # pause — verify() denies with "mandate_suspended" while suspended
pq.mandate.resume(mandate.id)               # reactivate a suspended mandate
pq.mandate.revoke(mandate.id)               # permanent — irreversible, no narrow/suspend/resume after this

patched = pq.mandate.suspend(mandate.id)
print(patched.status, patched.scope, patched.updatedAt)
# suspended ['sign', 'verify', 'read:crm'] 1785691318

result = pq.mandate.get("mdt_...")
print(result.mandate.budgetConsumed, result.mandate.budgetRemaining, result.mandate.scopeCurrent, result.mandate.status)

# First page: the 50 most recent mandates of this project
page = pq.mandate.list()
print(page.count, page.nextCursor)        # MandateListResult(mandates, count, nextCursor)

# Your own page size (1–100), then the next page
page1 = pq.mandate.list(limit=20)
page2 = pq.mandate.list(limit=20, cursor=page1.nextCursor) if page1.nextCursor else None

# Every mandate, page by page — stop whenever you want with break
for m in pq.mandate.list_all():
    print(m.id, m.status, m.budgetConsumed)

# Async client: same names, list_all() is an async generator (no await before it)
# async for m in pq.mandate.list_all(): ...

Both MCP servers expose the same 11 tools covering the full FIPSign runtime API. Install one — they're equivalent.

Edit claude_desktop_config.json and restart Claude Desktop. The API key is passed via environment variable — never hardcode it.

{
  "mcpServers": {
    "fipsign": {
      "command": "npx",
      "args": ["-y", "@fipsign/mcp"],
      "env": {
        "FIPSIGN_API_KEY": "pqa_your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "fipsign": {
      "command": "uvx",
      "args": ["fipsign-mcp"],
      "env": {
        "FIPSIGN_API_KEY": "pqa_your_api_key_here"
      }
    }
  }
}

Add FIPSign to Claude Code with a single command. The server runs per-project or globally.

claude mcp add fipsign -- env FIPSIGN_API_KEY=pqa_your_api_key npx -y @fipsign/mcp

claude mcp add fipsign -- env FIPSIGN_API_KEY=pqa_your_api_key uvx fipsign-mcp

claude mcp list
claude mcp get fipsign

Once connected, Claude can call FIPSign tools directly in response to natural language.

Both MCP servers are open source. Use MCP Inspector for interactive testing before connecting to a client.

# Install inspector globally once
npm install -g @modelcontextprotocol/inspector

# Run inspector against the published package
FIPSIGN_API_KEY=pqa_your_api_key npx @modelcontextprotocol/inspector npx @fipsign/mcp

# Or from a local clone
git clone https://github.com/fipsign/fipsign-mcp
cd fipsign-mcp && npm install && npm run build
FIPSIGN_API_KEY=pqa_your_api_key npx @modelcontextprotocol/inspector node dist/index.js

# Using uvx — no install needed
FIPSIGN_API_KEY=pqa_your_api_key npx @modelcontextprotocol/inspector uvx fipsign-mcp

# Or from a local clone
git clone https://github.com/fipsign/fipsign-mcp-python
cd fipsign-mcp-python && pip install -e .
FIPSIGN_API_KEY=pqa_your_api_key npx @modelcontextprotocol/inspector python -m fipsign_mcp.server

Set these in your terminal before running any example in this section.

export API_KEY="pqa_YOUR_API_KEY_HERE"
export BASE_URL="https://api.fipsign.dev"

Public endpoint. No authentication required. No token cost.

curl -s $BASE_URL/health | jq

Requires X-API-Key. No token cost. Rate limited to 300 requests per minute per API key. Returns the project's ML-DSA public key for offline token verification. The algorithm reflects the project's configured algorithm (ML-DSA-44, ML-DSA-65, or ML-DSA-87).

curl -s $BASE_URL/public-key   -H "X-API-Key: $API_KEY" | jq

Requires X-API-Key. Cost: 1 token.

curl -s -X POST $BASE_URL/sign \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"sub":"user_123","email":"[email protected]","role":"admin","expiresInSeconds":3600}' | jq

TOKEN=$(curl -s -X POST $BASE_URL/sign \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"sub":"user_test","email":"[email protected]"}' \
  | jq -c '.token')

Sign sensitive data without sending it to the API. The data is hashed locally — only a 64-character SHA-256 hex digest (32 bytes) is transmitted. PQ-Sign never sees the original content. Compatible with HIPAA, PCI-DSS, and any environment where plaintext must not leave your infrastructure. Cost: 1 token.

# Your sensitive data — never leaves your machine
SENSITIVE='{"amount":"50000","customer":"Acme Corp","invoice":"INV-123"}'
# Keys must be sorted alphabetically: amount → customer → invoice

# Hash locally with SHA-256 → hex
ZES_HASH=$(echo -n "$SENSITIVE" | sha256sum | awk '{print $1}')
echo "Hash: $ZES_HASH"
# Hash: a3f2c1d8e9b4f7c2... (64 hex chars — this is what travels to the API)

ZES_TOKEN=$(curl -s -X POST $BASE_URL/sign   -H "Content-Type: application/json"   -H "X-API-Key: $API_KEY"   -d "{\"sub\": \"zes:$ZES_HASH\", \"zes\": true}"   | jq -c '.token')
echo $ZES_TOKEN | jq

# Recalculate the hash from the original data (on your side)
VERIFY_HASH=$(echo -n "$SENSITIVE" | sha256sum | awk '{print $1}')

# Verify the token — same endpoint as always
curl -s -X POST $BASE_URL/verify   -H "Content-Type: application/json"   -H "X-API-Key: $API_KEY"   -d "{\"token\": $ZES_TOKEN}" | jq

import crypto from 'crypto'

// Step 1 — hash locally (keys sorted recursively — nested objects too)
function canonicalize(obj) {
  if (Array.isArray(obj)) return obj.map(canonicalize)
  if (obj !== null && typeof obj === 'object') {
    return Object.fromEntries(Object.keys(obj).sort().map(k => [k, canonicalize(obj[k])]))
  }
  return obj
}
const sensitive = { amount: '50000', customer: 'Acme Corp', invoice: 'INV-123' }
const sorted    = JSON.stringify(canonicalize(sensitive))
const hash      = crypto.createHash('sha256').update(sorted).digest('hex')

// Step 2 — sign the hash
const res   = await fetch('https://api.fipsign.dev/sign', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': process.env.PQSIGN_KEY },
  body:    JSON.stringify({ sub: `zes:${hash}`, zes: true })
})
const { token } = await res.json()

// Step 3 — verify: recalculate hash and confirm it matches payload.sub
const verifyRes = await fetch('https://api.fipsign.dev/verify', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': process.env.PQSIGN_KEY },
  body:    JSON.stringify({ token })
})
const { valid, payload } = await verifyRes.json()

const rehash  = crypto.createHash('sha256').update(sorted).digest('hex')
const matches = payload.sub === `zes:${rehash}`
console.log(`valid: ${valid}, data matches token: ${matches}`)  // true, true

import hashlib, json, requests, os

# Step 1 — hash locally (keys sorted recursively — nested objects too)
def canonicalize(obj):
    if isinstance(obj, list):
        return [canonicalize(x) for x in obj]
    if isinstance(obj, dict):
        return {k: canonicalize(obj[k]) for k in sorted(obj)}
    return obj

sensitive = {'amount': '50000', 'customer': 'Acme Corp', 'invoice': 'INV-123'}
sorted_json = json.dumps(canonicalize(sensitive), separators=(',', ':'))
zes_hash    = hashlib.sha256(sorted_json.encode()).hexdigest()

headers = {'Content-Type': 'application/json', 'X-API-Key': os.environ['PQSIGN_KEY']}

# Step 2 — sign the hash
r     = requests.post('https://api.fipsign.dev/sign',
          json={'sub': f'zes:{zes_hash}', 'zes': True}, headers=headers)
token = r.json()['token']

# Step 3 — verify
v       = requests.post('https://api.fipsign.dev/verify',
            json={'token': token}, headers=headers).json()
rehash  = hashlib.sha256(sorted_json.encode()).hexdigest()
matches = v['payload']['sub'] == f'zes:{rehash}'
print(f'valid: {v["valid"]}, data matches token: {matches}')  # True, True

Requires X-API-Key. Cost: 1 token. Verifies signature, expiry, and revocation status.

curl -s -X POST $BASE_URL/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $TOKEN}" | jq

FAKE_TOKEN=$(echo $TOKEN | jq -c '.payload = "TAMPERED_PAYLOAD"')
curl -s -X POST $BASE_URL/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $FAKE_TOKEN}" | jq

Requires X-API-Key. Cost: 1 token. Permanently and immediately invalidates the token.

curl -s -X POST $BASE_URL/revoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $TOKEN, \"reason\": \"user logged out\"}" | jq

Requires X-API-Key or a session cookie. No token cost. Returns balance, 6-month history, purchased packs, and account info.

curl -s $BASE_URL/usage \
  -H "X-API-Key: $API_KEY" | jq

Copy, replace your API key, and run to test the full token lifecycle.

#!/bin/bash
API_KEY="pqa_YOUR_API_KEY"
BASE_URL="https://api.fipsign.dev"

echo "[1/7] Health..."
curl -s $BASE_URL/health | jq .status

echo "[2/7] Sign..."
TOKEN=$(curl -s -X POST $BASE_URL/sign \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d '{"sub":"user_test","role":"user"}' | jq -c '.token')

echo "[3/7] Verify (must be true)..."
curl -s -X POST $BASE_URL/verify -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" -d "{\"token\": $TOKEN}" | jq .valid

echo "[4/7] Tampered (must be false)..."
FAKE=$(echo $TOKEN | jq -c '.payload = "FAKE"')
curl -s -X POST $BASE_URL/verify -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" -d "{\"token\": $FAKE}" | jq .valid

echo "[5/7] Revoke..."
curl -s -X POST $BASE_URL/revoke -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" -d "{\"token\": $TOKEN, \"reason\": \"test\"}" | jq .message

echo "[6/7] Verify revoked (must be false)..."
curl -s -X POST $BASE_URL/verify -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" -d "{\"token\": $TOKEN}" | jq '{valid,error}'

echo "[7/7] Balance..."
curl -s $BASE_URL/usage -H "X-API-Key: $API_KEY" | jq .current

All endpoints are rate limited. 300 requests/minute per API key on write endpoints, 60/minute on CA read endpoints. HTTP 429 on excess, with a Retry-After header.

HTTP/2 429
retry-after: 37

{
  "success": false,
  "error": "Rate limit exceeded. Maximum 300 requests per minute per API key.",
  "code": "rate_limited"
}

HTTP/2 429

{
  "success": false,
  "error": "Token limit reached. Free monthly tokens exhausted and no active packs.",
  "code": "token_quota_exhausted",
  "usage": {
    "freeRemaining": 0,
    "packRemaining": 0,
    "totalRemaining": 0
  }
}

// retry.mjs — Node.js 20+, no SDK. Run it with:  FIPSIGN_API_KEY=pqa_... node retry.mjs
const BASE_URL = 'https://api.fipsign.dev'
const API_KEY  = process.env.FIPSIGN_API_KEY

async function fipsign(path, body, retries = 1) {
  const res = await fetch(BASE_URL + path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
    body: JSON.stringify(body),
  })
  if (res.status !== 429) return res

  const err = await res.json()
  if (err.code === 'rate_limited' && retries > 0) {
    // Retry-After = seconds until the one-minute window ends
    const seconds = Number(res.headers.get('Retry-After') ?? 1)
    await new Promise(resolve => setTimeout(resolve, seconds * 1000))
    return fipsign(path, body, retries - 1)
  }
  // 'token_quota_exhausted' (or still rate limited after the retry): waiting will not fix it now
  throw new Error(`FIPSign answered 429 ${err.code}: ${err.error}`)
}

const res = await fipsign('/sign', { sub: 'user_123' })
console.log(res.status, await res.json())

All CA runtime operations are available via REST. The CA root is created once from the dashboard — there is no REST endpoint for that. All endpoints require X-API-Key. The API key determines the project; no projectId needed in the request body.

CERT=$(curl -s -X POST $BASE_URL/ca/issue \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "subject":          "device-serial-00123",
    "publicKey":        "base64_ml_dsa65_public_key",
    "expiresInSeconds": 31536000,
    "meta":             {"model": "lock-v2", "batch": "2026-05"}
  }')

CERT_ID=$(echo $CERT | jq -r '.meta.certId')
echo "Issued: $CERT_ID"

curl -s $BASE_URL/ca/crl -H "X-API-Key: $API_KEY" | jq '.'

curl -s $BASE_URL/ca/certificate/$CERT_ID \
  -H "X-API-Key: $API_KEY" | jq '.status'

curl -s -X POST $BASE_URL/ca/revoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"certId\": \"$CERT_ID\", \"reason\": \"device decommissioned\"}" | jq

X.509 CA works identically to PQCert CA from the API perspective — same endpoints, same auth model. The difference is the format: X.509 returns a standard PEM certificate (RFC 9881, id-ml-dsa-65) that OpenSSL 3.5+ can parse.

node -e "
import('@noble/post-quantum/ml-dsa.js').then(({ml_dsa65}) => {
  const seed = new Uint8Array(32);
  crypto.getRandomValues(seed);
  const kp = ml_dsa65.keygen(seed);
  let pub = '', sec = '';
  for(let i=0;i<kp.publicKey.length;i++) pub += String.fromCharCode(kp.publicKey[i]);
  for(let i=0;i<kp.secretKey.length;i++) sec += String.fromCharCode(kp.secretKey[i]);
  console.log('PUBLIC_KEY=' + btoa(pub));
  console.log('SECRET_KEY=' + btoa(sec));
})"

# publicKey must be exactly 1952 bytes (ML-DSA-65 public key)
# meta is not supported for X.509 CAs — omit it
CERT_PEM=$(curl -s -X POST $BASE_URL/ca/issue \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{
    \"subject\":          \"device-serial-00123\",
    \"publicKey\":        \"$DEVICE_PUBLIC_KEY\",
    \"expiresInSeconds\": 31536000
  }")

CERT_ID=$(echo $CERT_PEM | jq -r '.meta.certId')
echo $CERT_PEM | jq -r '.certificate'  # prints PEM

A complete example: issue a certificate, sign a device message, and verify it on the server including cert chain validation, expiry check, and replay protection.

# Set DEVICE_PUBLIC_KEY and DEVICE_SECRET_KEY from REST 11b above

# Already covered in REST 11b — CERT_PEM and CERT_ID set

node -e "
import('@noble/post-quantum/ml-dsa.js').then(({ml_dsa65}) => {
  const message    = JSON.stringify({ deviceId: 'device-serial-00123', timestamp: Date.now(), value: 42.5 });
  const secretKeyB64 = process.env.DEVICE_SECRET_KEY;
  const bin = atob(secretKeyB64);
  const secretKey = new Uint8Array(bin.length);
  for(let i = 0; i < bin.length; i++) secretKey[i] = bin.charCodeAt(i);
  const msgBytes  = new TextEncoder().encode(message);
  const signature = ml_dsa65.sign(msgBytes, secretKey);
  let sigStr = '';
  for(let i = 0; i < signature.length; i++) sigStr += String.fromCharCode(signature[i]);
  console.log(JSON.stringify({ message, signature: btoa(sigStr), certificate: process.env.DEVICE_CERT_PEM }));
})"

Verify the certificate chain using the JS SDK's pq.ca.verifyX509Cert(certPem, rootPem) or Python's pq.ca.verify_x509_cert(cert_pem, root_pem) (requires cryptography>=48.0.0). Then verify the message signature with ml_dsa65.verify().

Requires dashboard session (cookie auth). No token cost. Rotates the ML-DSA keypair for a specific project. The previous key remains valid for as long as a token signed with it could still be alive — currently up to 5 years, matching /sign's maximum expiresInSeconds — so tokens signed before rotation continue to verify successfully throughout that window.

curl -s -X POST $BASE_URL/projects/proj_YOUR_PROJECT_ID/rotate-keys   -H "Content-Type: application/json"   -b "__Host-pq_session=YOUR_SESSION_COOKIE" | jq

FIPSign sends HTTP POST requests to your endpoint when events occur. Webhook configuration is dashboard-only — it requires a user session and is not available via API key.

import crypto from 'crypto'

app.post('/webhooks/fipsign', express.json(), (req, res) => {
  const sig      = req.headers['x-pqauth-signature']
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.FIPSIGN_WEBHOOK_SECRET)
    .update(JSON.stringify(req.body)).digest('hex')
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return res.status(401).send('Invalid signature')

  const { event, data } = req.body
  // handle event...
  res.status(200).send('ok')
})

Mandate is a PQ-Sign feature — not a separate product. It uses the same ML-DSA signing infrastructure as /sign, extended with a real-time mutable state layer that gives you per-agent control.

Read this before you write code. It answers the questions that come up in almost every integration: which credential lives where, who should call verify, what cost really means, and what the scope and budget rules are. Everything here follows the behavior of the API.

your backend / executor              FIPSign                         the agent
────────────────────────             ───────                         ─────────
1. POST /mandate  ─────────────────► signs, registers state
                  ◄───────────────── { id, token }
2. keep the id, hand the token over ──────────────────────────────►  holds the token
                                                                       │ "please do X"
3. ◄───────────────────────────────────────────────────────────────────┘
   work out the real cost of X
   POST /mandate/verify
     { token, action: "X", cost }  ─► checks signature, status, expiry,
                                       scope, budget — atomically
                                    ◄─ granted / denied
4. only if granted: perform X

Issues a signed mandate for an agent or device. Signs the payload with ML-DSA (using the project's configured algorithm) and registers the mutable state server-side. The token is returned to you and not stored on the server — store it securely and pass it to the agent. Cost: 2 tokens.

curl -s -X POST https://api.fipsign.dev/mandate \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId":          "agent-reporting-v2",
    "issuedBy":         "[email protected]",
    "scope":            ["sign", "verify", "read:crm"],
    "budgetTotal":      1000,
    "expiresInSeconds": 28800
  }'

MANDATE=$(curl -s -X POST https://api.fipsign.dev/mandate \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"agent-test","issuedBy":"[email protected]","scope":["sign","verify"],"budgetTotal":100,"expiresInSeconds":3600}')

MANDATE_ID=$(echo $MANDATE | jq -r '.mandate.id')
MANDATE_TOKEN=$(echo $MANDATE | jq -c '.mandate.token')

The agent calls this before executing any authorized action. Verification runs in two phases: first the ML-DSA signature (cryptographic integrity), then the live mutable state (current scope, budget, status). Only if both pass is the action granted. Cost: 2 tokens — only charged on granted responses; denied calls are free.

curl -s -X POST https://api.fipsign.dev/mandate/verify \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"token\": $MANDATE_TOKEN, \"action\": \"sign\", \"cost\": 5}"

Turn a mandate from a bearer token into one that only a specific agent can use. This section is the full recipe: the exact signing contract, copy-paste code for Node.js and Python, and what every error means.

Any FIPS 204 ML-DSA library works, and any of the three variants: the project's algorithm does not matter, and the agent's key is unrelated to the CA. The examples use ML-DSA-44 (smallest and fastest). Whichever variant you pick, you will write its name in the algorithm field of every signature (Step 3). This table is the complete list: the text in the second column is what you type, character for character.

// npm install @noble/post-quantum        (Node 20+)
import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js'
import { randomBytes } from 'node:crypto'

// The 32-byte seed IS the private key. It is the only secret you keep.
const seed = randomBytes(32)
// ml_dsa44 is the "ML-DSA-44" row of the table above
const { publicKey } = ml_dsa44.keygen(seed)

// Goes into "agentPublicKey" when you emit the mandate
const agentPublicKey = Buffer.from(publicKey).toString('base64')

// Save this on the agent side (secret store, or a file only the agent can read), never share it.
// Step 3 uses it under the same name: storedSeed
const storedSeed = Buffer.from(seed).toString('base64')

# pip install "cryptography>=48.0.0"
import base64
from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA44PrivateKey

# MLDSA44PrivateKey is the "ML-DSA-44" row of the table above
agent_key = MLDSA44PrivateKey.generate()
# The 32-byte seed IS the private key. It is the only secret you keep.
seed = agent_key.private_bytes_raw()

# Goes into "agentPublicKey" when you emit the mandate
public_raw = agent_key.public_key().public_bytes_raw()
agent_public_key = base64.b64encode(public_raw).decode()

# Save this on the agent side (secret store, or a file only the agent can read), never share it.
# Step 3 uses it under the same name: stored_seed
stored_seed = base64.b64encode(seed).decode()

curl -s -X POST https://api.fipsign.dev/mandate \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agentId\":\"agent-42\",\"issuedBy\":\"[email protected]\",\"scope\":[\"sign\"],\"budgetTotal\":100,\"expiresInSeconds\":3600,\"agentPublicKey\":\"$AGENT_PUBLIC_KEY\"}"

The response is the usual one, plus "requiresAgentSignature": true. A wrong-sized key is rejected with 400 at this point — nothing is charged — so a mandate that could never be verified cannot be created by mistake.

The signature is a token with the same shape as any FIPSign token: payload (base64 of a JSON), signature, algorithm. This is the whole contract:

import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js'

// Exactly this text, in every signature. Same row of the table as ml_dsa44 (Step 1).
const ALGORITHM = 'ML-DSA-44'

// storedSeed: the base64 seed that Step 1 saved
function signCall(storedSeed, mandateId, action, cost) {
  // Re-derive the signing key from the seed
  const { secretKey } = ml_dsa44.keygen(Buffer.from(storedSeed, 'base64'))
  const now = Math.floor(Date.now() / 1000)
  const payload = { sub: mandateId, action, cost, iat: now, exp: now + 30 }
  const payloadB64 = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64')
  // Sign the base64 TEXT (UTF-8 bytes), not the JSON
  const message = new TextEncoder().encode(payloadB64)
  const signature = ml_dsa44.sign(message, secretKey)
  return {
    payload:   payloadB64,
    signature: Buffer.from(signature).toString('base64'),
    algorithm: ALGORITHM,    // exactly the text from the table in Step 1
    issuedAt:  now,           // optional
  }
}

import base64
import json
import time

from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA44PrivateKey

# Exactly this text, in every signature. Same row of the table as MLDSA44PrivateKey (Step 1).
ALGORITHM = "ML-DSA-44"


def sign_call(stored_seed: str, mandate_id: str, action: str, cost: int) -> dict:
    # stored_seed: the base64 seed that Step 1 saved. Re-derive the signing key from it.
    agent_key = MLDSA44PrivateKey.from_seed_bytes(base64.b64decode(stored_seed))
    now = int(time.time())
    payload = {
        "sub": mandate_id, "action": action, "cost": cost,
        "iat": now, "exp": now + 30,
    }
    payload_b64 = base64.b64encode(json.dumps(payload).encode("utf-8")).decode()
    # Sign the base64 TEXT, not the JSON
    signature = agent_key.sign(payload_b64.encode("ascii"))
    return {
        "payload": payload_b64,
        "signature": base64.b64encode(signature).decode(),
        "algorithm": ALGORITHM,    # exactly the text from the table in Step 1
        "issuedAt": now,            # optional
    }

{
  "token":  { "payload": "eyJ...", "signature": "...", "algorithm": "ML-DSA-65", "issuedAt": 1785690939 },
  "action": "sign",
  "cost":   1,
  "agentSignature": {
    "payload":   "eyJzdWIiOiJtZHRfLi4uIn0=",
    "signature": "k3Jd8...",
    "algorithm": "ML-DSA-44",
    "issuedAt":  1785690940
  }
}

token is the mandate token exactly as returned by POST /mandate (an object, not a string) and agentSignature is the object built in step 3. Send it to POST /mandate/verify as in section 02.

Two algorithm fields, two different things. token.algorithm belongs to the mandate token: send the token exactly as POST /mandate returned it and never edit it (it is the variant of your project; "ML-DSA-65" in the example). agentSignature.algorithm is the one you write in Step 3: the variant of the agent's key ("ML-DSA-44" in the example). They may differ, and that is fine.

Emits a mandate for a fresh keypair and then runs the four interesting cases against the live API. Save as pop-demo.mjs, run npm install @noble/post-quantum, then FIPSIGN_API_KEY=pqa_... node pop-demo.mjs (Node 20+).

// pop-demo.mjs — proof of possession, end to end.
// Setup: npm install @noble/post-quantum        (Node 20+)
// Run:   FIPSIGN_API_KEY=pqa_... node pop-demo.mjs
import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js'
import { randomBytes } from 'node:crypto'

const API = 'https://api.fipsign.dev'
const b64 = (bytes) => Buffer.from(bytes).toString('base64')

// A denied verify is HTTP 403 with a JSON body:
// return status + body instead of throwing.
async function call(method, path, body) {
  const res = await fetch(API + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.FIPSIGN_API_KEY,
    },
    body: body && JSON.stringify(body),
  })
  return { status: res.status, data: await res.json() }
}

// ── AGENT SIDE ──────────────────────────────────────────────────────────
// The agent creates its own keypair. The seed is the private key: keep it secret
// (in real life, store b64(seed) in a secret store).
const seed = randomBytes(32)
const { publicKey, secretKey } = ml_dsa44.keygen(seed)

// Sign ONE call: this mandate + this action + this cost. Valid 30 s, usable once.
function signCall(mandateId, action, cost) {
  const now = Math.floor(Date.now() / 1000)
  const payload = { sub: mandateId, action, cost, iat: now, exp: now + 30 }
  const payloadB64 = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64')
  // Sign the base64 TEXT (UTF-8 bytes), not the JSON
  const message = new TextEncoder().encode(payloadB64)
  const signature = ml_dsa44.sign(message, secretKey)
  return {
    payload: payloadB64,
    signature: b64(signature),
    algorithm: 'ML-DSA-44',   // exactly this text; it pairs with ml_dsa44
    issuedAt: now,
  }
}

// ── YOUR BACKEND ────────────────────────────────────────────────────────
// 1. Emit the mandate, registering the agent's PUBLIC key.
const emitted = await call('POST', '/mandate', {
  agentId: 'agent-pop-demo',
  issuedBy: '[email protected]',
  scope: ['sign'],
  budgetTotal: 10,
  expiresInSeconds: 3600,
  agentPublicKey: b64(publicKey),
})
if (!emitted.data.success) {
  throw new Error('emit failed: ' + JSON.stringify(emitted.data))
}
const { id, token, requiresAgentSignature } = emitted.data.mandate
console.log('emitted', id, '· requiresAgentSignature:', requiresAgentSignature)

// 2. Without agentSignature the mandate token alone is useless.
let r = await call('POST', '/mandate/verify', { token, action: 'sign', cost: 1 })
console.log('no signature      →', r.status, r.data.result, r.data.reason)

// 3. With the agent's signature over THIS call: granted.
const agentSignature = signCall(id, 'sign', 1)
const body = { token, action: 'sign', cost: 1, agentSignature }
r = await call('POST', '/mandate/verify', body)
console.log('with signature    →', r.status, r.data.result,
  '· budgetRemaining:', r.data.budgetRemaining)

// 4. Sending the same signature again is refused: each signature works once.
r = await call('POST', '/mandate/verify', body)
console.log('same signature    →', r.status, r.data.result, r.data.reason)

// 5. A signature made for cost 1 cannot be used for cost 9.
const bad = { token, action: 'sign', cost: 9, agentSignature: signCall(id, 'sign', 1) }
r = await call('POST', '/mandate/verify', bad)
console.log('cost changed      →', r.status, r.data.result, r.data.reason)

The same flow. Save as pop_demo.py, run pip install "cryptography>=48.0.0" requests, then FIPSIGN_API_KEY=pqa_... python pop_demo.py.

# pop_demo.py — proof of possession, end to end.
# Setup: pip install "cryptography>=48.0.0" requests
# Run:   FIPSIGN_API_KEY=pqa_... python pop_demo.py
import base64
import json
import os
import time

import requests
from cryptography.hazmat.primitives.asymmetric.mldsa import MLDSA44PrivateKey

API = "https://api.fipsign.dev"
HEADERS = {"X-API-Key": os.environ["FIPSIGN_API_KEY"]}


def b64(data: bytes) -> str:
    return base64.b64encode(data).decode()


def call(method, path, body=None):
    # A denied verify is HTTP 403 with a JSON body:
    # return status + body instead of raising.
    r = requests.request(method, API + path, headers=HEADERS, json=body, timeout=30)
    return r.status_code, r.json()


# ── AGENT SIDE ──────────────────────────────────────────────────────────
# The agent creates its own keypair. The seed is the private key: keep it secret
# (in real life, store b64(agent_key.private_bytes_raw()) in a secret store).
agent_key = MLDSA44PrivateKey.generate()
agent_public_key = b64(agent_key.public_key().public_bytes_raw())


def sign_call(mandate_id: str, action: str, cost: int) -> dict:
    """Sign ONE call: mandate + action + cost. Valid 30 s, usable once."""
    now = int(time.time())
    payload = {
        "sub": mandate_id, "action": action, "cost": cost,
        "iat": now, "exp": now + 30,
    }
    payload_b64 = b64(json.dumps(payload).encode("utf-8"))
    # Sign the base64 TEXT, not the JSON
    signature = agent_key.sign(payload_b64.encode("ascii"))
    return {
        "payload": payload_b64,
        "signature": b64(signature),
        "algorithm": "ML-DSA-44",   # exactly this text; it pairs with MLDSA44PrivateKey
        "issuedAt": now,
    }


# ── YOUR BACKEND ────────────────────────────────────────────────────────
# 1. Emit the mandate, registering the agent's PUBLIC key.
status, data = call("POST", "/mandate", {
    "agentId": "agent-pop-demo",
    "issuedBy": "[email protected]",
    "scope": ["sign"],
    "budgetTotal": 10,
    "expiresInSeconds": 3600,
    "agentPublicKey": agent_public_key,
})
if not data.get("success"):
    raise SystemExit(f"emit failed: {data}")
mandate = data["mandate"]
mandate_id, token = mandate["id"], mandate["token"]
print("emitted", mandate_id, "· requiresAgentSignature:",
      mandate["requiresAgentSignature"])

# 2. Without agentSignature the mandate token alone is useless.
body = {"token": token, "action": "sign", "cost": 1}
status, r = call("POST", "/mandate/verify", body)
print("no signature      →", status, r["result"], r.get("reason"))

# 3. With the agent's signature over THIS call: granted.
body["agentSignature"] = sign_call(mandate_id, "sign", 1)
status, r = call("POST", "/mandate/verify", body)
print("with signature    →", status, r["result"],
      "· budgetRemaining:", r.get("budgetRemaining"))

# 4. Sending the same signature again is refused: each signature works once.
status, r = call("POST", "/mandate/verify", body)
print("same signature    →", status, r["result"], r.get("reason"))

# 5. A signature made for cost 1 cannot be used for cost 9.
body = {"token": token, "action": "sign", "cost": 9,
        "agentSignature": sign_call(mandate_id, "sign", 1)}
status, r = call("POST", "/mandate/verify", body)
print("cost changed      →", status, r["result"], r.get("reason"))

emitted mdt_… · requiresAgentSignature: true
no signature      → 403 denied agent_signature_required
with signature    → 200 granted · budgetRemaining: 9
same signature    → 403 denied agent_signature_replayed
cost changed      → 403 denied agent_signature_mismatch

What to do with every answer verify can give, how to retry safely, and the mistakes that cost integrators the most time.

// ok: true only when FIPSign explicitly granted the action.
// Anything else means "do not act".
async function authorize({ token, action, cost, agentSignature }) {
  const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.FIPSIGN_API_KEY,
  }
  const body = { token, action, cost, ...(agentSignature && { agentSignature }) }
  let res
  try {
    res = await fetch('https://api.fipsign.dev/mandate/verify', {
      method: 'POST',
      headers,
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(10_000),
    })
  } catch {
    // Timeout or network failure: the call may or may not have been applied
    // (see "Retries and idempotency" below)
    return { ok: false, reason: 'network_error', unknownOutcome: true }
  }
  // A 403 carries a JSON body too: it is a normal answer
  const data = await res.json().catch(() => null)
  if (res.status === 200 && data?.result === 'granted') {
    return { ok: true, budgetRemaining: data.budgetRemaining }
  }
  return {
    ok: false,
    status: res.status,
    reason: data?.reason ?? data?.error ?? 'unknown',
    unknownOutcome: res.status >= 500,
  }
}

import os

import requests

API = "https://api.fipsign.dev"


def authorize(token, action, cost, agent_signature=None):
    """ok=True only when FIPSign explicitly granted the action.
    Anything else means "do not act"."""
    body = {"token": token, "action": action, "cost": cost}
    if agent_signature:
        body["agentSignature"] = agent_signature
    headers = {"X-API-Key": os.environ["FIPSIGN_API_KEY"]}
    try:
        r = requests.post(f"{API}/mandate/verify", json=body, headers=headers,
                          timeout=10)
    except requests.RequestException:
        # Timeout or network failure: the call may or may not have been applied
        # (see "Retries and idempotency" below)
        return {"ok": False, "reason": "network_error", "unknown_outcome": True}
    try:
        data = r.json()          # a 403 carries a JSON body too: it is a normal answer
    except ValueError:
        data = {}
    if r.status_code == 200 and data.get("result") == "granted":
        return {"ok": True, "budget_remaining": data.get("budgetRemaining")}
    return {
        "ok": False,
        "status": r.status_code,
        "reason": data.get("reason") or data.get("error") or "unknown",
        "unknown_outcome": r.status_code >= 500,
    }

Modify the mutable state of a mandate. No token cost. Four actions — each has different semantics and constraints. Requires only the mandate id — not the token itself. Rate limited to 60 req/min per API key.

curl -s -X PATCH https://api.fipsign.dev/mandate/$MANDATE_ID \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "narrow", "scope": ["verify"]}'

curl -s -X PATCH https://api.fipsign.dev/mandate/$MANDATE_ID \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "suspend"}'

curl -s -X PATCH https://api.fipsign.dev/mandate/$MANDATE_ID \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "resume"}'

curl -s -X PATCH https://api.fipsign.dev/mandate/$MANDATE_ID \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "revoke"}'

Returns the current state of a mandate. Use this to inspect budget consumption, current scope, status, or remaining time. No token cost.

curl -s https://api.fipsign.dev/mandate/$MANDATE_ID \
  -H "X-API-Key: $API_KEY" | jq

Returns the mandates of the project associated with the API key, most recent first (issuedAt descending), one page at a time. No token cost. It is meant for inspection and auditing: keep the id of every mandate you emit in your own database rather than listing to find it.

curl -s "https://api.fipsign.dev/mandate?limit=50" \
  -H "X-API-Key: $API_KEY" | jq

CURSOR=""
while :; do
  PAGE=$(curl -s "https://api.fipsign.dev/mandate?limit=100${CURSOR:+&cursor=$CURSOR}" \
    -H "X-API-Key: $API_KEY")
  echo "$PAGE" | jq -c '.mandates[] | {id, status, budgetConsumed}'
  CURSOR=$(echo "$PAGE" | jq -r '.nextCursor // empty')
  [ -z "$CURSOR" ] && break
done

Copy, replace your API key, and run to test the full mandate lifecycle against the live backend. Steps 1–12 cover the core lifecycle; step 13 is optional and covers proof of possession (agentPublicKey / agentSignature). Requires curl and jq; step 13 also needs Node 20+ (Python and Node versions with more detail are in 02b).

#!/bin/bash
# Requires: curl and jq. Step 13 (optional) also needs Node 20+ and:  npm install @noble/post-quantum
API_KEY="pqa_YOUR_API_KEY"
BASE_URL="https://api.fipsign.dev"

echo "[1/13] Emit mandate..."
MANDATE=$(curl -s -X POST $BASE_URL/mandate \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d '{"agentId":"agent-test","issuedBy":"[email protected]","scope":["sign","verify","read:data"],"budgetTotal":100,"expiresInSeconds":3600}')
MANDATE_ID=$(echo "$MANDATE" | jq -r '.mandate.id')
MANDATE_TOKEN=$(echo "$MANDATE" | jq -c '.mandate.token')
echo "id: $MANDATE_ID · status: $(echo "$MANDATE" | jq -r '.mandate.status')"

echo "[2/13] Verify — granted (sign, cost 5)..."
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $MANDATE_TOKEN, \"action\": \"sign\", \"cost\": 5}" | jq '{result,budgetRemaining}'

echo "[3/13] Verify — denied (scope_not_authorized)..."
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $MANDATE_TOKEN, \"action\": \"delete:records\", \"cost\": 0}" | jq '{result,reason}'

echo "[4/13] Read state..."
curl -s $BASE_URL/mandate/$MANDATE_ID -H "X-API-Key: $API_KEY" | jq '.mandate | {status,budgetConsumed,budgetRemaining,scopeCurrent}'

echo "[5/13] Suspend..."
curl -s -X PATCH $BASE_URL/mandate/$MANDATE_ID \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d '{"action": "suspend"}' | jq '.status'

echo "[6/13] Verify — denied (mandate_suspended)..."
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $MANDATE_TOKEN, \"action\": \"sign\", \"cost\": 5}" | jq '{result,reason}'

echo "[7/13] Resume..."
curl -s -X PATCH $BASE_URL/mandate/$MANDATE_ID \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d '{"action": "resume"}' | jq '.status'

echo "[8/13] Narrow scope to [verify] only..."
curl -s -X PATCH $BASE_URL/mandate/$MANDATE_ID \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d '{"action": "narrow", "scope": ["verify"]}' | jq '.scope'

echo "[9/13] Verify — denied (sign no longer in scope)..."
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $MANDATE_TOKEN, \"action\": \"sign\", \"cost\": 5}" | jq '{result,reason,authorizedScope}'

echo "[10/13] Revoke..."
curl -s -X PATCH $BASE_URL/mandate/$MANDATE_ID \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d '{"action": "revoke"}' | jq '.status'

echo "[11/13] Verify — denied (mandate_revoked)..."
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $MANDATE_TOKEN, \"action\": \"verify\", \"cost\": 0}" | jq '{result,reason}'

echo "[12/13] List mandates (first 3)..."
curl -s "$BASE_URL/mandate?limit=3" -H "X-API-Key: $API_KEY" | jq '.mandates[] | {id,status,budgetConsumed,scopeOriginal,scopeCurrent}'

echo "[13/13] Proof of possession — emit with agentPublicKey, verify with/without agentSignature..."
# Requires Node 20+ with @noble/post-quantum installed in the current folder: npm install @noble/post-quantum
umask 077   # the agent's seed (its private key) is written to a file that only your user can read
node --input-type=module -e '
import { ml_dsa44 } from "@noble/post-quantum/ml-dsa.js"
const b64 = (u8) => Buffer.from(u8).toString("base64")
const seed = new Uint8Array(32); crypto.getRandomValues(seed)
const { publicKey } = ml_dsa44.keygen(seed)
console.log(JSON.stringify({ publicKey: b64(publicKey), seed: b64(seed) }))
' > /tmp/agent-keys.json

AGENT_PUBLIC_KEY=$(jq -r '.publicKey' /tmp/agent-keys.json)

PO_MANDATE=$(curl -s -X POST $BASE_URL/mandate \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"agentId\":\"agent-pop-test\",\"issuedBy\":\"[email protected]\",\"scope\":[\"sign\"],\"budgetTotal\":10,\"expiresInSeconds\":3600,\"agentPublicKey\":\"$AGENT_PUBLIC_KEY\"}")
echo "requiresAgentSignature: $(echo "$PO_MANDATE" | jq -r '.mandate.requiresAgentSignature')"

PO_ID=$(echo "$PO_MANDATE" | jq -r '.mandate.id')
PO_TOKEN=$(echo "$PO_MANDATE" | jq -c '.mandate.token')

echo "  → verify WITHOUT agentSignature (expect denied / agent_signature_required)"
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $PO_TOKEN, \"action\": \"sign\", \"cost\": 1}" | jq '{result,reason}'

# The agent signs THIS call: mandate id + action + cost, valid for 30 seconds, usable once
AGENT_SIGNATURE=$(node --input-type=module -e '
import { ml_dsa44 } from "@noble/post-quantum/ml-dsa.js"
import { readFileSync } from "fs"
const b64 = (u8) => Buffer.from(u8).toString("base64")
const { seed } = JSON.parse(readFileSync("/tmp/agent-keys.json", "utf8"))
const { secretKey } = ml_dsa44.keygen(Buffer.from(seed, "base64"))
const now = Math.floor(Date.now() / 1000)
const payload = { sub: process.argv[1], action: "sign", cost: 1, iat: now, exp: now + 30 }
const payloadB64 = Buffer.from(JSON.stringify(payload)).toString("base64")
const sig = ml_dsa44.sign(new TextEncoder().encode(payloadB64), secretKey)
// algorithm: exactly "ML-DSA-44", the variant of this key (ml_dsa44)
console.log(JSON.stringify({ payload: payloadB64, signature: b64(sig), algorithm: "ML-DSA-44", issuedAt: now }))
' "$PO_ID")

echo "  → verify WITH agentSignature (expect granted)"
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $PO_TOKEN, \"action\": \"sign\", \"cost\": 1, \"agentSignature\": $AGENT_SIGNATURE}" | jq '{result,budgetRemaining}'

echo "  → verify AGAIN with the same agentSignature (expect denied / agent_signature_replayed)"
curl -s -X POST $BASE_URL/mandate/verify \
  -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" \
  -d "{\"token\": $PO_TOKEN, \"action\": \"sign\", \"cost\": 1, \"agentSignature\": $AGENT_SIGNATURE}" | jq '{result,reason}'

rm -f /tmp/agent-keys.json

When project keys are rotated from the dashboard, Mandate handles it the same way as POST /verify.