Learn that a SPIFFE Verifiable Identity Document (SVID) is the cryptographic proof of a workload's SPIFFE ID (a URI of the form spiffe://<trust-domain>/<path>)
Understand X.509-SVIDs: a short-lived TLS certificate where the SPIFFE ID is encoded in the certificate's SAN URI field; used for mTLS connections where both parties present certificates
Understand JWT-SVIDs: a short-lived signed JWT with the sub claim set to the SPIFFE ID; used for HTTP API calls or contexts where TLS certificate presentation is not possible
Choose X.509-SVIDs for service-to-service mTLS as they integrate with standard TLS stacks and require no custom HTTP header handling
Choose JWT-SVIDs for cases where only application-layer identity is needed (e.g., an HTTP API call through a proxy that terminates TLS) or when the consumer validates a bearer token
Both SVID types are delivered by the SPIFFE Workload API (a local Unix domain socket) and have short TTLs; workloads must refresh them automatically before expiry
Known gotchas
JWT-SVIDs have an audience (aud) claim that must match the intended recipient; do not accept a JWT-SVID without validating the audience, as it could be a token issued for a different service
X.509-SVIDs must be rotated before expiry; failing to renew results in TLS handshake failures — implement the SPIFFE Workload API watcher pattern for automatic renewal
The SPIFFE ID in an SVID encodes trust domain; cross-trust-domain authentication requires explicit federation configuration and bundle exchange, not just presenting any SVID
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp