SPIFFE Workload API Events

asyncapi: 2.6.0
info:
  title: SPIFFE Workload API Events
  description: >-
    The SPIFFE Workload API is a gRPC streaming interface through which workloads
    request and receive SPIFFE Verifiable Identity Documents (SVIDs) and trust
    bundle updates. Workloads subscribe to the API and receive a continuous stream
    of identity updates as certificates are issued, rotated, and renewed. The API
    uses server-side streaming RPCs where the workload sends a single request and
    the SPIFFE implementation (such as SPIRE Agent) streams back identity updates
    for the lifetime of the connection. This AsyncAPI document describes the
    streaming event channels for X.509 SVID delivery, JWT SVID issuance, and
    trust bundle synchronization as exposed by SPIFFE Workload API implementors.
  version: '1.0'
  contact:
    name: SPIFFE Community
    url: https://spiffe.io/community/
externalDocs:
  description: SPIFFE Workload API Specification
  url: https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md
servers:
  spireAgent:
    url: 'unix:///tmp/spire-agent/public/api.sock'
    protocol: grpc
    description: >-
      SPIRE Agent Unix domain socket exposing the SPIFFE Workload API.
      Workloads connect to this socket to receive their SPIFFE identities.
      The socket path is configurable in the SPIRE Agent configuration.
channels:
  /spiffe.workload.SpiffeWorkloadAPI/FetchX509SVID:
    description: >-
      Streaming channel through which workloads receive X.509-SVID identity
      documents. After the workload sends a request, the server streams back
      an initial bundle of all SVIDs the workload is authorized to hold,
      followed by updated bundles whenever certificates are rotated or
      authorization changes. The stream remains open indefinitely and the
      workload should reconnect if the stream is interrupted.
    subscribe:
      operationId: fetchX509SVID
      summary: Stream X.509 SVID updates
      description: >-
        Subscribes to a stream of X.509 SVID updates from the SPIFFE
        implementation. The first message contains all current X.509-SVIDs
        the workload is authorized to hold. Subsequent messages are delivered
        whenever any SVID is rotated (typically before expiry) or when the
        workload's authorization changes. Each message in the stream is a
        complete replacement of the workload's current SVID set, not a delta.
      message:
        $ref: '#/components/messages/X509SVIDResponse'
  /spiffe.workload.SpiffeWorkloadAPI/FetchX509Bundles:
    description: >-
      Streaming channel for receiving the X.509 trust bundle set for all
      trust domains the workload needs to validate peer identities. This
      channel delivers the federation bundles from all configured federated
      trust domains in addition to the workload's own trust domain.
    subscribe:
      operationId: fetchX509Bundles
      summary: Stream X.509 trust bundle updates
      description: >-
        Subscribes to a stream of X.509 trust bundle updates. The stream
        delivers the complete set of trust bundles for the local trust domain
        and all federated trust domains. New messages are pushed whenever
        any trust bundle is updated, such as during CA rotation or federation
        bundle refresh events.
      message:
        $ref: '#/components/messages/X509BundlesResponse'
  /spiffe.workload.SpiffeWorkloadAPI/FetchJWTSVID:
    description: >-
      Request-response channel for fetching a JWT-SVID for a specific audience.
      Unlike X.509 streaming, JWT-SVIDs are issued on demand with a short TTL
      and should be fetched fresh for each use. The workload specifies the
      audience claim(s) and optionally a specific SPIFFE ID to obtain a JWT for.
    subscribe:
      operationId: fetchJWTSVID
      summary: Receive a JWT-SVID
      description: >-
        Returns a JWT-SVID for the requested audience claim(s). JWT-SVIDs are
        short-lived tokens (typically with a 5-minute TTL) and should be
        fetched immediately before use rather than cached. The SPIFFE
        implementation issues the JWT-SVID for each SPIFFE ID the workload
        is authorized to hold.
      message:
        $ref: '#/components/messages/JWTSVIDResponse'
  /spiffe.workload.SpiffeWorkloadAPI/FetchJWTBundles:
    description: >-
      Streaming channel for receiving JWT trust bundle updates. JWT bundles
      contain the public keys needed to validate JWT-SVIDs from all trust
      domains the workload is configured to federate with.
    subscribe:
      operationId: fetchJWTBundles
      summary: Stream JWT trust bundle updates
      description: >-
        Subscribes to a stream of JWT trust bundle updates containing the
        JWKS (JSON Web Key Sets) for all trust domains. New messages are
        pushed whenever a trust bundle is updated. Validators should use
        the bundle from this stream to verify incoming JWT-SVIDs rather
        than caching static keys.
      message:
        $ref: '#/components/messages/JWTBundlesResponse'
  /spiffe.workload.SpiffeWorkloadAPI/ValidateJWTSVID:
    description: >-
      Request-response channel for asking the SPIFFE implementation to validate
      a JWT-SVID on behalf of the workload. This allows workloads to delegate
      JWT validation to the SPIRE Agent rather than implementing it themselves.
    subscribe:
      operationId: validateJWTSVID
      summary: Receive JWT-SVID validation result
      description: >-
        Returns the validation result for a JWT-SVID token. The SPIFFE
        implementation verifies the token's signature using the appropriate
        trust bundle, checks the audience claim, and returns the SPIFFE ID
        of the validated identity along with any claims present in the token.
      message:
        $ref: '#/components/messages/ValidateJWTSVIDResponse'
