Reference

SDK Reference

QuickStartSVID

from AuthSec_SDK import QuickStartSVID

svid = await QuickStartSVID.initialize(socket_path="/run/spire/sockets/agent.sock")

Method / Property	Description
await .initialize(socket_path)	Connect to agent, fetch SVID, start auto-renewal
await .validate_jwt_svid(token, audience)	Validate a JWT-SVID. Returns {"spiffe_id": ..., "claims": {...}} or None
await .fetch_jwt_svid(audience)	Fetch a JWT-SVID for calling other services. Returns token string
.create_ssl_context_for_server()	SSL context for mTLS server (requires client certs)
.create_ssl_context_for_client()	SSL context for mTLS client (presents your SVID)
.spiffe_id	Your SPIFFE ID string
.cert_file_path	Path to cert file (auto-updated on renewal)
.key_file_path	Path to private key file
.ca_file_path	Path to CA bundle file

---

Certificate Rotation

Handled automatically — no restarts needed.

• Agent rotates its own SVID when 66% of TTL has elapsed
• Workload SVIDs are pushed to connected workloads via the gRPC stream
• SDK writes updated certs to disk atomically (/tmp/spiffe-certs/)
• Private keys are generated locally and never leave the host

t=0min   SVID issued (1h TTL)
t=40min  Rotation triggered (66% elapsed)
t=40min  New SVID pushed to workload via gRPC, cert files updated
t=60min  Old SVID expires (already replaced)

---

Selector Reference

Selectors on a workload entry must all match (AND logic) for a workload to receive an SVID.

Kubernetes

Selector	Example	Description
k8s:ns	production	Pod namespace
k8s:sa	order-service	Service account name
k8s:pod-label:app	order-service	Pod label
k8s:pod-owner-Deployment	order-service	Owner reference
k8s:pod-image	myregistry/order:v1	Container image

Most common pattern:

k8s:ns = production
k8s:sa = order-service

Docker

Selector	Example	Description
docker:label:app	my-ai-agent	Container label
docker:label:env	production	Any container label
docker:image_id	sha256:abc123...	Image digest
docker:container_name	my-ai-agent	Container name

Most common pattern:

docker:label:app = my-ai-agent
docker:label:env = production

Unix (VM / Bare Metal)

Selector	Example	Description
unix:uid	1000	Process user ID
unix:gid	1000	Process group ID
unix:path	/opt/my-agent/venv/bin/python	Executable path
unix:sha256	a1b2c3...	Executable SHA-256 hash

Most common pattern:

unix:uid = 1000
unix:path = /opt/my-agent/venv/bin/python