Set these in your terminal before running any REST/curl command in this guide. If you are using the SDK you only need your API key.

# Replace with your API key from the dashboard (starts with pqa_)
export API_KEY="pqa_YOUR_API_KEY_HERE"
export BASE_URL="https://api.fipsign.dev"

Works in Node.js, Deno and Cloudflare Workers — run it on your backend. In a browser the code runs, but calls to the API only work from FIPSign's own domains (see the note at the top of this tab). TypeScript types included — no separate @types package needed. On Node.js use version 20 or newer: on Node 18 the key-generation functions and zes fail with crypto is not defined.

npm install fipsign-sdk

// Simple form — just the API key
import { PQAuth } from 'fipsign-sdk'

const pq = new PQAuth('pqa_your_api_key')

// Or with all options (see SDK 11 for full reference):
// const pq = new PQAuth({
//   apiKey:      'pqa_your_api_key',
//   baseUrl:     'https://api.fipsign.dev', // default
//   localVerify: false,   // set to true for offline verification (SDK 04)
//   projectId:   undefined, // required when localVerify: true (SDK 04)
//   timeout:     10_000,  // request timeout in ms, default 10000
// })

Signs any payload with ML-DSA (44, 65, or 87 — configured per project at creation). The only required field is sub — any string identifying the entity. All other fields are stored in the payload and returned on verify. Token cost: see Costs.

const { token, meta, usage } = await pq.sign({
  sub:              'user_123',
  email:            'user@example.com',
  role:             'admin',
  expiresInSeconds: 3600,    // optional — default: 1 hour
})

const { token } = await pq.sign({
  sub:      'order_456',
  amount:   299.99,
  currency: 'USD',
  expiresInSeconds: 300,
})

const { token } = await pq.sign({
  sub:      'doc_789',
  hash:     'sha256:abc...',
  signedBy: 'alice',
})

const { token } = await pq.sign({
  sub:     'agent_summarizer_v2',
  action:  'document:summarize',
  userId:  'user_123',
  traceId: 'trace_abc',
})

const { token } = await pq.sign({
  sub:      'device_iot_001',
  firmware: '2.1.4',
  location: 'plant-A',
})

const { token, meta, usage } = await pq.sign({ sub: 'user_123' })
console.log(`${usage.freeRemaining} free · ${usage.packRemaining} pack`)
console.log(`charged from: ${meta.source}`)  // "free" | "pack" | "free+pack"
console.log(`project: ${meta.projectId} · account: ${meta.issuedFor}`)

Verifies the ML-DSA signature (algorithm read from the token itself), token expiry, and the revocation list. Never throws — always returns an object. Token cost: see Costs.

const result = await pq.verify(token)

