Security architecture

GeckoGuard treats authorization as a signed exchange rather than trusting TLS alone. Official SDKs send a timestamp and unique nonce with an HMAC-SHA256 request signature. The API rejects stale timestamps and remembers nonces so a captured request cannot be replayed inside the acceptance window.

Official SDKs send a response nonce to request Ed25519 signature v2. The signed message binds the version marker, timestamp, uppercase HTTP method, request path (without its query string), SHA-256 hash of the exact response body bytes, and response nonce. The HTTP status and key ID are not fields in that signed message; the key ID selects the verification key. Official SDKs pin the production public key and fail closed on a missing signature, an unknown key, a changed body, a mismatched nonce, or a downgrade attempt.

For legacy compatibility, requests without a valid response nonce receive signature v1. Official SDKs require v2 for their nonce-challenged requests and do not fall back to v1.

Key rotation

Responses name their signing key with a kid. A release can carry both the active and next public key during a bounded overlap. The server then moves signing to the next private key, and the retired public key is removed only after supported clients have updated. Remote key discovery is disabled by default for the official production host, so a compromised API origin cannot silently replace the trust anchor.

Tenant and secret boundaries

  • Organization and product authorization is checked server-side on every dashboard operation.
  • API keys are stored as peppered HMAC hashes. Their per-key request-signing secrets are returned only when created or rotated.
  • Webhook secrets are encrypted at rest and webhook destinations pass SSRF and redirect checks.
  • Passwords use bcrypt; imported KeyAuth users receive no reusable password and must establish a GeckoGuard credential.
  • Audit records form a tamper-evident HMAC chain and sensitive tokens are redacted from responses and logs.

What customers should do

Keep API keys and signing secrets out of source control, do not disable response verification, use the least permissions required, rotate credentials after suspected exposure, and run a heartbeat for software that needs prompt revocation. Custom API hosts must supply their own pinned Ed25519 public keys.

See the SDK-specific setup under SDKs and the live measurements on System status.