Security Model

The sync endpoint is designed to be strict by default.

GitHub Actions OIDC is also supported and avoids long-lived private keys in GitHub workflows.

Signed Headers

The endpoint expects:

1X-VL-MD-DOCS-Key-Id2X-VL-MD-DOCS-Timestamp3X-VL-MD-DOCS-Nonce4X-VL-MD-DOCS-Body-SHA2565X-VL-MD-DOCS-Signature

Canonical String

The sender signs:

1v12POST3<endpoint pathname>4<timestamp>5<nonce>6<sha256(body)>

The CLI derives the endpoint pathname from the full endpoint URL.

Server-Owned Controls

The manifest cannot choose:

• target collection
• target field names
• route base
• publish authority
• hard delete authority
• allowed docs set slugs
• source-specific auth allowlists

Payload Admin docs sets own slugs, branches, and advanced workflow refs. Global Keys and Trusted records own reusable authentication trust. Plugin config owns collection setup and lifecycle gates such as write, publish, and hard-delete authority.

Replay Protection

Accepted nonces are stored in the docs-sync-nonces collection. A repeated nonce for the same key id is rejected while it is still valid.

Common Rejections

See troubleshooting for invalid_signature, body_hash_mismatch, nonce_replay, source_not_allowed, publish_disabled, and other endpoint errors.