openapi: 3.1.0 info: title: SPIFFE Federation Bundle Endpoint API description: >- The SPIFFE Federation Bundle Endpoint is an HTTP REST API that SPIFFE implementations expose to allow foreign trust domains to retrieve the current trust bundle (set of root CA certificates) for the serving trust domain. Trust bundles are used to validate X.509-SVIDs and JWT-SVIDs issued by a trust domain. The endpoint follows the SPIFFE Trust Domain and Bundle specification and returns a JSON document containing the JWKS (JSON Web Key Set) representation of the trust bundle's root CAs, enabling automated cross-domain trust establishment and rotation without manual certificate distribution. version: '1.0' contact: name: SPIFFE Community url: https://spiffe.io/community/ termsOfService: https://github.com/spiffe/spiffe/blob/main/LICENSE externalDocs: description: SPIFFE Trust Domain and Bundle Specification url: https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Trust_Domain_and_Bundle.md servers: - url: https://{trust-domain} description: SPIFFE Trust Domain Bundle Endpoint Server variables: trust-domain: default: example.org description: >- The DNS name of the trust domain serving the bundle endpoint. The trust domain name is used as the server hostname. tags: - name: Bundle description: >- SPIFFE trust bundle retrieval operations for fetching root CA certificates used to validate SVIDs issued by a trust domain paths: /spiffe/v1/bundle: get: operationId: getTrustBundle summary: SPIFFE Get trust bundle description: >- Returns the current trust bundle for this SPIFFE trust domain as a JWKS (JSON Web Key Set) document. The trust bundle contains the root CA certificates that are used to validate X.509-SVIDs and JWT-SVIDs issued by this trust domain. Foreign SPIFFE implementations poll this endpoint to stay synchronized with trust bundle updates, enabling cross-domain workload authentication. The response is a standard JWKS document where each key entry represents a root CA certificate encoded as an X.509 certificate in the x5c claim. tags: - Bundle parameters: - name: Accept in: header description: >- Requested response format. The bundle endpoint must return application/json. Clients may include this header to indicate they accept JSON responses. schema: type: string default: application/json responses: '200': description: Trust bundle retrieved successfully headers: Content-Type: description: Always application/json for SPIFFE bundle endpoints schema: type: string enum: [application/json] content: application/json: schema: $ref: '#/components/schemas/TrustBundle' '404': description: Trust bundle not found or trust domain not configured content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TrustBundle: type: object description: >- A SPIFFE trust bundle encoded as a JWKS (JSON Web Key Set) document. The trust bundle contains the root CA certificates that validators use to authenticate X.509-SVIDs and JWT-SVIDs issued by this trust domain. The keys array contains one entry per root CA certificate in the trust bundle. required: - keys - spiffe_refresh_hint - spiffe_sequence properties: keys: type: array description: >- Array of JSON Web Key (JWK) entries representing root CA certificates in the trust bundle. Each entry corresponds to one root certificate authority that can be used to validate SVIDs from this trust domain. items: $ref: '#/components/schemas/JWK' spiffe_refresh_hint: type: integer description: >- Recommended polling interval in seconds for trust bundle consumers. Consumers should re-fetch the bundle at least this frequently to stay synchronized with trust bundle updates and certificate rotations. minimum: 0 spiffe_sequence: type: integer description: >- Monotonically increasing sequence number for the trust bundle. Consumers can use this to detect updates and avoid re-processing an unchanged bundle. The sequence number increments with each trust bundle update. minimum: 0 JWK: type: object description: >- A JSON Web Key representing a single root CA certificate in the SPIFFE trust bundle. For X.509 trust bundles the kty is EC or RSA and the x5c array contains the DER-encoded certificate chain. For JWT signing keys used in JWT-SVID validation, additional JWK fields are present. required: - kty - use - kid properties: kty: type: string description: Key type identifying the cryptographic algorithm family enum: [EC, RSA, OKP] use: type: string description: >- Intended use of the key. "x509-svid" for X.509 SVID validation keys and "jwt-svid" for JWT-SVID signing and validation keys. enum: [x509-svid, jwt-svid] kid: type: string description: >- Key identifier uniquely identifying this key within the trust bundle. Used to select the correct key when validating an SVID. crv: type: string description: Elliptic curve name for EC keys enum: [P-256, P-384, P-521] x: type: string description: X coordinate for EC keys encoded as base64url y: type: string description: Y coordinate for EC keys encoded as base64url n: type: string description: RSA modulus encoded as base64url for RSA keys e: type: string description: RSA public exponent encoded as base64url for RSA keys x5c: type: array description: >- X.509 certificate chain for this key. The first element is the certificate for the key itself, followed by any intermediate CA certificates. Each element is DER-encoded and base64-encoded (not base64url). items: type: string description: A DER-encoded X.509 certificate in base64 encoding Error: type: object description: Error response from the SPIFFE bundle endpoint properties: code: type: integer description: HTTP status code message: type: string description: Human-readable error message