Fetching a WIT-SVID

note

WIT-SVID is a preview feature, off by default and enabled per organization. See the WIT-SVID overview for details.

Your workload calls the standard SPIFFE Workload API over the Agent's Unix socket. Enabling WIT-SVID issuance adds two streaming RPCs:

• FetchWITSVID streams WITSVIDResponse messages. Each response carries a repeated svids field, one entry per identity the workload is entitled to. Each entry has spiffe_id, wit_svid (the compact JWS), wit_svid_key (the PoP private key as a JWK), and an optional hint. The stream re-pushes fresh WIT-SVIDs before they expire.
• FetchWITBundles streams WITBundlesResponse messages. Each response carries a bundles map keyed by the trust domain's SPIFFE ID, whose values are the JWK-encoded WIT bundles used to verify WIT-SVIDs you receive from peers.

Your application is responsible for presenting the WIT-SVID and proving possession of the private key to a verifier, and for verifying WIT-SVIDs from inbound connections.

Do not treat a WIT-SVID as a bearer token

Never send a WIT-SVID on its own as a bearer credential, such as in an Authorization header, the way you would a JWT-SVID. A WIT-SVID that is merely presented, without a proof of possession bound to the request, gives an attacker who captures it the same access as the workload. Every presentation must carry a proof of possession (a signature made with the PoP private key) that is bound to the specific request, so a captured token cannot be replayed.

Testing with spirldbg

Use the spirldbg CLI to fetch a WIT-SVID and its trust bundle for testing.

Fetch a WIT-SVID:

spirldbg svid-wit

svid-wit takes no SPIFFE ID argument. The server selects the WIT-SVID by template.

Flag	Description
--show-private-key	Include the bound proof-of-possession private key (PKCS#8 PEM) in the output.
--raw	Output the raw compact WIT token only. Cannot be combined with --json.
--filename	Write the token to a file. With --show-private-key, the private key is written to a sibling file.
--json	Emit JSON instead of the default text output.
--max-retry-duration	Maximum retry interval for fetching. Defaults to 30s. Set to 0 to disable retries.
--spiffe-endpoint-socket	Path to the Workload API Unix socket.

Output contains a private key

--show-private-key prints the proof-of-possession private key to standard output, and --filename combined with --show-private-key writes it to a file. Anyone who obtains that key can impersonate the workload. Do not paste this output into shared or CI logs, and do not check generated key files into version control. Protect any key file you create and delete it once you finish testing.

Fetch the WIT trust bundle:

spirldbg trust-bundle-wit --trust-domain example.org

Flag	Description
--trust-domain	The trust domain to fetch the bundle for. Required when more than one is available.
--filename	Write the bundle to a file.
--json	Emit JSON instead of the default text output.
--spiffe-endpoint-socket	Path to the Workload API Unix socket.

Frequently asked questions

Do I have to switch from JWT-SVIDs?

No. WIT-SVID is additive. X.509-SVIDs and JWT-SVIDs can be issued and retrieved while WIT-SVID issuance is enabled.

Why is there no audience (aud)?

The WIT spec prohibits it. A WIT-SVID is scoped by proof-of-possession, not by audience. If your use case needs audience restriction, JWT-SVID remains the right choice.

What happens to the private key on rotation?

The Agent re-issues WIT-SVIDs before they expire and pushes them down the open stream. Workloads must read both wit_svid and wit_svid_key from each stream update rather than caching the key indefinitely.

Is validating a WIT-SVID enough to trust the caller?

No. A valid WIT-SVID only proves the token is authentic and unexpired. It does not prove that the caller holds the proof-of-possession private key. Never accept a WIT-SVID as a bearer token: A verifier must also require a proof of possession that is bound to the request. Proving possession is a separate step: The presenter signs a challenge with the PoP private key, and the verifier checks that signature against the public key in the token's cnf claim (RFC 7800).

Defakto issues the WIT-SVID and the PoP private key. It does not define the protocol your application uses to present the token and prove possession. Choosing and implementing that protocol is your application's responsibility.