Knogin
[Developers]

Signed API Requests (RFC 9421 HTTP Message Signatures)

When a service calls an administrative API endpoint, a captured bearer token alone allows unlimited replays and undetected tampering. A signed request binding the signature to the exact method, target URI, and request bo

Back to All Modules
Category: ModulesLast Updated: May 14, 2026
modulescomplianceblockchaingeospatial

Overview#

When a service calls an administrative API endpoint, a captured bearer token alone allows unlimited replays and undetected tampering. A signed request binding the signature to the exact method, target URI, and request body ensures that even if a token leaks, an attacker cannot replay it to a different endpoint or forge a request modification without the calling service's private key. RFC 9421 HTTP Message Signatures provide cryptographic non-repudiation for service-to-service calls, transforming one-time tokens into components of a multi-factor defence where the request content itself proves authenticity.

Developers and partners integrate signing keys, call the platform's signing library on the client side, and the platform verifies the Signature-Input and Signature headers on each admin request. Signatures use ed25519 by default for speed and determinism on constrained runtimes like Cloudflare Workers, with ECDSA P-256 as an alternative for HSM-backed identities. The verifier enforces a 60-second replay window, checks for nonce reuse across a 10-minute cache, and validates that every request covers the method, URI, authority, date, and a SHA-256 content digest.

Key Features#

  • Cryptographic Request Authentication: Signatures cryptographically bind to the exact HTTP method, target URI, and request body, so a captured token cannot be replayed to a different endpoint or modified without detection.

  • Algorithm Flexibility: Supports ed25519 (default, optimised for constrained runtimes and Cloudflare Workers) and ECDSA P-256 (for HSM and smartcard identities), with explicit rejection of weaker RSA and HMAC algorithms.

  • Mandatory Signed Components: Every signature must cover the HTTP method, target URI, authority header, date, and a SHA-256 content digest, ensuring comprehensive coverage of request semantics.

  • Anti-Replay Defence: Enforces a configurable created-timestamp window (default ±60 seconds) to reject old or future-dated requests, combined with a 10-minute sliding nonce cache to detect and reject duplicate calls from the same service identity.

  • Service Identity Registry: Public keys are registered per service identity (e.g. a registered service identity) in environment variables, JSON configuration files, or a database table, enabling audit history and revocation tracking.

  • Nonce Store Abstraction: In-memory nonce cache for testing and a pluggable distributed nonce store for production, with fail-closed semantics so unavailable caches do not silently degrade security on high-value admin paths.

  • Standards Alignment: Fully compliant with RFC 9421, RFC 9530 (Content-Digest), and OWASP ASVS 5.0 Level 3 requirements for API and web service authentication on admin calls.

  • Layered Defence: Operates on top of existing bearer-token authentication, adding a second cryptographic factor so compromised tokens alone are insufficient for admin mutations.

  • Audit Trail: Signature verification failures are logged with distinct error codes (malformed input, unknown keyid, signature mismatch, nonce replay, etc.) for security operations and compliance investigations.

Use Cases#

  • Inter-Service Admin Calls: Microservices calling shared authentication or permission-management endpoints cryptographically prove their identity using service-specific signing keys, preventing token interception from opening high-value API surfaces.

  • Partner Integration Security: External partners integrating with the platform's provisioning APIs sign each request with their registered service key, ensuring that downstream systems cannot forge requests as trusted partners even if API tokens are compromised.

  • Regulatory Compliance: Financial services and government agencies require non-repudiation on sensitive operations such as access grants, MFA resets, and role promotions. Signed requests create cryptographic proof of the caller's identity and intent, satisfying audit trail and attribution requirements.

  • High-Assurance Identity Orchestration: Organisations using HSM-backed identities (smartcards, hardware security modules) for top-tier administrators register ECDSA P-256 keys; the verifier accepts signatures from these higher-assurance credentials without degrading to symmetric or weaker algorithms.

  • Zero-Trust Infrastructure: Distributed systems and edge deployments (such as Cloudflare Workers) verify that admin requests originate from registered service identities, layering signature-based trust on top of mTLS or OAuth2 to eliminate credential-sharing dependencies.

Integration#

Developers configure a signing key registry (environment variables, JSON file, or database table) mapping service identities to ed25519 or ECDSA P-256 public keys. On the calling side, libraries or custom code read the HTTP method, URI, headers, and body, compute a SHA-256 content digest, construct the RFC 9421 signature base (a canonicalised line-separated list of signed components), sign with the service's private key, and inject the Signature-Input and Signature headers into the request.

The platform's verifier dependency integrates into FastAPI or compatible web frameworks. It extracts the signature headers, validates that all required components are signed, reconstructs the canonical base from the incoming request, retrieves the public key for the declared service identity, and verifies the ed25519 or ECDSA-P256 cryptographic signature. Nonce reuse is tracked in a configurable nonce store (in-memory for testing, a distributed cache for production) with a sliding 10-minute window. Timestamp validation rejects requests older than 60 seconds or with future-dated created timestamps, preventing replay of old signed requests even if a key is later compromised. Operators can roll out signatures incrementally using a soft-fail mode where verification is logged but not enforced, then switch to strict enforcement via a single environment flag.

Open Standards#

  • RFC 9421 (HTTP Message Signatures), IETF standard defining the canonical signature-base construction, component identifiers, algorithm identifiers, and Signature-Input / Signature header format that the platform implements for service-to-service admin-request authentication.
  • RFC 9530 (Digest Fields), IETF standard specifying the Content-Digest header and sha-256 digest algorithm used to bind the request body into every covered signature, preventing body-swap attacks.
  • RFC 8032 (EdDSA / Ed25519), IETF standard for the Edwards-Curve Digital Signature Algorithm; the platform defaults to Ed25519 for low-latency signing on constrained runtimes including Cloudflare Workers.
  • RFC 6979 / SEC 1 (ECDSA P-256), Deterministic ECDSA over NIST P-256, supported as an alternative algorithm for HSM-backed and smartcard service identities.
  • OWASP ASVS 5.0 Level 3 (V4.1.5), Application Security Verification Standard requirement for cryptographic request signing on admin and high-privilege API surfaces; the implementation is designed to satisfy Level 3 attestation.
  • NIST SP 800-186 (Elliptic Curve Cryptography), Normative guidance on approved elliptic-curve parameters; P-256 (secp256r1) is one of the explicitly approved curves, and no weaker RSA or HMAC algorithms are accepted.
  • OAuth 2.0 / JWT (RFC 6749 / RFC 7519), Bearer-token layer that signed requests operate on top of, adding a second cryptographic factor rather than replacing the existing identity and authorisation layer.

Security & Compliance#

  • Non-Repudiation: Service identities cannot deny having made a request because signatures are cryptographically bound to the request content and verified by the service's registered public key.

  • Replay Protection: Two-layer defence combines timestamp windows (±60 seconds) with a nonce cache enforcing uniqueness within a 10-minute window, preventing attackers from reusing a captured signed request.

  • Tampering Prevention: Any modification to method, URI, body, or covered headers invalidates the signature, so signed requests cannot be altered in flight without cryptographic verification failure.

  • ASVS V4.1.5 Level 3 Compliance: Implements RFC 9421-compliant signing and verification for API authentication on protected endpoints, satisfying OWASP Application Security Verification Standard Level 3 requirements for service-to-service communication.

  • Key Rotation Support: Service identities can be revoked (marked inactive) or rotated in the registry without forcing all calling services to update simultaneously; the verifier checks key status and rejects requests from revoked identities.

  • Tenant Isolation: Each service identity's signing key is isolated; one compromised key does not grant access to requests from other services.

  • Audit Logging: Verification failures (signature invalid, nonce replayed, algorithm mismatch, timestamp out of window, unknown keyid, etc.) are logged with distinct operator-facing error codes and structured details for compliance and security investigations.

Availability#

  • Enterprise Plan: Included
  • Professional Plan: Available as add-on

Last Reviewed: 2026-05-14 Last Updated: 2026-05-14

Ready to Build?

Get started with our APIs or contact our integration team for support.