components:
  messages:
    X509SVIDResponse:
      name: X509SVIDResponse
      title: X.509 SVID Response
      summary: A batch of X.509-SVIDs for the workload
      description: >-
        Contains all X.509-SVIDs the workload is currently authorized to hold,
        along with the trust bundles needed to validate peer identities. This
        message is delivered as the first response on a new FetchX509SVID stream
        and re-delivered whenever any SVID or bundle is updated.
      contentType: application/protobuf
      payload:
        $ref: '#/components/schemas/X509SVIDResponse'
    X509BundlesResponse:
      name: X509BundlesResponse
      title: X.509 Bundles Response
      summary: The complete set of X.509 trust bundles
      description: >-
        Contains the X.509 trust bundles for the local trust domain and all
        federated trust domains. Delivered when the subscription is established
        and re-delivered whenever any bundle is updated.
      contentType: application/protobuf
      payload:
        $ref: '#/components/schemas/X509BundlesResponse'
    JWTSVIDResponse:
      name: JWTSVIDResponse
      title: JWT-SVID Response
      summary: One or more JWT-SVIDs for the requested audience
      description: >-
        Contains JWT-SVIDs for all SPIFFE IDs the workload is authorized to
        hold, issued with the requested audience claim(s). Each JWT-SVID is
        a signed JSON Web Token containing the SPIFFE ID as the subject claim.
      contentType: application/protobuf
      payload:
        $ref: '#/components/schemas/JWTSVIDResponse'
    JWTBundlesResponse:
      name: JWTBundlesResponse
      title: JWT Bundles Response
      summary: JWT trust bundles for all trust domains
      description: >-
        Contains the JWT signing key sets (JWKS) for all trust domains the
        workload is configured to federate with. Used by validators to verify
        incoming JWT-SVIDs from workloads in other trust domains.
      contentType: application/protobuf
      payload:
        $ref: '#/components/schemas/JWTBundlesResponse'
    ValidateJWTSVIDResponse:
      name: ValidateJWTSVIDResponse
      title: Validate JWT-SVID Response
      summary: Result of JWT-SVID validation
      description: >-
        Contains the validated SPIFFE ID from the JWT-SVID and the full set
        of JWT claims. Returned when the token signature is valid, the
        audience matches, and the token has not expired.
      contentType: application/protobuf
      payload:
        $ref: '#/components/schemas/ValidateJWTSVIDResponse'
  schemas:
    X509SVID:
      type: object
      description: >-
        An X.509-SVID (SPIFFE Verifiable Identity Document) consisting of an
        X.509 certificate chain with the SPIFFE ID encoded in the Subject
        Alternative Name URI field, and the corresponding private key.
      required:
        - spiffe_id
        - x509_svid
        - x509_svid_key
        - bundle
      properties:
        spiffe_id:
          type: string
          description: >-
            The SPIFFE ID encoded in the certificate's Subject Alternative Name
            URI field. Format: spiffe://{trust-domain}/{path}
          pattern: '^spiffe://[^/]+/.+'
        x509_svid:
          type: string
          description: >-
            The DER-encoded X.509 certificate chain for this SVID. The first
            certificate in the chain is the leaf (end-entity) certificate
            containing the SPIFFE ID. Encoded as base64.
          contentEncoding: base64
        x509_svid_key:
          type: string
          description: >-
            The DER-encoded private key corresponding to the leaf certificate
            in x509_svid. Encoded as base64. The workload must keep this
            key secret.
          contentEncoding: base64
        bundle:
          type: string
          description: >-
            The DER-encoded X.509 trust bundle for the trust domain indicated
            by the SPIFFE ID. Used to validate peer X.509-SVIDs from the same
            trust domain. Encoded as base64.
          contentEncoding: base64
        hint:
          type: string
          description: >-
            Optional workload hint provided by the SPIFFE implementation to
            help workloads select among multiple SVIDs when they are authorized
            to hold more than one identity.
    X509SVIDResponse:
      type: object
      description: >-
        Streamed response from the FetchX509SVID RPC containing all X.509-SVIDs
        the workload is authorized to hold. Workloads should replace their
        entire current SVID set when receiving this message.
      required:
        - svids
      properties:
        svids:
          type: array
          description: >-
            Complete list of X.509-SVIDs the workload is currently authorized
            to hold. Replace the workload's entire SVID set with this list.
          items:
            $ref: '#/components/schemas/X509SVID'
        federated_bundles:
          type: object
          description: >-
            Map from trust domain name to DER-encoded X.509 bundle for each
            federated trust domain. Used to validate X.509-SVIDs from workloads
            in foreign trust domains.
          additionalProperties:
            type: string
            description: DER-encoded trust bundle encoded as base64
            contentEncoding: base64
    X509BundlesResponse:
      type: object
      description: >-
        Streamed response from the FetchX509Bundles RPC containing X.509 trust
        bundles for all trust domains.
      required:
        - bundles
      properties:
        bundles:
          type: object
          description: >-
            Map from trust domain name to DER-encoded X.509 bundle. Includes
            the local trust domain and all federated trust domains.
          additionalProperties:
            type: string
            description: DER-encoded trust bundle encoded as base64
            contentEncoding: base64
    JWTSVID:
      type: object
      description: >-
        A JWT-SVID (SPIFFE Verifiable Identity Document) encoded as a signed
        JSON Web Token. The SPIFFE ID is the subject ("sub") claim and the
        audience is specified in the "aud" claim.
      required:
        - token
        - spiffe_id
      properties:
        token:
          type: string
          description: >-
            The signed JWT-SVID token. A base64url-encoded JWT with three
            dot-separated parts: header, payload, and signature.
          pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$'
        spiffe_id:
          type: string
          description: The SPIFFE ID encoded in the token's subject claim
          pattern: '^spiffe://[^/]+/.+'
        expiry_time:
          type: integer
          description: Unix timestamp (seconds since epoch) when this JWT-SVID expires
    JWTSVIDResponse:
      type: object
      description: Response from the FetchJWTSVID RPC containing JWT-SVIDs
      required:
        - svids
      properties:
        svids:
          type: array
          description: >-
            One JWT-SVID for each SPIFFE ID the workload is authorized to hold,
            all signed with the requested audience claim(s).
          items:
            $ref: '#/components/schemas/JWTSVID'
    JWTBundlesResponse:
      type: object
      description: >-
        Streamed response from the FetchJWTBundles RPC containing JWT signing
        key sets for all trust domains.
      required:
        - bundles
      properties:
        bundles:
          type: object
          description: >-
            Map from trust domain name to serialized JWKS (JSON Web Key Set)
            document. Contains signing keys for validating JWT-SVIDs from
            workloads in each trust domain.
          additionalProperties:
            type: string
            description: Serialized JWKS JSON document
    ValidateJWTSVIDResponse:
      type: object
      description: Response from the ValidateJWTSVID RPC
      required:
        - spiffe_id
      properties:
        spiffe_id:
          type: string
          description: The SPIFFE ID extracted from the validated JWT-SVID
          pattern: '^spiffe://[^/]+/.+'
        claims:
          type: object
          description: >-
            The full set of JWT claims from the validated token as a key-value
            map. Includes standard claims (sub, aud, exp, iat) and any custom
            claims included by the token issuer.
          additionalProperties: true