if (!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'
    return res.status(401).json({ error: '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.
  if (result.retryAfter !== undefined) res.set('Retry-After', String(result.retryAfter))
  return res.status(503).json({ error: 'Authentication service temporarily unavailable' })
}

const { payload } = result
console.log(payload.sub)    // 'user_123'
console.log(payload.role)   // 'admin'
console.log(payload.exp)    // expiry Unix timestamp
console.log(payload.iat)    // issued at Unix timestamp
// All custom fields passed to sign() are available on payload too

Enable localVerify: true to verify tokens entirely in memory — no API call, no network latency, no token cost.

const pq = new PQAuth({
  apiKey:      'pqa_your_api_key',
  localVerify: true,
  projectId:   'proj_...',  // required — from the dashboard or meta.projectId in /sign's response
})

// Optional: preload public key at startup to avoid first-request latency
await pq.preloadPublicKey()

const { valid, payload, local } = await pq.verify(token)
console.log(local) // true — verified without an API call

Immediately and permanently invalidates a token. Future verify() calls will reject it even if the signature is valid and the token has not yet expired. Token cost: see Costs.

const { success, message, revokedAt, sub, expiresAt, note } =
  await pq.revoke(token, 'user logged out')

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

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

const { valid } = await pq.verify(token)
console.log(valid) // false — error: 'Token has been revoked'

Reads Authorization: Bearer <token>, verifies the token, and attaches the decoded payload to req.user. Answers 401 when the token is missing or FIPSign refuses it, and 503 when FIPSign could not check it. Node.js only. It is an Express-style function ((req, res, next), answering with res.status(...).json(...)), so it works as it is in Express; for Fastify see below.

import express from 'express'
import { PQAuth } from 'fipsign-sdk'

const app = express()
const pq  = new PQAuth('pqa_your_api_key')

app.use(express.json())

// Stand-in for your own user check. Replace it with your database lookup
// and a real password comparison (bcrypt, argon2…).
async function authenticate(email, password) {
  if (email === 'ana@example.com' && password === 'correct-horse') {
    return { id: 'user_123', email, role: 'admin' }
  }
  return null
}

// Login — sign a token and return it base64-encoded to the client
app.post('/login', async (req, res) => {
  const user = await authenticate(req.body.email, req.body.password)
  if (!user) {
    return res.status(401).json({ error: 'Invalid credentials' })
  }

  const { token } = await pq.sign({
    sub:              user.id,
    email:            user.email,
    role:             user.role,
    expiresInSeconds: 3600,
  })

  // Encode to base64 — this is what the client puts in Authorization: Bearer <encoded>
  const encoded = Buffer.from(JSON.stringify(token)).toString('base64')
  res.json({ token: encoded })
})

// Logout — decode the header and revoke the token immediately
app.post('/logout', async (req, res) => {
  const header = req.headers['authorization'] ?? ''
  if (header.startsWith('Bearer ')) {
    try {
      const token = JSON.parse(Buffer.from(header.slice(7), 'base64').toString('utf8'))
      await pq.revoke(token, 'user logged out')
    } catch { /* ignore malformed token */ }
  }
  res.json({ success: true })
})

// Protect all routes under /api with the FIPSign middleware
app.use('/api', pq.middleware())

// req.user is the verified payload — sub, email, role, exp, iat, plus any custom fields
app.get('/api/profile', (req, res) => {
  res.json({ user: req.user })
})

app.listen(3000)

TOKEN=$(curl -s -X POST localhost:3000/login -H 'Content-Type: application/json' \
  -d '{"email":"ana@example.com","password":"correct-horse"}' | jq -r .token)

curl -s localhost:3000/api/profile -H "Authorization: Bearer $TOKEN"
# {"user":{"sub":"user_123","email":"ana@example.com","role":"admin","_iss":"prj_...","iat":...,"exp":...}}

curl -s -i localhost:3000/api/profile
# HTTP/1.1 401 Unauthorized
# ...
# {"error":"Authorization header required (Bearer <token>)"}

Fastify cannot use an Express-style function as a hook: app.addHook('onRequest', pq.middleware()) fails when you register it, with FST_ERR_HOOK_INVALID_ASYNC_HANDLER. Use it through @fastify/express, which adds app.use() to Fastify.

// npm install fastify @fastify/express
import Fastify from 'fastify'
import fastifyExpress from '@fastify/express'
import { PQAuth } from 'fipsign-sdk'

const app = Fastify()
const pq  = new PQAuth('pqa_your_api_key')

await app.register(fastifyExpress)    // adds app.use() for Express-style middleware
app.use('/api', pq.middleware())

// The middleware sets user on Node's raw request, so in Fastify it is request.raw.user
app.get('/api/profile', async (request) => {
  return { user: request.raw.user }
})

await app.listen({ port: 3000 })

Returns the current token balance, 6-month usage history, and purchased packs. Token cost: see Costs.

const { current, monthlyHistory, packs, developer } = await pq.usage()

// Current balance
console.log(`Month: ${current.month}`)                             // e.g. "2026-06"
console.log(`Free:  ${current.freeRemaining} / ${current.freeLimit}`)
console.log(`Used:  ${current.freeUsed} this month`)
console.log(`Pack:  ${current.packRemaining}`)
console.log(`Total: ${current.totalRemaining}`)
console.log(`Account: ${developer.email}`)

// 6-month history (always 6 entries, months with no activity show 0)
monthlyHistory.forEach(({ month, tokensUsed, fromFree, fromPack }) => {
  console.log(`${month}: ${tokensUsed} used (${fromFree} free + ${fromPack} pack)`)
})

// Purchased packs
packs.forEach(({ id, packType, tokensPurchased, purchasedAt, paymentRef }) => {
  console.log(`${packType}: ${tokensPurchased} tokens — ${new Date(purchasedAt * 1000).toLocaleDateString()}`)
  console.log(`  id: ${id} — paymentRef: ${paymentRef ?? 'n/a'}`)
})

Checks the health of the FIPSign service. Does not require an API key and does not consume tokens.

const { status, algorithm, quantumResistant, version } = await pq.health()

console.log(status)           // "ok"
console.log(algorithm)        // "ML-DSA-44/65/87"
console.log(quantumResistant) // true
console.log(version)          // e.g. "2.0.0"

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.

verify(), ca.verifyCert(), ca.verifyX509Cert() and ca.verifyCrl() never throw — they always return { valid: false, error } on failure, with error as text (local verification errors such as an invalid signature, an expired token, another project's token, a certificate from another CA or an expired one, or a revocation list that your CA did not sign are reported there, not as codes). verify() also returns failure, which tells a token that FIPSign refuses from a check that did not happen (SDK 03). All other methods throw PQAuthError.

import { PQAuth, PQAuthError } from 'fipsign-sdk'

try {
  await pq.sign({ sub: 'user_123' })
} catch (err) {
  if (err instanceof PQAuthError) {
    switch (err.code) {
      case 'INVALID_API_KEY':        // key format invalid — must be pqa_ + 64 hex chars
        break
      case 'MISSING_PROJECT_ID':     // localVerify: true without projectId
        break
      case 'API_ERROR':              // server error: see err.status (429: err.serverCode)
        break
      case 'TIMEOUT':                // request exceeded timeout (default: 10s)
        break
      case 'NETWORK_ERROR':          // connection failed
        break
      case 'MISSING_SUB':            // sign() called without sub
        break
      case 'INVALID_ARGUMENT':        // signAgentCall(): missing or invalid argument
        break
      case 'INVALID_SECRET_KEY':      // signAgentCall(): secretKey is not an ML-DSA private key (e.g. a 32-byte seed)
        break
      case 'UNSUPPORTED_ALGORITHM':  // generateAgentKeyPair() / signAgentCall(): unknown ML-DSA variant name
        break
    }
    console.error(err.code, err.message, err.status)
  }
}

import { PQAuthError } from 'fipsign-sdk'

async function signWithRetry(pq, claims) {
  try {
    return await pq.sign(claims)
  } catch (err) {
    if (err instanceof PQAuthError && err.serverCode === 'rate_limited') {
      // retryAfter: seconds until the one-minute window ends (from the Retry-After header)
      await new Promise(resolve => setTimeout(resolve, (err.retryAfter ?? 1) * 1000))
      return await pq.sign(claims)    // one retry; if it fails again, the error is thrown
    }
    throw err    // 'token_quota_exhausted' and every other error: waiting will not fix it
  }
}

All available options when instantiating PQAuth.

const pq = new PQAuth({
  apiKey:      'pqa_...',
  baseUrl:     'https://api.fipsign.dev',
  timeout:     10_000,
  localVerify: false,
  projectId:   'proj_...',  // required when localVerify: true
})

Issue and verify 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. Token cost of each method: see Costs.

import { PQAuth, generateKeyPair } from 'fipsign-sdk'

const { publicKey, secretKey } = await generateKeyPair()
// publicKey: base64-encoded ML-DSA-65 public key  — 1952 bytes raw
// secretKey: base64-encoded ML-DSA-65 expanded key — 4032 bytes raw
// store secretKey securely on the device — never send it to the server
// pass publicKey to ca.issue() to obtain a certificate

// ── PQCert CA ──────────────────────────────────────────────────────────────
const { certificate, meta, usage } = await pq.ca.issue({
  subject:          'device-serial-00123',
  publicKey:        devicePublicKey,            // base64 ML-DSA-65 public key
  expiresInSeconds: 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
})
// certificate is a PQCert JSON object
console.log(certificate.id)        // cert_...
console.log(certificate.caId)      // ca_... — the CA that signed it
console.log(certificate.expiresAt) // Unix timestamp
console.log(meta.certId)           // same as certificate.id
console.log(meta.caId)             // ca_...
console.log(meta.subject)          // 'device-serial-00123'
console.log(meta.format)           // 'pqcert'
console.log(meta.issuedAt)         // Unix timestamp
console.log(meta.expiresAt)        // Unix timestamp
console.log(meta.algorithm)        // 'ML-DSA-65'
console.log(meta.standard)         // 'NIST FIPS 204'
console.log(meta.caExpiry)         // null normally; { 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.
const { certificate: certPem, meta, usage } = await pq.ca.issue({
  subject:          'device-serial-00123',
  publicKey:        devicePublicKey,
  expiresInSeconds: 365 * 24 * 60 * 60,
})
// certificate is a PEM string
console.log(typeof certPem)        // "string"
console.log(certPem)              // "-----BEGIN CERTIFICATE-----\n..."
console.log(meta.certId)           // cert_... — use this for revocation
console.log(meta.caId)             // ca_...
console.log(meta.format)           // 'x509'
console.log(meta.sizeNote)         // size advisory for IoT memory planning

import { readFileSync } from 'node:fs'
import { PQAuth } from 'fipsign-sdk'

const pq = new PQAuth('pqa_your_api_key')

// root-cert.json: the root certificate you saved when the CA was created
// device-cert.json: the certificate the device presents (a PQCert JSON object)
const rootCert   = JSON.parse(readFileSync('./root-cert.json', 'utf8'))
const deviceCert = JSON.parse(readFileSync('./device-cert.json', 'utf8'))

const result = pq.ca.verifyCert(deviceCert, rootCert)   // synchronous — no await

if (!result.valid) {
  // result.error is plain text for your logs: decide with result.valid, do not compare the text.
  // It is one of:
  //   'Expected a CA_CERT, got ...' / 'Expected a CA_ROOT, got ...'
  //   'Certificate was not issued by this CA'
  //   'Root CA certificate expired N seconds ago'
  //   'Certificate expired N seconds ago'
  //   'Invalid certificate signature — not issued by this CA'
  //   'Unknown error' (malformed input, for example a certificate that is not an object)
  console.error(result.error)
  throw new Error('Device not authorized')
}

console.log(result.cert.subject)   // 'device-serial-00123'
console.log(result.cert.expiresAt) // Unix timestamp

// rootCertPem is the PEM string shown at CA creation — save it once
const result = await pq.ca.verifyX509Cert(deviceCertPem, rootCertPem)

if (!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)'
  //   'Unexpected public key size: N bytes (expected 1952 or 1953 for ML-DSA-65)'
  //   'Unexpected signature size: N bytes (expected 3309 or 3310 for ML-DSA-65)'
  console.error(result.error)
  return reject('Device not authorized')
}

// result.cert is the PEM string of the verified certificate
console.log(result.cert) // "-----BEGIN CERTIFICATE-----\n..."

const { crl } = await pq.ca.getCrl()

// PQCert CA — pass the certificate object
if (pq.ca.isCertRevoked(deviceCert, crl)) {
  return reject('Device certificate has been revoked')
}

// X.509 CA — pass the certId string from meta.certId
if (pq.ca.isCertRevoked(meta.certId, crl)) {
  return reject('Device certificate has been revoked')
}

const { caId, subject, crl, generatedAt, raw } = await pq.ca.getCrl()

console.log(`CA: ${subject}`)
console.log(`${crl.length} revoked certificates`)

crl.forEach(({ certId, revokedAt, reason }) => {
  // reason may be null if no reason was provided at revocation time
  console.log(`${certId} — revoked ${new Date(revokedAt * 1000).toISOString()} — ${reason ?? 'no reason'}`)
})

// raw is the whole list as the CA signed it, for PQCert and X.509 CAs:
// { caId, subject, format, algorithm, generatedAt, revokedCerts, signature }
// ca.verifyCrl() checks it (next step)
if (raw) {
  console.log(raw.signature) // base64 ML-DSA-65 signature over the canonical list
}

const list = await pq.ca.getCrl()

// rootCert: the root certificate you saved when the CA was created
//   PQCert CA: the CA_ROOT object (JSON.parse of root-cert.json)
//   X.509 CA:  the PEM string
const check = await pq.ca.verifyCrl(list, rootCert)

if (!check.valid) {
  // check.error is plain text for your logs: decide with check.valid, do not compare the text.
  // It is one of:
  //   'Invalid list signature — not signed by this CA'
  //   'This list was not issued by this CA'
  //   'This list is from a PQCert CA: pass its CA_ROOT certificate ...'
  //   'This list is from an X.509 CA: pass its root certificate in PEM form (a string)'
  //   'The entries of this result (crl, caId, subject, generatedAt) are not the signed ones (raw)'
  //   'This list is not signed: ...'
  //   'The root certificate could not be read: pass the PEM of the CA root certificate'
  //   'Unsupported root CA algorithm: <OID>. Expected ML-DSA-65 (2.16.840.1.101.3.4.3.18)'
  console.error(check.error)
  throw new Error('Revocation list not trusted')
}

// check.generatedAt is when the CA signed the list (Unix seconds). A correctly signed old list is still
// valid: you decide how old a list you accept.
const ageSeconds = Math.floor(Date.now() / 1000) - check.generatedAt
if (ageSeconds > 15 * 60) throw new Error('Revocation list is too old: download it again')

// Now the entries can be trusted
if (pq.ca.isCertRevoked(deviceCert, list.crl)) throw new Error('Device certificate has been revoked')

const { certificate, status, meta } = await pq.ca.getCert('cert_...')

console.log(status.revoked)   // boolean
console.log(status.expired)   // boolean
console.log(status.revokedAt) // Unix timestamp or null
console.log(status.expiresAt) // Unix timestamp

// For PQCert CAs, certificate is a PQCert object
// For X.509 CAs, certificate is a PEM string
// For X.509 CAs, meta contains additional fields:
if (meta) {
  console.log(meta.certId)    // cert_...
  console.log(meta.caId)      // ca_...
  console.log(meta.subject)   // 'device-serial-00123'
  console.log(meta.format)    // 'x509'
  console.log(meta.algorithm) // 'ML-DSA-65'
}

const { certId, revokedAt, reason, usage } = await pq.ca.revokeCert(
  'cert_...',
  'device decommissioned'
)

console.log(certId)              // cert_...
console.log(revokedAt)           // Unix timestamp
console.log(reason)              // 'device decommissioned' (or null if omitted)
console.log(usage.freeRemaining) // tokens remaining after this operation

import { readFileSync } from 'node:fs'
import { PQAuth, generateKeyPair } from 'fipsign-sdk'

const pq = new PQAuth('pqa_your_api_key')
// root-cert.json: the root certificate you saved when the CA was created
const rootCert = JSON.parse(readFileSync('./root-cert.json', 'utf8'))

// 1. Factory: generate a key pair for the device
const { publicKey, secretKey } = await generateKeyPair()

// 2. Factory: issue a certificate for the device
const { certificate } = await pq.ca.issue({
  subject:          'lock-serial-00123',
  publicKey,
  expiresInSeconds: 365 * 24 * 60 * 60,
  meta:             { model: 'lock-v3', batch: '2026-05' },
})
// store certificate (PQCert JSON object) and secretKey on the device

// 3. At runtime: verify the device certificate offline
const result = pq.ca.verifyCert(certificate, rootCert)
if (!result.valid) throw new Error(result.error)

// 4. Revocation: download the CRL every few minutes, check its signature and keep it (not on every check)
const list  = await pq.ca.getCrl()
const check = await pq.ca.verifyCrl(list, rootCert)
if (!check.valid) throw new Error(check.error)
// At runtime: look the device up in the list you kept
if (pq.ca.isCertRevoked(certificate, list.crl)) throw new Error('Device revoked')

// 5. Decommission: revoke the certificate
await pq.ca.revokeCert(certificate.id, 'device decommissioned')

import { PQAuth, generateKeyPair } from 'fipsign-sdk'

const pq          = new PQAuth('pqa_your_api_key')
const rootCertPem = process.env.ROOT_CERT_PEM  // PEM saved at CA creation

// 1. Factory: generate a key pair for the device
const { publicKey, secretKey } = await generateKeyPair()

// 2. Factory: issue a certificate for the device
const { certificate: certPem, meta } = await pq.ca.issue({
  subject:          'lock-serial-00123',
  publicKey,
  expiresInSeconds: 365 * 24 * 60 * 60,
})
// store certPem (PEM string), meta.certId, and secretKey on the device

// 3. At runtime: verify the device certificate offline
const result = await pq.ca.verifyX509Cert(certPem, rootCertPem)
if (!result.valid) throw new Error(result.error)

// 4. Revocation: download the CRL every few minutes, check its signature and keep it (not on every check)
const list  = await pq.ca.getCrl()
const check = await pq.ca.verifyCrl(list, rootCertPem)
if (!check.valid) throw new Error(check.error)
// At runtime: look the device up in the list you kept
if (pq.ca.isCertRevoked(meta.certId, list.crl)) throw new Error('Device revoked')

// 5. Decommission: revoke the certificate using the certId from meta
await pq.ca.revokeCert(meta.certId, '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.

const { token, hash } = await pq.zes.sign({
  patient:   'Jane Doe',
  diagnosis: 'confidential',
  record_id: 'MR-2026-4491',
})
// hash: the 64-char SHA-256 hex digest that was actually signed
// token.payload decodes to { sub: 'zes:<hash>', zes: true, iat, exp }

const { valid, dataMatches } = await pq.zes.verify(token, {
  patient:   'Jane Doe',
  diagnosis: 'confidential',
  record_id: 'MR-2026-4491',
})
if (!valid || !dataMatches) return reject('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. Token cost of each method: see Costs.

const { mandate } = await pq.mandate.emit({
  agentId:          'agent-reporting-v2',
  issuedBy:         'user@empresa.com',
  scope:            ['sign', 'verify', 'read:crm'],
  budgetTotal:      1000,             // abstract units — 0 disables budget checking
  expiresInSeconds: 28800,            // whole number, min 60, max 2_592_000 (30 days)
})
console.log(mandate.id)     // mdt_... — use for narrow/suspend/resume/revoke/get
console.log(mandate.status) // 'active'
const mandateToken = mandate.token  // give this to the agent — not stored server-side, save it now

Optional: pass agentPublicKey to require proof of possession — see Proof of possession with the SDK below. The response then carries requiresAgentSignature: true. It also carries a receipt, FIPSign's signature over the emitted event: see Receipts and the audit log below.

const check = await pq.mandate.verify(mandateToken, 'read:crm', 1)  // (token, action, cost)
// Mandates with proof of possession take the agent's signature as a 4th 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)
  // check.failure: 'rejected' | 'rate_limited' | 'quota_exhausted' | 'unavailable' | 'outcome_unknown' — table below
  return reject(check.reason)
}
// granted — check.budgetRemaining and check.expiresInSeconds are also present
doTheAction()

const check = await pq.mandate.verify(mandateToken, 'read:crm', 1)

if (check.result !== 'granted') {
  if (check.failure === 'outcome_unknown') {
    // No usable answer: the call may have been granted and charged. Do NOT act yet.
    // Without proof of possession: read the budget and compare it with the value you had before the call.
    const { mandate: now } = await pq.mandate.get(mandateId)  // needs your full-access key
    console.log('budgetConsumed is now', now.budgetConsumed)
    throw new Error('outcome unknown: do not act yet')
  }
  if (check.failure === 'rate_limited') throw new Error(`rate limited: try again in ${check.retryAfter} s`)
  return reject(check.reason)
}
doTheAction()

import { generateAgentKeyPair } from 'fipsign-sdk'

// On the agent, once. The default variant is ML-DSA-65.
const { publicKey, secretKey, algorithm } = await generateAgentKeyPair()
// Another variant: await generateAgentKeyPair({ algorithm: 'ML-DSA-44' })  // or 'ML-DSA-87'

// publicKey → goes to your backend, for mandate.emit({ agentPublicKey })
// secretKey → stays on the agent, in a secret store. Never send it anywhere.

const { mandate } = await pq.mandate.emit({
  agentId:          'agent-reporting-v2',
  issuedBy:         'user@empresa.com',
  scope:            ['sign', 'send_reply'],
  budgetTotal:      1000,
  expiresInSeconds: 28800,
  agentPublicKey:   publicKey,      // base64, from generateAgentKeyPair()
})
console.log(mandate.requiresAgentSignature)  // true
// Keep mandate.id in your database: you need it to narrow, suspend, revoke and inspect.
const mandateToken = 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 { signAgentCall } from 'fipsign-sdk'

// On the agent, for EVERY call: no API key needed, nothing is sent to FIPSign.
const agentSignature = await signAgentCall({
  mandate: mandateToken,   // the mandate token (or just the mandate id)
  action:  'send_reply',   // exactly what mandate.verify() will receive
  cost:    1,              // exactly what mandate.verify() will receive
  secretKey,               // from generateAgentKeyPair()
})
// Send agentSignature to whoever calls mandate.verify() — your executor, or the agent itself

const check = await pq.mandate.verify(mandateToken, 'send_reply', 1, { agentSignature })

if (check.result !== 'granted') {
  // check.reason also covers the agent's signature:
  // 'agent_signature_required' | 'agent_signature_invalid' |
  // 'agent_signature_mismatch' | 'agent_signature_replayed'
  return reject(check.reason)
}
doTheAction()

import { PQAuthError, signAgentCall } from 'fipsign-sdk'

try {
  await signAgentCall({ mandate: mandateToken, action: 'send_reply', cost: 1, secretKey })
} catch (err) {
  if (err instanceof PQAuthError) console.error(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.mjs, run npm install fipsign-sdk, then FIPSIGN_API_KEY=pqa_... node pop-sdk-demo.mjs (Node 20+). Token cost: the emit and the one granted verify (see Costs); denied calls are free.

// pop-sdk-demo.mjs — proof of possession with the SDK, end to end.
// Setup: npm install fipsign-sdk        (Node 20+)
// Run:   FIPSIGN_API_KEY=pqa_... node pop-sdk-demo.mjs
import { PQAuth, generateAgentKeyPair, signAgentCall } from 'fipsign-sdk'

const pq = new PQAuth(process.env.FIPSIGN_API_KEY)

// ── AGENT SIDE ──────────────────────────────────────────────────────────
// The agent creates its own key pair. The secret key never leaves the agent.
const { publicKey, secretKey } = await generateAgentKeyPair()

// ── YOUR BACKEND ────────────────────────────────────────────────────────
// 1. Emit the mandate, registering the agent's PUBLIC key.
const { mandate } = await pq.mandate.emit({
  agentId:          'agent-pop-demo',
  issuedBy:         'dev@example.com',
  scope:            ['sign'],
  budgetTotal:      10,
  expiresInSeconds: 3600,
  agentPublicKey:   publicKey,
})
console.log('emitted', mandate.id, '· requiresAgentSignature:', mandate.requiresAgentSignature)

// 2. Without agentSignature the mandate token alone is useless.
let r = await pq.mandate.verify(mandate.token, 'sign', 1)
console.log('no signature   →', r.result, r.reason)

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

// 4. Sending the same signature again is refused: each signature works once.
r = await pq.mandate.verify(mandate.token, 'sign', 1, { agentSignature: signature })
console.log('same signature →', r.result, r.reason)

// 5. A signature made for cost 1 cannot be used for cost 9.
const other = await signAgentCall({ mandate: mandate.token, action: 'sign', cost: 1, secretKey })
r = await pq.mandate.verify(mandate.token, 'sign', 9, { agentSignature: other })
console.log('cost changed   →', r.result, r.reason)

// Clean up: revoke the demo mandate.
await 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

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

const patched = await pq.mandate.suspend(mandate.id)
console.log(patched.status, patched.scope, patched.updatedAt)
// 'suspended' [ 'sign', 'verify', 'read:crm' ] 1785691318

const { mandate } = await pq.mandate.get('mdt_...')
console.log(mandate.budgetConsumed, mandate.budgetRemaining, mandate.scopeCurrent, mandate.status)

// First page: the 50 most recent mandates of this project
const { mandates, count, nextCursor } = await pq.mandate.list()

// Your own page size (1–100), then the next page
const page1 = await pq.mandate.list({ limit: 20 })
const page2 = page1.nextCursor
  ? await pq.mandate.list({ limit: 20, cursor: page1.nextCursor })
  : null

// Every mandate, page by page — stop whenever you want with break
for await (const m of pq.mandate.listAll()) {
  console.log(m.id, m.status, m.budgetConsumed)
}

FIPSign records everything that happens to a mandate — it was emitted, each call it granted or denied, each change — in a log, and signs it. There is nothing to switch on. With the SDK you ask for a receipt on the calls you may have to prove, keep it, and check it on your own machine; later you can read the log and export it. Receipts, reading the log and the export cost no tokens (Costs). What the log holds, how it is protected and what a receipt does and does not prove: Mandate 11 to 15. The steps below follow one another: each one uses what the one before it made, and the complete example at the end runs all of them.

// emit(): the answer has the receipt next to the mandate
const { mandate, receipt: emitted } = await pq.mandate.emit({
  agentId:          'agent-reporting-v2',
  issuedBy:         'user@empresa.com',
  scope:            ['sign', 'verify', 'read:crm'],
  budgetTotal:      1000,
  expiresInSeconds: 28800,
  correlationId:    'ticket-4821',   // your own id for this call
})

// verify(): a receipt only if you ask for it, granted or denied
const check = await pq.mandate.verify(mandate.token, 'read:crm', 1, {
  receipt: true,
  correlationId: 'req-77',
})
console.log(check.result, check.receipt.event.seq)   // granted 2  (1 is the emit)

// narrow(), suspend(), resume() and revoke(): always a receipt
const { receipt: revoked } = await pq.mandate.revoke(mandate.id, {
  correlationId: 'ticket-4822',
})
console.log(revoked.event.type)   // revoked

Keep the receipt next to your own record of the call, as JSON:

import { writeFileSync } from 'node:fs'

writeFileSync('receipt-emit.json', JSON.stringify(emitted))

The fingerprint is the SHA-256 of the public key of your project, 64 hexadecimal characters. It tells you which key to trust. Run this once, the day you integrate:

import { PQAuth, publicKeyFingerprint } from 'fipsign-sdk'

const pq = new PQAuth(process.env.FIPSIGN_API_KEY)
const { keys } = await pq.mandate.publicKeys()
const current = keys.find((k) => k.status === 'current')
console.log(await publicKeyFingerprint(current.publicKey))
// Prints: <64 hexadecimal characters>

import { verifyMandateReceipt } from 'fipsign-sdk'

// The fingerprints you saved, separated by commas (one for each key you had)
const pinned = process.env.FIPSIGN_KEY_FINGERPRINTS.split(',')
const { keys } = await pq.mandate.publicKeys()   // free; includes retired keys

const result = await verifyMandateReceipt(emitted, {
  pinFingerprint: pinned,
  keys,
  expect: { mandateId: mandate.id },   // fails if the receipt is of another mandate
})
if (result.valid) {
  const { seq, type, at } = result.event
  console.log(`valid: event ${seq} (${type}) of ${result.mandateId}, at ${at}`)
} else {
  console.log('NOT valid:', result.problems)
}
// Prints: valid: event 1 (emitted) of mdt_…, at 1785690939

// Every event of one mandate, oldest first (the pages are fetched for you)
for await (const e of pq.mandate.eventsAll(mandate.id)) {
  console.log(e.seq, e.type, JSON.parse(e.body).correlationId)
}

// Search the events of all your mandates, newest first
const { events } = await pq.mandate.queryEvents({ correlationId: 'req-77' })
for (const e of events) console.log(e.mandateId, e.seq, e.type)

// Every denied call of the last 7 days, page by page
for await (const e of pq.mandate.queryEventsAll({ type: 'verify_denied' })) {
  console.log(e.mandateId, e.at, JSON.parse(e.body).reason)
}
// Prints:
//   1 emitted ticket-4821
//   2 verify_granted req-77
//   3 revoked ticket-4822
//   mdt_… 2 verify_granted
//   mdt_… 1785691402 scope_not_authorized     (one line for each denied call)

import { readFileSync, writeFileSync } from 'node:fs'
import { verifyMandateExport } from 'fipsign-sdk'

const pages = await pq.mandate.exportAll(mandate.id)   // every page, in order
writeFileSync('export.json', JSON.stringify(pages))     // keep it

// Now, or years later, with no network and no API key:
const saved = JSON.parse(readFileSync('export.json', 'utf8'))
const audit = await verifyMandateExport(saved, { pinFingerprint: pinned })
console.log(audit.valid, audit.complete, audit.events, audit.problems)
// Prints: true false 3 []     (valid, complete, events, problems)

Change one number of a receipt and the check says so. Run it after Step 3, with the same pinned and keys:

// Change one number of a receipt: it no longer passes
const forged = structuredClone(emitted)
const body = forged.event.body
forged.event.body = body.replace('"budgetTotal":1000', '"budgetTotal":9999')
const bad = await verifyMandateReceipt(forged, { pinFingerprint: pinned, keys })
console.log(bad.valid, bad.problems)
// Prints: false [ 'event 1: hash is not sha256(prevHash + "\\n" + body)' ]

Emits a mandate, makes one granted and one denied call, checks the three receipts, shows that a changed receipt fails, revokes the mandate, reads its log, finds an event by your own id and checks the export. Save as audit-sdk-demo.mjs, run npm install fipsign-sdk, set FIPSIGN_API_KEY and FIPSIGN_KEY_FINGERPRINTS (the fingerprint you saved in Step 2) and run node audit-sdk-demo.mjs (Node 20+). Token cost: the emit and the one granted verify (see Costs); the denied call, the receipts, the reads and the checks are free.

// audit-sdk-demo.mjs — receipts, the log and the export with the SDK, end to end.
// Setup: npm install fipsign-sdk        (Node 20+)
// Run:   export FIPSIGN_API_KEY=pqa_...
//        export FIPSIGN_KEY_FINGERPRINTS=<64 hexadecimal characters>
//        node audit-sdk-demo.mjs
import { PQAuth, verifyMandateReceipt, verifyMandateExport } from 'fipsign-sdk'

const pq = new PQAuth(process.env.FIPSIGN_API_KEY)
const pinned = process.env.FIPSIGN_KEY_FINGERPRINTS.split(',')   // see Step 2
const { keys } = await pq.mandate.publicKeys()

// 1. Emit a mandate and make two calls on it: one granted, one denied.
//    Ask for a receipt on each.
const { mandate, receipt: emitted } = await pq.mandate.emit({
  agentId:          'agent-audit-demo',
  issuedBy:         'dev@example.com',
  scope:            ['sign'],
  budgetTotal:      10,
  expiresInSeconds: 3600,
  correlationId:    'demo-emit',
})
const granted = await pq.mandate.verify(mandate.token, 'sign', 1, {
  receipt: true,
  correlationId: 'demo-granted',
})
const denied = await pq.mandate.verify(mandate.token, 'delete', 1, {
  receipt: true,
  correlationId: 'demo-denied',
})
console.log('granted:', granted.result, '· denied:', denied.result, denied.reason)

// 2. Check the three receipts on this machine.
const options = { pinFingerprint: pinned, keys, expect: { mandateId: mandate.id } }
for (const r of [emitted, granted.receipt, denied.receipt]) {
  const c = await verifyMandateReceipt(r, options)
  const { seq, type } = r.event
  console.log(c.valid ? 'valid' : 'NOT valid', `event ${seq} ${type}`, c.problems)
}

// 3. A receipt in which one number was changed does not pass.
const forged = structuredClone(emitted)
const body = forged.event.body
forged.event.body = body.replace('"budgetTotal":10', '"budgetTotal":99')
const bad = await verifyMandateReceipt(forged, { pinFingerprint: pinned, keys })
console.log('forged receipt:', bad.valid ? 'valid' : 'NOT valid')

// 4. Revoke the mandate, then read its log.
await pq.mandate.revoke(mandate.id, { correlationId: 'demo-revoke' })
for await (const e of pq.mandate.eventsAll(mandate.id)) {
  console.log(e.seq, e.type, JSON.parse(e.body).correlationId)
}

// 5. Search by your own id. This search sees an event about 5 seconds later.
await new Promise((resolve) => setTimeout(resolve, 6000))
const found = await pq.mandate.queryEvents({ correlationId: 'demo-denied' })
const names = found.events.map((e) => `${e.type} (event ${e.seq})`)
console.log('found by correlationId:', names.join(', '))

// 6. Export the whole log and check it on this machine.
const pages = await pq.mandate.exportAll(mandate.id)
const audit = await verifyMandateExport(pages, { pinFingerprint: pinned })
console.log('export valid:', audit.valid, '· events:', audit.events)
if (!audit.valid) console.log(audit.problems)

granted: granted · denied: denied scope_not_authorized
valid event 1 emitted []
valid event 2 verify_granted []
valid event 3 verify_denied []
forged receipt: NOT valid
1 emitted demo-emit
2 verify_granted demo-granted
3 verify_denied demo-denied
4 revoked demo-revoke
found by correlationId: verify_denied (event 3)
export valid: true · events: 4

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. Token cost: see Costs.

result = pq.sign("user_123", email="user@example.com", 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. Token cost: see Costs.

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. Token cost: see Costs.

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 == "ana@example.com" 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(), verify_x509_cert() and verify_crl() 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)

        crl_check = pq.ca.verify_crl(crl, root_cert)  # no await either
        if not crl_check.valid:
            raise PermissionError(crl_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. Token cost: see Costs.

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. Token cost of each method: see Costs.

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'}")

# result.raw is the whole list as the CA signed it, for PQCert and X.509 CAs:
# {"caId", "subject", "format", "algorithm", "generatedAt", "revokedCerts", "signature"}
# ca.verify_crl() checks it (next step)
if result.raw:
    print(result.raw["signature"][:16] + "...")  # base64 ML-DSA signature

import time

result = pq.ca.get_crl()

# root_cert: the root certificate you saved when the CA was created
#   PQCert CA: a PQCert (PQCert.from_dict(json.load(f)) of root-cert.json) or the dict itself
#   X.509 CA:  the PEM string
check = pq.ca.verify_crl(result, root_cert)

if not check.valid:
    # check.error is plain text for your logs: decide with check.valid, do not compare the text
    # (the JS SDK words a few of these differently). It is one of:
    #   "Invalid list signature — not signed by this CA"
    #   "This list was not issued by this CA"
    #   "This list is from a PQCert CA: pass its CA_ROOT certificate (a PQCert, or the dict of its JSON)"
    #   "This list is from an X.509 CA: pass its root certificate in PEM form (a string)"
    #   "The entries of this result (crl, caId, subject, generatedAt) are not the signed ones (raw)"
    #   "This list is not signed: ..."
    #   "The root certificate could not be read: pass the PEM of the CA root certificate"
    #   "Unsupported root CA algorithm: <OID>. Expected ML-DSA-65 (2.16.840.1.101.3.4.3.18)"
    raise PermissionError("Revocation list not trusted: " + check.error)

# check.generatedAt is when the CA signed the list (Unix seconds). A correctly signed old list is still
# valid: you decide how old a list you accept.
age_seconds = time.time() - check.generatedAt
if age_seconds > 15 * 60:
    raise PermissionError("Revocation list is too old: download it again")

# Now the entries can be trusted
if pq.ca.is_cert_revoked(device_cert, result.crl):
    raise PermissionError("Device certificate has been revoked")

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. Revocation: download the CRL every few minutes, check its signature and keep it (not on every check)
crl_result = pq.ca.get_crl()
check = pq.ca.verify_crl(crl_result, root_cert)
if not check.valid:
    raise PermissionError(check.error)
# At runtime: look the device up in the list you kept
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. Revocation: download the CRL every few minutes, check its signature and keep it (not on every check)
crl_result = pq.ca.get_crl()
check = pq.ca.verify_crl(crl_result, root_pem)
if not check.valid:
    raise PermissionError(check.error)
# At runtime: look the device up in the list you kept
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(), events_all() and query_events_all(), which are async generators (async for). Token cost of each method: see Costs.

result = pq.mandate.emit(
    agent_id="agent-reporting-v2",
    issued_by="user@empresa.com",
    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. It also carries a receipt, FIPSign's signature over the emitted event: see Receipts and the audit log below.

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)
    # check.failure: "rejected" | "rate_limited" | "quota_exhausted" | "unavailable" | "outcome_unknown" — table below
    raise PermissionError(check.reason)
# granted — check.budgetRemaining and check.expiresInSeconds are also present
do_the_action()

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

if check.result != "granted":
    if check.failure == "outcome_unknown":
        # No usable answer: the call may have been granted and charged. Do NOT act yet.
        # Without proof of possession: read the budget and compare it with the value you had before the call.
        now = pq.mandate.get(mandate_id).mandate  # needs your full-access key
        print("budgetConsumed is now", now.budgetConsumed)
        raise RuntimeError("outcome unknown: do not act yet")
    if check.failure == "rate_limited":
        raise RuntimeError(f"rate limited: try again in {check.retry_after} s")
    raise PermissionError(check.reason)
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="user@empresa.com",
    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. Token cost: the emit and the one granted verify (see Costs); 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="dev@example.com",
    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.
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(): ...

FIPSign records everything that happens to a mandate — it was emitted, each call it granted or denied, each change — in a log, and signs it. There is nothing to switch on. With the SDK you ask for a receipt on the calls you may have to prove, keep it, and check it on your own machine; later you can read the log and export it. Receipts, reading the log and the export cost no tokens (Costs). What the log holds, how it is protected and what a receipt does and does not prove: Mandate 11 to 15. The steps below follow one another: each one uses what the one before it made, and the complete example at the end runs all of them.

# emit(): the answer has the receipt next to the mandate
result = pq.mandate.emit(
    agent_id="agent-reporting-v2",
    issued_by="user@empresa.com",
    scope=["sign", "verify", "read:crm"],
    budget_total=1000,
    expires_in_seconds=28800,
    correlation_id="ticket-4821",   # your own id for this call
)
mandate, emitted = result.mandate, result.receipt

# verify(): a receipt only if you ask for it, granted or denied
check = pq.mandate.verify(
    mandate.token, "read:crm", 1, receipt=True, correlation_id="req-77"
)
print(check.result, check.receipt.event.seq)   # granted 2  (1 is the emit)

# narrow(), suspend(), resume() and revoke(): always a receipt
revoked = pq.mandate.revoke(mandate.id, correlation_id="ticket-4822").receipt
print(revoked.event.type)   # revoked

Keep the receipt next to your own record of the call, as JSON:

import json

with open("receipt-emit.json", "w") as f:
    json.dump(emitted.to_dict(), f)

The fingerprint is the SHA-256 of the public key of your project, 64 hexadecimal characters. It tells you which key to trust. Run this once, the day you integrate:

import os
from fipsign import PQAuth, public_key_fingerprint

pq = PQAuth(os.environ["FIPSIGN_API_KEY"])
current = next(k for k in pq.mandate.public_keys().keys if k.status == "current")
print(public_key_fingerprint(current.publicKey))
# Prints: <64 hexadecimal characters>

from fipsign import verify_mandate_receipt

# The fingerprints you saved, separated by commas (one for each key you had)
pinned = os.environ["FIPSIGN_KEY_FINGERPRINTS"].split(",")
keys = pq.mandate.public_keys().keys   # free; includes retired keys

result = verify_mandate_receipt(
    emitted,
    pin_fingerprint=pinned,
    keys=keys,
    expect_mandate_id=mandate.id,   # fails if the receipt is of another mandate
)
if result.valid:
    ev = result.event
    print(f"valid: event {ev.seq} ({ev.type}) of {result.mandateId}, at {ev.at}")
else:
    print("NOT valid:", result.problems)
# Prints: valid: event 1 (emitted) of mdt_…, at 1785690939

import json

# Every event of one mandate, oldest first (the pages are fetched for you)
for e in pq.mandate.events_all(mandate.id):
    print(e.seq, e.type, json.loads(e.body).get("correlationId"))

# Search the events of all your mandates, newest first
page = pq.mandate.query_events(correlation_id="req-77")
for e in page.events:
    print(e.mandateId, e.seq, e.type)

# Every denied call of the last 7 days, page by page
for e in pq.mandate.query_events_all(type="verify_denied"):
    print(e.mandateId, e.at, json.loads(e.body)["reason"])
# Prints:
#   1 emitted ticket-4821
#   2 verify_granted req-77
#   3 revoked ticket-4822
#   mdt_… 2 verify_granted
#   mdt_… 1785691402 scope_not_authorized     (one line for each denied call)

import json
from fipsign import verify_mandate_export

pages = pq.mandate.export_all(mandate.id)   # every page, in order
with open("export.json", "w") as f:
    json.dump([p.to_dict() for p in pages], f)   # keep it

# Now, or years later, with no network and no API key:
with open("export.json") as f:
    saved = json.load(f)
audit = verify_mandate_export(saved, pin_fingerprint=pinned)
print(audit.valid, audit.complete, audit.events, audit.problems)
# Prints: True False 3 []     (valid, complete, events, problems)

Change one number of a receipt and the check says so. Run it after Step 3, with the same pinned and keys:

import copy

# Change one number of a receipt: it no longer passes
forged = copy.deepcopy(emitted.to_dict())
body = forged["event"]["body"]
forged["event"]["body"] = body.replace('"budgetTotal":1000', '"budgetTotal":9999')
bad = verify_mandate_receipt(forged, pin_fingerprint=pinned, keys=keys)
print(bad.valid, bad.problems)
# Prints: False ['event 1: hash is not sha256(prevHash + "\\n" + body)']

Emits a mandate, makes one granted and one denied call, checks the three receipts, shows that a changed receipt fails, revokes the mandate, reads its log, finds an event by your own id and checks the export. Save as audit_sdk_demo.py, run pip install fipsign-sdk, set FIPSIGN_API_KEY and FIPSIGN_KEY_FINGERPRINTS (the fingerprint you saved in Step 2) and run python audit_sdk_demo.py. Token cost: the emit and the one granted verify (see Costs); the denied call, the receipts, the reads and the checks are free.

# audit_sdk_demo.py — receipts, the log and the export with the SDK, end to end.
# Setup: pip install fipsign-sdk
# Run:   export FIPSIGN_API_KEY=pqa_...
#        export FIPSIGN_KEY_FINGERPRINTS=<64 hexadecimal characters>
#        python audit_sdk_demo.py
import copy
import json
import os
import time

from fipsign import PQAuth, verify_mandate_export, verify_mandate_receipt

pq = PQAuth(os.environ["FIPSIGN_API_KEY"])
pinned = os.environ["FIPSIGN_KEY_FINGERPRINTS"].split(",")   # see Step 2
keys = pq.mandate.public_keys().keys

# 1. Emit a mandate and make two calls on it: one granted, one denied.
#    Ask for a receipt on each.
result = pq.mandate.emit(
    agent_id="agent-audit-demo",
    issued_by="dev@example.com",
    scope=["sign"],
    budget_total=10,
    expires_in_seconds=3600,
    correlation_id="demo-emit",
)
mandate, emitted = result.mandate, result.receipt
granted = pq.mandate.verify(
    mandate.token, "sign", 1, receipt=True, correlation_id="demo-granted"
)
denied = pq.mandate.verify(
    mandate.token, "delete", 1, receipt=True, correlation_id="demo-denied"
)
print("granted:", granted.result, "· denied:", denied.result, denied.reason)

# 2. Check the three receipts on this machine.
for r in [emitted, granted.receipt, denied.receipt]:
    c = verify_mandate_receipt(
        r, pin_fingerprint=pinned, keys=keys, expect_mandate_id=mandate.id
    )
    seq, kind = r.event.seq, r.event.type
    print("valid" if c.valid else "NOT valid", f"event {seq} {kind}", c.problems)

# 3. A receipt in which one number was changed does not pass.
forged = copy.deepcopy(emitted.to_dict())
body = forged["event"]["body"]
forged["event"]["body"] = body.replace('"budgetTotal":10', '"budgetTotal":99')
bad = verify_mandate_receipt(forged, pin_fingerprint=pinned, keys=keys)
print("forged receipt:", "valid" if bad.valid else "NOT valid")

# 4. Revoke the mandate, then read its log.
pq.mandate.revoke(mandate.id, correlation_id="demo-revoke")
for e in pq.mandate.events_all(mandate.id):
    print(e.seq, e.type, json.loads(e.body).get("correlationId"))

# 5. Search by your own id. This search sees an event about 5 seconds later.
time.sleep(6)
found = pq.mandate.query_events(correlation_id="demo-denied")
names = [f"{e.type} (event {e.seq})" for e in found.events]
print("found by correlationId:", ", ".join(names))

# 6. Export the whole log and check it on this machine.
pages = pq.mandate.export_all(mandate.id)
audit = verify_mandate_export(pages, pin_fingerprint=pinned)
print("export valid:", audit.valid, "· events:", audit.events)
if not audit.valid:
    print(audit.problems)

granted: granted · denied: denied scope_not_authorized
valid event 1 emitted []
valid event 2 verify_granted []
valid event 3 verify_denied []
forged receipt: NOT valid
1 emitted demo-emit
2 verify_granted demo-granted
3 verify_denied demo-denied
4 revoked demo-revoke
found by correlationId: verify_denied (event 3)
export valid: True · events: 4

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

Each tool costs what the operation it calls costs: see Costs.

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. Token cost: see Costs.

curl -s $BASE_URL/health | jq

Requires X-API-Key. Token cost: see Costs. 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. Token cost: see Costs.

curl -s -X POST $BASE_URL/sign \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{"sub":"user_123","email":"user@example.com","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":"test@example.com"}' \
  | 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. Use it when plaintext must not leave your infrastructure. A ZES token is a regular token: it lives at most 24 hours (1 hour by default), so use it to check that data did not change between two of your services, not to keep a record for later. Token cost: see Costs.

# 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=(',', ':'), ensure_ascii=False)
zes_hash    = hashlib.sha256(sorted_json.encode('utf-8')).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('utf-8')).hexdigest()
matches = v['payload']['sub'] == f'zes:{rehash}'
print(f'valid: {v["valid"]}, data matches token: {matches}')  # True, True

Requires X-API-Key. Token cost: see Costs. 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. Token cost: see Costs. 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. Token cost: see Costs. 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. Token cost of each endpoint: see Costs.

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. Token cost of each endpoint: see Costs.

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

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, meta}'

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().

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