SPIFFE / SVID Workload Identity

SPIFFE (Secure Production Identity Framework For Everyone) gives each service a cryptographic identity via X.509 SVIDs. Buttrbase acts as a SPIFFE-compatible CA per org.

Authentication

Management endpoints require Authorization: Bearer <jwt> (admin scope). Trust bundle and CRL are public.

Endpoints

GET /orgs/:org_uuid/.well-known/ca.pem

Download the org root CA cert. Public, no auth required.

GET /api/auth/spiffe/trust-bundle

SPIFFE trust bundle as JSON. Auth required.

Output: ~~~json { "trust_domain": "org.spiffe.buttrbase.com", "x509_authorities": [{ "asn1": "base64-der..." }] } ~~~

POST /api/auth/spiffe/svid

Issue a new X.509 SVID. private_key_pem is shown once.

Input: ~~~json { "service_identity_id": "identity-uuid", "ttl_hours": 24, "san_uris": ["spiffe://org/service/payments"] } ~~~

Output: ~~~json { "svid_id": "svid-uuid", "certificate_pem": "-----BEGIN CERTIFICATE----- ...", "private_key_pem": "-----BEGIN EC PRIVATE KEY----- ...", "expires_at": "2026-05-12T10:00:00Z" } ~~~

GET /api/auth/spiffe/svid/:svid_id

Get SVID metadata (no private key). Response includes svid_id, sans, expires_at, revoked.

DELETE /api/auth/spiffe/svid/:svid_id

Revoke SVID immediately — added to CRL. Returns 204.

GET /api/auth/spiffe/crl

Download Certificate Revocation List as PEM. Public, no auth.

Error Reference

| Status | Code | Meaning | |---|---|---| | 400 | invalid_san_scheme | SAN URI must use spiffe:// scheme | | 403 | forbidden | Admin scope required | | 404 | not_found | SVID or identity does not exist | | 409 | already_revoked | SVID already revoked | | 422 | ttl_exceeds_max | Requested TTL exceeds org CA maximum |

Example

~~~bash curl -X POST -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{"service_identity_id":"id","ttl_hours":24,"san_uris":["spiffe://org/svc/pay"]}' \ https://api.buttrbase.com/api/auth/spiffe/svid ~~~