pomerium/pkg/zero/cluster/openapi.yaml

openapi: 3.0.0

info:
  title: "Pomerium Zero SDK API"
  version: 0.1.0

servers:
  - url: /cluster/v1

security:
  - bearerAuth: []

paths:
  /bootstrap:
    get:
      description: Get cluster bootstrap configuration
      operationId: getClusterBootstrapConfig
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetBootstrapConfigResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /bundles:
    get:
      description: Get all cluster resource bundles
      operationId: getClusterResourceBundles
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetBundlesResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /bundles/{bundleId}/download:
    get:
      description: Download cluster resource bundle
      operationId: downloadClusterResourceBundle
      parameters:
        - $ref: "#/components/parameters/bundleId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadBundleResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /bundles/{bundleId}/status:
    post:
      description: Report cluster resource bundle status
      operationId: reportClusterResourceBundleStatus
      parameters:
        - $ref: "#/components/parameters/bundleId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BundleStatus"
      responses:
        "204":
          description: OK
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /exchangeToken:
    post:
      description: Exchange cluster identity token for bearer token
      operationId: exchangeClusterIdentityToken
      tags: [token]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExchangeTokenRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExchangeTokenResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /reportUsage:
    post:
      description: Report usage for the cluster
      operationId: reportUsage
      tags: [usage]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReportUsageRequest"
      responses:
        "204":
          description: OK
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /config/import:
    put:
      description: |
        Apply the raw configuration directly to the cluster, replacing any
        existing user-defined routes, policies, and certificates.
        Only available before a Pomerium instance has connected to the cluster
        for the first time.
      operationId: importConfiguration
      tags: [cluster]
      parameters:
        - in: header
          name: X-Import-Hints
          schema:
            type: array
            items:
              type: string
          style: simple
          explode: true
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              contentMediaType: application/octet-stream
              contentEncoding: zstd
        description: type.googleapis.com/pomerium.config.Config
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  parameters:
    bundleId:
      name: bundleId
      in: path
      description: bundle id
      required: true
      schema:
        type: string

  schemas:
    BootstrapConfig:
      type: object
      properties:
        clusterId:
          type: string
        databrokerStorageConnection:
          type: string
          description: databroker storage connection string
        organizationId:
          type: string
        pseudonymizationKey:
          type: string
          format: byte
        sharedSecret:
          type: string
          format: byte
          description: shared secret
      required:
        - clusterId
        - organizationId
        - pseudonymizationKey
        - sharedSecret

    Bundle:
      type: object
      properties:
        id:
          type: string
          description: bundle id
      required:
        - id
    BundleStatus:
      type: object
      properties:
        success:
          $ref: "#/components/schemas/BundleStatusSuccess"
        failure:
          $ref: "#/components/schemas/BundleStatusFailure"
    BundleStatusSuccess:
      type: object
      properties:
        metadata:
          type: object
          description: bundle metadata
          additionalProperties:
            type: string
      required:
        - metadata
    BundleStatusFailure:
      type: object
      properties:
        message:
          type: string
        source:
          type: string
          description: source of the failure
          enum:
            - download_error
            - io_error
            - invalid_bundle
            - databroker_error
            - unknown_error
      required:
        - source
        - message

    DownloadBundleResponse:
      type: object
      properties:
        url:
          type: string
          description: download URL
        expiresInSeconds:
          type: string
          format: int64
        captureMetadataHeaders:
          type: array
          items:
            type: string
          description: bundle metadata that need be picked up by the client from the download URL
      required:
        - url
        - expiresInSeconds
        - captureMetadataHeaders
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
      required:
        - error
    ImportResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
    ExchangeTokenRequest:
      type: object
      properties:
        refreshToken:
          type: string
          description: cluster identity token
      required:
        - refreshToken
    ExchangeTokenResponse:
      type: object
      properties:
        idToken:
          type: string
          description: ID token
        expiresInSeconds:
          type: string
          format: int64
      required:
        - idToken
        - expiresInSeconds
    GetBootstrapConfigResponse:
      $ref: "#/components/schemas/BootstrapConfig"
    GetBundlesResponse:
      type: object
      properties:
        bundles:
          type: array
          items:
            $ref: "#/components/schemas/Bundle"
      required:
        - bundles
    ReportUsageRequest:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/ReportUsageUser"
      required:
        - users
    ReportUsageUser:
      type: object
      properties:
        lastSignedInAt:
          type: string
          format: "date-time"
        pseudonymousEmail:
          type: string
        pseudonymousId:
          type: string
      required:
        - lastSignedInAt
        - pseudonymousEmail
        - pseudonymousId