Security and key management

Who this is for

Security, risk and architecture reviewers at a bank. This page covers who operates each control, how callers are authenticated and authorised, how transaction signing keys are held, how data is protected in transit and at rest, and how the software is built and maintained. It distinguishes application behaviour from deployment controls that need an approved configuration and assurance record. Controls that are not yet available are listed on Limitations.

Who operates each control

Application behaviour depends on the deployed release and configuration. Establish which party operates each control and retain its evidence; a public API declaration is not proof that the deployment enforces it. See Deployment model.

Confirm deployment/database isolation in the approved hosting design. Tenant-scoped business APIs use the organisation in the caller's token; shared catalogues and the user-by-ID lookup have different access rules. See Authentication.

Authentication and authorisation

• Protected requests carry a bearer token. People obtain tokens through POST /api/auth/login. Bank systems use the OAuth 2.0 client credentials grant with the identity provider. See Authentication.
• Tokens are validated before a request reaches the platform. The gateway checks the token's signature against the identity provider's published keys, and its issuer and expiry. A missing, expired or malformed token is rejected with 401.
• Revocation. User refresh-token revocation and machine-client credential revocation follow different flows. Existing JWTs can remain valid until expiry, while some endpoints also check current user status. Test existing-token access and new-token acquisition during removal; see Authentication.
• The organisation comes from the token. Tenant-scoped endpoints use this identity; any tenant ID in a path must match the authorised organisation. Check shared-resource and lookup exceptions in the reference.
• Permissions. Custom roles are built from a permission catalogue, and a caller may not grant a permission they do not hold. See Roles and access.
• Approvals. An approval task can be decided only by a caller listed among its approvers. The request initiator cannot approve their own request; either check fails with 403. Creating a manual request that names the caller as an approver is rejected with 400, before the request is stored. See Create an approval request, Approve a task and Policy, approvals and audit.
• Separate business and infrastructure administration. Customer APIs support team, role, policy and approval administration. Platform-only tenant creation and global template writes are excluded from this reference. Infrastructure and operator actions remain subject to the agreed privileged-access process; audit search does not guarantee an event for every API write.
• Confirm the multi-factor authentication and sign-in policy configured by your identity provider before granting Management Panel access.

Transaction signing and custody

Use the approved custody or HSM arrangement for production signing. The signing service documents custody and HSM provider paths; the customer API is not a private-key export or general key-management interface. Confirm the configured provider, key owner, on-chain authority and signing-policy controls before enabling value movements. Local test-signing configurations are not production custody assurances.

How a transaction is signed:

1. The platform prepares the unsigned transaction: the contract call, its parameters, nonce, gas and chain identifier.
2. It computes the transaction's digest and asks the custody service to sign that digest with the relevant key.
3. The custody service applies its own signing policy, held in the key owner's custody workspace and administered there. That policy can constrain the source account, the asset, the requesting user and the approvals required.
4. The custody service returns the signature. The platform assembles the signed transaction from the original prepared fields and the signature, and submits it.

Because the signature covers the digest of the exact transaction the platform prepared, changing any field afterwards invalidates it. A refusal by the custody service ends the operation in FAILED with failureCode: SIGNING_REJECTED.

The documented Fireblocks custody path verifies a detached callback signature against the configured provider key. Other providers have their own integration requirements. Confirm TLS termination, source restrictions, trusted callback keys and failure behaviour with the signing/security owner; do not assume every deployment has the same firewall rules.

The custody or HSM provider is selected by deployment configuration. Agree how it integrates with the bank's signing arrangement; the public API does not publish a universal supported-provider list. Webhook secrets and API access tokens are not blockchain signing keys.

Where transaction signing happens

%%{init: {"theme": "neutral"}}%%
sequenceDiagram
    participant Q as Quant Flow
    participant C as Custody or HSM provider
    participant N as Token network
    Q->>Q: Prepare transaction and digest
    Q->>C: Request digest signature
    C->>C: Apply custody signing policy
    alt Signing authorised
      C-->>Q: Signature
      Q->>Q: Assemble signed transaction
      Q->>N: Submit transaction
      N-->>Q: Settlement result
    else Signing refused
      C-->>Q: Refusal
      Q->>Q: FAILED / SIGNING_REJECTED
    end

Production signing keys stay within the approved custody or HSM boundary. An API bearer token or webhook secret has no blockchain signing authority.

Deploy contract · Submit token operation · Read outcome

Webhook signing

Deliveries to your endpoint are signed with HMAC_SHA256 over the delivery timestamp and the raw body. Each destination's secret is generated by the platform, returned once, encrypted with a dedicated key before it is stored, and decrypted only in memory when a delivery is signed. Rotation keeps the previous secret valid for an overlap window so that deliveries keep verifying while you deploy the new one. See Webhooks.

Obtain the trusted issuer and JWKS URL for your environment before using JWS_ES256. The notification documentation provides a staging key-set location but does not establish a production location or automatic key rotation.

Data protection

In transit. Use HTTPS for the customer gateway and webhook receiver. Agree the supported TLS versions, certificate ownership, internal encrypted connections and any private-link, VPN or allow-list arrangement in the deployment design. The API server URL does not establish those network controls.

