openapi.yaml

# Generated with protoc-gen-openapi
# https://github.com/google/gnostic/tree/master/cmd/protoc-gen-openapi

openapi: 3.0.3
info:
    title: ""
    version: 0.0.1
paths:
    /api/kessel/v1/livez:
        get:
            tags:
                - KesselInventoryHealthService
            operationId: KesselInventoryHealthService_GetLivez
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1.GetLivezResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1/readyz:
        get:
            tags:
                - KesselInventoryHealthService
            operationId: KesselInventoryHealthService_GetReadyz
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1.GetReadyzResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1beta2/check:
        post:
            tags:
                - KesselInventoryService
            description: |-
                Performs an relationship check to determine whether a subject has a specific
                 permission or relationship on a resource.

                 This API evaluates whether the provided subject is a member of the specified relation
                 (e.g., "viewer", "editor", "admin") on the target object. It answers the question:
                 "Does subject *X* have relation *Y* on object *Z*?"

                 Common use cases include enforcing read access, conditional UI visibility,
                 or authorization gating for downstream API calls.
            operationId: KesselInventoryService_Check
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1beta2/checkbulk:
        post:
            tags:
                - KesselInventoryService
            description: |-
                Performs bulk permission checks for multiple resource-subject-relation combinations.

                 This API is more efficient than making individual Check calls when verifying permissions
                 for multiple items. It answers questions like:
                 "Which of these resources can subject *X* perform action *Y* on?"

                 Common use cases include:
                 - Filtering lists based on user permissions
                 - Batch authorization checks before performing bulk operations
                 - Dashboard rendering with multiple permission checks
                 - Pre-authorization for UI components

                 The response includes a result for each item in the request, maintaining the same order.
            operationId: KesselInventoryService_CheckBulk
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckBulkRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckBulkResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1beta2/checkforupdate:
        post:
            tags:
                - KesselInventoryService
            description: |-
                Performs a strongly consistent relationship check to determine whether a subject
                 has a specific relation to an object (representing, for example, a permission).

                 This API answers the question:
                 "Is subject *X* currently authorized to update or modify resource *Y*?"
                 Unlike the basic `Check` endpoint, this method guarantees a fully up-to-date
                 view of the relationship state (e.g., not relying on cached or eventually consistent data).

                 It is intended to be used just prior to sensitive operation (e.g., update, delete)
                 which depend on the current state of the relationship.
            operationId: KesselInventoryService_CheckForUpdate
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckForUpdateRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckForUpdateResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1beta2/checkself:
        post:
            tags:
                - KesselInventoryService
            description: |-
                Performs a relationship check where the subject is implicitly the caller
                 (self), as determined by the authentication context, rather than being
                 provided explicitly in the request.

                 This API answers the question:
                 "Does the current caller have relation *Y* on object *Z*?"

                 Common use cases include enforcing access checks for the authenticated user.
            operationId: KesselInventoryService_CheckSelf
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1beta2/checkselfbulk:
        post:
            tags:
                - KesselInventoryService
            description: |-
                Performs bulk permission checks where the subject is implicitly the caller
                 (self) for multiple resource-relation combinations.

                 This API is more efficient than making individual CheckSelf calls when
                 verifying permissions for multiple items. It answers questions like:
                 "Which of these resources can the current caller perform action *Y* on?"

                 The response includes a result for each item in the request, maintaining
                 the same order.
            operationId: KesselInventoryService_CheckSelfBulk
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfBulkRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfBulkResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
    /api/kessel/v1beta2/resources:
        post:
            tags:
                - KesselInventoryService
            description: |-
                Reports to Kessel Inventory that a Resource has been created or has been updated.

                 Reporters can use this API to report facts about their resources in order to
                 facilitate integration, correlation, and access control.

                 Each call can include:
                 - Reporter-specific attributes and relationships (`representations.reporter`)
                 - Shared attributes and relationships common to all reporters (`representations.common`)
                 - Identifiers and metadata that allow correlation to an existing resource

                 Multiple reporters may report representations for the same resource.
                 Kessel Inventory correlates these
                 based on correlation keys provided for a given resource type

                 All versions of your reported facts will be retained and can be queried as needed

                 The relationships reported through this API are used to determine relationship check outcomes
                 via the Check and CheckForUpdate APIs.

                 Reporters are responsible for ensuring delivery guarantees and message ordering
                 appropriate to the sensitivity and consistency needs of their use case.

                 This API does **not** guarantee immediate read-your-writes consistency by default.
                  If a reporter requires newly submitted resources or relationships to be visible
                 in subsequent checks (e.g., `Check`), the request must explicitly set
                 `write_visibility = IMMEDIATE`.
            operationId: KesselInventoryService_ReportResource
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.ReportResourceRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.ReportResourceResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
        delete:
            tags:
                - KesselInventoryService
            description: |-
                Reports to Kessel Inventory that a Reporter's representation of a Resource has been deleted.

                 This operation is typically used when a resource has been decommissioned or
                 is no longer reported by any authorized system.

                 As a result, relationship checks performed via the `Check` and
                 `CheckForUpdate` APIs will no longer resolve positively for the deleted
                 resource. Any decisions that depend on relationships tied to
                 this resource will be affected.

                 As an example, it can revoke previously granted access across the system.
            operationId: KesselInventoryService_DeleteResource
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/kessel.inventory.v1beta2.DeleteResourceRequest'
                required: true
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/kessel.inventory.v1beta2.DeleteResourceResponse'
                default:
                    description: Default error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/google.rpc.Status'
components:
    schemas:
        google.protobuf.Any:
            type: object
            properties:
                '@type':
                    type: string
                    description: The type of the serialized message.
            additionalProperties: true
            description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
        google.rpc.Status:
            type: object
            properties:
                code:
                    type: integer
                    description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
                    format: int32
                message:
                    type: string
                    description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
                details:
                    type: array
                    items:
                        $ref: '#/components/schemas/google.protobuf.Any'
                    description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
            description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
        kessel.inventory.v1.GetLivezResponse:
            type: object
            properties:
                status:
                    type: string
                code:
                    type: integer
                    format: uint32
        kessel.inventory.v1.GetReadyzResponse:
            type: object
            properties:
                status:
                    type: string
                code:
                    type: integer
                    format: uint32
        kessel.inventory.v1beta2.CheckBulkRequest:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckBulkRequestItem'
                consistency:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.Consistency'
            description: |-
                CheckBulkRequest allows checking multiple permissions in a single request.
                 This is more efficient than making individual Check calls when verifying permissions
                 for multiple resource-subject-relation combinations.
        kessel.inventory.v1beta2.CheckBulkRequestItem:
            type: object
            properties:
                object:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
                relation:
                    type: string
                subject:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.SubjectReference'
            description: CheckBulkRequestItem represents a single permission check in a bulk request.
        kessel.inventory.v1beta2.CheckBulkResponse:
            type: object
            properties:
                pairs:
                    type: array
                    items:
                        $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckBulkResponsePair'
                consistencyToken:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ConsistencyToken'
            description: CheckBulkResponse contains the results of all permission checks in the request.
        kessel.inventory.v1beta2.CheckBulkResponseItem:
            type: object
            properties:
                allowed:
                    enum:
                        - ALLOWED_UNSPECIFIED
                        - ALLOWED_TRUE
                        - ALLOWED_FALSE
                    type: string
                    format: enum
            description: CheckBulkResponseItem represents the result of a single permission check.
        kessel.inventory.v1beta2.CheckBulkResponsePair:
            type: object
            properties:
                request:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckBulkRequestItem'
                item:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckBulkResponseItem'
                error:
                    $ref: '#/components/schemas/google.rpc.Status'
            description: CheckBulkResponsePair associates a request item with its corresponding result.
        kessel.inventory.v1beta2.CheckForUpdateRequest:
            type: object
            properties:
                object:
                    allOf:
                        - $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
                    description: |-
                        Required parameters
                         - resource type and id
                         - permission (cannot be derived from type as types may have multiple edit permissions Ex: https://github.com/RedHatInsights/rbac-config/blob/master/configs/prod/schemas/src/notifications.ksl#L37)
                         - user (possibly derived from an identity token)
                relation:
                    type: string
                subject:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.SubjectReference'
        kessel.inventory.v1beta2.CheckForUpdateResponse:
            type: object
            properties:
                allowed:
                    enum:
                        - ALLOWED_UNSPECIFIED
                        - ALLOWED_TRUE
                        - ALLOWED_FALSE
                    type: string
                    format: enum
        kessel.inventory.v1beta2.CheckRequest:
            type: object
            properties:
                object:
                    allOf:
                        - $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
                    description: |-
                        Required parameters (from an authz perspective)
                         - resource type and id
                         - permission (cannot be derived from the type as a type may have multiple 'read' permissions. Ex: https://github.com/RedHatInsights/rbac-config/blob/master/configs/prod/schemas/src/notifications.ksl#L31)
                         - user (possibly derived from an identity token)
                relation:
                    type: string
                subject:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.SubjectReference'
                consistency:
                    allOf:
                        - $ref: '#/components/schemas/kessel.inventory.v1beta2.Consistency'
                    description: |-
                        Consistency requirement for the check operation.
                         If not specified, standard server configuration defaults to minimizeLatency.
                         Server deployments may override this default behavior (for example, to
                         at_least_as_acknowledged).
        kessel.inventory.v1beta2.CheckResponse:
            type: object
            properties:
                allowed:
                    enum:
                        - ALLOWED_UNSPECIFIED
                        - ALLOWED_TRUE
                        - ALLOWED_FALSE
                    type: string
                    format: enum
                consistencyToken:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ConsistencyToken'
        kessel.inventory.v1beta2.CheckSelfBulkRequest:
            type: object
            properties:
                items:
                    type: array
                    items:
                        $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfBulkRequestItem'
                consistency:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.Consistency'
            description: |-
                CheckSelfBulkRequest allows checking multiple permissions for the caller
                 (self) in a single request. This is more efficient than making individual
                 CheckSelf calls when verifying permissions for multiple
                 resource-relation combinations.
        kessel.inventory.v1beta2.CheckSelfBulkRequestItem:
            type: object
            properties:
                object:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
                relation:
                    type: string
            description: |-
                CheckSelfBulkRequestItem represents a single permission check for the caller
                 (self) in a bulk request. The subject is derived from the caller's
                 authenticated identity rather than being provided explicitly.
        kessel.inventory.v1beta2.CheckSelfBulkResponse:
            type: object
            properties:
                pairs:
                    type: array
                    items:
                        $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfBulkResponsePair'
                consistencyToken:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ConsistencyToken'
            description: CheckSelfBulkResponse contains the results of all self-access permission checks in the request.
        kessel.inventory.v1beta2.CheckSelfBulkResponseItem:
            type: object
            properties:
                allowed:
                    enum:
                        - ALLOWED_UNSPECIFIED
                        - ALLOWED_TRUE
                        - ALLOWED_FALSE
                    type: string
                    format: enum
            description: CheckSelfBulkResponseItem represents the result of a single self-access permission check.
        kessel.inventory.v1beta2.CheckSelfBulkResponsePair:
            type: object
            properties:
                request:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfBulkRequestItem'
                item:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.CheckSelfBulkResponseItem'
                error:
                    $ref: '#/components/schemas/google.rpc.Status'
            description: CheckSelfBulkResponsePair associates a self-access request item with its corresponding result.
        kessel.inventory.v1beta2.CheckSelfRequest:
            type: object
            properties:
                object:
                    allOf:
                        - $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
                    description: |-
                        Required parameters (from an authz perspective)
                         - resource type and id
                         - permission (cannot be derived from the type as a type may have multiple 'read' permissions. Ex: https://github.com/RedHatInsights/rbac-config/blob/master/configs/prod/schemas/src/notifications.ksl#L31)

                         The subject is implicitly the caller, as determined by the authentication
                         context, instead of being provided as a SubjectReference.
                relation:
                    type: string
                consistency:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.Consistency'
            description: |-
                CheckSelfRequest performs an access check for the caller (self) against a
                 specific object and relation. The subject is derived from the caller's
                 authenticated identity rather than being provided explicitly.
        kessel.inventory.v1beta2.CheckSelfResponse:
            type: object
            properties:
                allowed:
                    enum:
                        - ALLOWED_UNSPECIFIED
                        - ALLOWED_TRUE
                        - ALLOWED_FALSE
                    type: string
                    format: enum
                consistencyToken:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ConsistencyToken'
            description: CheckSelfResponse represents the result of a self-access permission check.
        kessel.inventory.v1beta2.Consistency:
            type: object
            properties:
                minimizeLatency:
                    type: boolean
                    description: |-
                        The service selects the fastest snapshot available.
                         *Must* be set true if used.
                atLeastAsFresh:
                    allOf:
                        - $ref: '#/components/schemas/kessel.inventory.v1beta2.ConsistencyToken'
                    description: |-
                        All data used in the API call must be *at least as fresh*
                         as found in the ConsistencyToken. More recent data might be used
                         if available or faster.
                atLeastAsAcknowledged:
                    type: boolean
                    description: |-
                        All data used in the API call must be *at least as acknowledged*,
                         meaning it includes data up to the latest write known to Inventory.
                         This aligns with `ReportResource` write visibility: when
                         `write_visibility=IMMEDIATE`, the write waits for acknowledgement, so a
                         subsequent read with `at_least_as_acknowledged` is guaranteed to be at
                         least as recent as that write.
                         Some deployments may use this behavior as the server-side default when
                         consistency is omitted.
                         *Must* be set true if used.
            description: |-
                Defines how a request is handled by the service.
                 If consistency is omitted by the client, standard server configuration uses
                 minimize_latency by default, but deployments may override that default (for
                 example, to at_least_as_acknowledged).
        kessel.inventory.v1beta2.ConsistencyToken:
            type: object
            properties:
                token:
                    type: string
        kessel.inventory.v1beta2.DeleteResourceRequest:
            type: object
            properties:
                reference:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
        kessel.inventory.v1beta2.DeleteResourceResponse:
            type: object
            properties: {}
        kessel.inventory.v1beta2.ReportResourceRequest:
            type: object
            properties:
                inventoryId:
                    type: string
                    description: |-
                        The Kessel Inventory-assigned ID of the *Resource*.

                         Usually not required during reporting; populated internally during correlation.
                type:
                    type: string
                    description: |-
                        The canonical type of the *Resource* (e.g., "k8s_cluster", "host", "integration").

                         Must be a previously agreed-upon value between the *Reporter* and Kessel Inventory.
                         Must be consistent across all *Reporter Representations* of a given Type reported by a given *Reporter*.
                         Used to:
                         - Select the appropriate schema to validate the *Reporter Representation*
                         - Identify a *Reporter's Representation* uniquely in Kessel Inventory
                reporterType:
                    type: string
                    description: |-
                        The type of the *Reporter* (e.g., "hbi", "acm", "acs", "notifications").

                         Must be a previously agreed-upon value between the *Reporter* and Kessel Inventory.
                         Must be consistent across all *Reporter Representations* reported by a given *Reporter*.
                         Used to:
                         - Select the appropriate schema to validate the *Reporter Representation*
                         - Identify a *Reporter's Representation* uniquely in Kessel Inventory
                reporterInstanceId:
                    type: string
                    description: |-
                        Identifier for the specific instance of the *Reporter*.
                         This may not be applicable to all Reporters

                         Used to distinguish between multiple instances of the same `reporter_type`.
                         Does not require prior coordination with Kessel Inventory.
                representations:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceRepresentations'
                writeVisibility:
                    enum:
                        - WRITE_VISIBILITY_UNSPECIFIED
                        - MINIMIZE_LATENCY
                        - IMMEDIATE
                    type: string
                    description: |-
                        Controls the visibility guarantees of the write operation in Kessel Inventory.

                         - `MINIMIZE_LATENCY` (default): Optimizes for throughput; may delay visibility in `Check` results.
                         - `IMMEDIATE`: Ensures read-your-writes consistency; higher latency due to synchronization.

                         Use `IMMEDIATE` only if your use case requires strong consistency guarantees
                         (e.g., writing and immediately checking access to the resource).
                    format: enum
            description: Request to register or update a *Reporter*'s *Representation* of a *Resource* in Kessel Inventory.
        kessel.inventory.v1beta2.ReportResourceResponse:
            type: object
            properties: {}
        kessel.inventory.v1beta2.ReporterReference:
            type: object
            properties:
                type:
                    type: string
                instanceId:
                    type: string
        kessel.inventory.v1beta2.RepresentationMetadata:
            type: object
            properties:
                localResourceId:
                    type: string
                apiHref:
                    type: string
                consoleHref:
                    type: string
                reporterVersion:
                    type: string
                transactionId:
                    type: string
        kessel.inventory.v1beta2.ResourceReference:
            type: object
            properties:
                resourceType:
                    type: string
                resourceId:
                    type: string
                reporter:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ReporterReference'
        kessel.inventory.v1beta2.ResourceRepresentations:
            type: object
            properties:
                metadata:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.RepresentationMetadata'
                common:
                    type: object
                reporter:
                    type: object
        kessel.inventory.v1beta2.SubjectReference:
            type: object
            properties:
                relation:
                    type: string
                    description: |-
                        An optional relation which points to a set of Subjects instead of the single Subject.
                         e.g. "members" or "owners" of a group identified in `subject`.
                resource:
                    $ref: '#/components/schemas/kessel.inventory.v1beta2.ResourceReference'
            description: A reference to a Subject or, if a `relation` is provided, a Subject Set.
tags:
    - name: KesselInventoryHealthService
    - name: KesselInventoryService
      description: |-
        KesselInventoryService provides APIs to perform relationship checks
         and manage inventory resource lifecycles (reporting and deletion).