specification: API Commons Authentication
specificationVersion: '0.1'
provider: Buoyant
providerId: buoyant
generated: '2026-09-04'
method: searched
source: >-
  https://docs.buoyant.io/buoyant-cloud/tasks/programmatic-agent-install/,
  https://docs.buoyant.io/buoyant-cloud/tasks/routing-requests-through-internet-proxy/,
  grpc/buoyant-linkerd-proxy-api-identity.proto (saved verbatim in this repo), and a
  live probe of https://api.buoyant.cloud (2026-09-04).
note: >-
  There is no OpenAPI to derive from — Buoyant's machine-readable contracts are
  protobuf. Two distinct authentication surfaces exist and they are not
  interchangeable: an in-cluster mTLS identity plane, and a client-credentials
  handshake between the Buoyant Cloud agent and api.buoyant.cloud.
schemes:
  - id: linkerd-workload-identity
    surface: In-cluster Linkerd control plane (io.linkerd.proxy.identity.Identity)
    type: mutualTLS
    description: >-
      Every meshed workload obtains a short-lived mTLS leaf certificate by calling the
      Identity service's Certify RPC with its Kubernetes ServiceAccount token. Identity
      is bound to the ServiceAccount, not to the pod IP or hostname, which is what makes
      Linkerd's AuthorizationPolicy checks identity-based rather than network-based.
    contract: grpc/buoyant-linkerd-proxy-api-identity.proto
    credentials:
      - name: Kubernetes ServiceAccount projected token
        transport: gRPC request field
    rotation: >-
      Leaf certificates are short-lived and auto-rotated. Trust anchor rotation was
      manual until Buoyant Enterprise for Linkerd 2.20.0 introduced an operator that
      automates it.
  - id: buoyant-cloud-agent-credentials
    surface: api.buoyant.cloud (Buoyant Cloud agent telemetry + configuration)
    type: clientCredentials
    description: >-
      The Buoyant Cloud agent authenticates to Buoyant Cloud with an org-scoped client
      ID and secret issued in the Buoyant Cloud workspace. These are supplied either as
      Helm values or as a pre-created Kubernetes secret. This is a machine-to-machine
      credential for the agent, not a public developer API key programme — Buoyant
      publishes no developer API key issuance flow.
    credentials:
      - name: api.clientID
        location: Helm value
      - name: api.clientSecret
        location: Helm value
      - name: client_id
        location: data field of the Kubernetes secret buoyant-cloud-org-credentials
      - name: client_secret
        location: data field of the Kubernetes secret buoyant-cloud-org-credentials
    issuance: https://buoyant.cloud/settings
    transport: >-
      gRPC over HTTPS to api.buoyant.cloud. Probed 2026-09-04: any non-gRPC request
      returns HTTP 415 with content-type application/grpc, grpc-status 3,
      grpc-message "invalid gRPC request content-type". HSTS is enforced
      (max-age=31536000; includeSubDomains).
oauth2:
  published: false
  note: >-
    No OAuth 2.0 or OpenID Connect discovery document is served on any Buoyant or
    Linkerd host — see well-known/buoyant-well-known.yml. Buoyant Cloud user sign-in is
    a first-party web login at buoyant.cloud, not a documented delegated-authorization
    flow for third-party clients.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com