At rest. Record encryption coverage for operational databases, volumes, stored secrets, backups and logs. Confirm key ownership, rotation, recovery and decommissioning responsibilities with the hosting owner. For client-hosted infrastructure, the bank operates these controls; Quant-hosted arrangements require deployment-specific evidence rather than an assumed customer-managed-key configuration.

Secrets. Use the agreed secret store and runtime delivery mechanism for identity, database, broker, custody and webhook credentials. Keep secrets out of source files, example code and ordinary logs. Verify workload identity, rotation and any remaining static credentials in the deployed environment.

Data held. Operational records include customers/accounts, contracts, instructions, policies and decisions, automations, webhook events and signing status. Distinguish off-chain records from fields stored by the selected token contract. Agree residency, retention, backup and secure retirement before go-live; the customer API is not a general database export.

Logging and audit

Use request/resource identifiers to correlate operational logs, activity events, approval records and ledger evidence. The public activity API supports organisation event search, detail reads and CSV export. It is not a complete export of internal audit databases.

Require redaction of credentials, bearer tokens, cookies and sensitive bodies in the deployed logging configuration. Verify which fields are masked, whether identifiers survive asynchronous work and how retention/access are enforced. An API schema does not demonstrate these logging controls. See Audit and evidence.

Application and API security

• Every request is validated before it is processed. Malformed input is rejected at the boundary.
• Writes whose endpoints support idempotency use a persisted original key for recovery. Other writes need resource-state reconciliation before retrying. See Idempotency and retries.
• Errors use one response shape and never include internal detail or stack traces. See Errors.
• PayScript code runs in a restricted sandbox. It forbids package declarations, closures and new method definitions, and permits only an explicit allowlist of method calls.
• Assess the exact deployed token-contract version and its permissions, freeze/lock behaviour, arithmetic and external-call paths. Request the matching test results, contract audit and any formal-verification scope from the contract owner. Documentation examples are not a smart-contract security assessment.

Secure development and supply chain

Obtain evidence for the installed release: source revision, review and branch controls, test results, dependency/container scans, SBOM and image provenance or signatures where supplied. Verify the approved image identity in your deployment process. Do not infer two-reviewer enforcement, continuous scanning or signed delivery from the API contract.

For a bank-built release, agree source access and build responsibilities separately. The bank owns evidence for its build pipeline and the artefacts it deploys.

Vulnerability management and incident response

Agree the secure reporting channel, incident owner, severity handling, patch policy and release/rollback procedure with Quant and your deployment team. Request current penetration-test evidence and its scope through the approved assurance process. No test cadence, remediation deadline or release frequency is established by the public API contract.

The API contract lists [email protected] as its general support address. Obtain the approved secure channel before sending credentials, sensitive payloads or vulnerability evidence. If a credential is compromised, coordinate access revocation and replacement with its owner, preserve incident evidence and test both retired-token access and replacement credentials. Webhook secrets and custody credentials are separate controls; rotate only the affected credentials under the agreed procedure.

Certifications

Request current certificates, assessment dates and applicable service/deployment scopes from the assurance owner. Establish which ISO/IEC, Cyber Essentials, CSA STAR, PCI DSS, SOC 2 or other evidence applies to your integration. This guide does not certify a deployment or confirm a planned accreditation; framework names alone do not establish coverage.

Keep an operational control record

For each environment, identify who owns gateway authentication, machine-client credentials, custody signing authority, webhook verification and evidence retention. Store references to approved configuration and change records rather than secrets. API roles, approval membership and on-chain authority must be verified separately.

Test credential cutover, access removal and signature verification using the deployed controls. Where service authentication enforcement is marked planned, obtain gateway/operator evidence instead of treating a declared bearer scheme as proof. Coordinate signing-key or custody changes with their owner; the customer API is not a general key-management interface. Use Access changes and offboarding and Production readiness.

Worked example

Rotate a webhook destination's secret. The response returns the new secret once. The previous secret keeps working until previousSecretExpiresAt, and every delivery carries both signatures until then.

POST /api/webhooks/9f2a1c44-6e3b-4f8a-9d21-7c5e0b8a4d13/secret/rotate HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0
Idempotency-Key: 2d6f0b7e-4c1a-4e9b-8f33-5a7c9e1d2b40

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "9f2a1c44-6e3b-4f8a-9d21-7c5e0b8a4d13",
  "secret": "4rT9wKpZ2xCvB8nM6qLsD1fG7hJ3yU5aE0oI4uYtRbN",
  "previousSecretExpiresAt": "2026-08-29 09:15:11.584"
}

Store the new secret in your secret store and deploy it before previousSecretExpiresAt. The timestamp is UTC in yyyy-MM-dd HH:mm:ss.SSS form.

View in API Reference

• Issue a new HMAC secret, keeping the previous one briefly valid · POST

Errors and edge cases

API Reference

Open an endpoint for request fields, response examples and the interactive API console.

Related pages

• Authentication
• Webhooks
• Roles and access
• Audit and evidence
• Deployment model
• Limitations