SPIFFE Bundle API

openapi: 3.1.0
info:
  title: SPIFFE Federation Endpoint Bundle 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
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:
    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
    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
externalDocs:
  description: SPIFFE Trust Domain and Bundle Specification
  url: https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Trust_Domain_and_Bundle.md