# Copyright 2018-2022 Cargill Incorporated
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

openapi: '3.0.0'

info:
  version: 0.7.1
  title: splinterd API
  description: REST API for the Splinter daemon

servers:
  - url: http://localhost:9000/api

paths:
  /status:
    get:
      tags:
        - Diagnostics
      description: |
        Used to check if server is successfully running

        This endpoint requires the permission "status.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: Server is running correctly and accepting connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /admin/proposals:
    get:
      summary: Fetches a list of pending circuit proposals for this node
      description: |
        This endpoint can be used to view all of the circuit proposals that the
        node is a proposed member of. If a circuit management type is provided
        via the "management_type" query parameter, only circuit proposals that
        have the given circuit management type will be returned. If a node ID is
        provided via the "member" query parameter, only circuit proposals that
        have the given node as a member will be returned. If no filter is
        provided, all of the node's circuit proposals will be returned.

        This endpoint requires the permission "circuit.read".
      tags:
        - Proposals
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: offset
          in: query
          description: paging offset
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: maximum number of items to return (max 100)
          required: false
          schema:
            type: integer
            default: 100
        - name: management_type
          in: query
          description: |-
            Only show proposed circuits matching the given circuit management
            type
          required: false
          schema:
            type: string
        - name: member
          in: query
          description: |-
            Only show proposed circuits that have a member with the given node
            ID
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the list of proposals
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Proposal'
                  paging:
                    $ref: '#/components/schemas/Paging'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /admin/proposals/{circuit_id}:
    get:
      summary: Fetches a circuit proposal by the circuit's ID
      description: |
        This endpoint can be used to view a specific circuit proposal that the
        node is a proposed member of.

        This endpoint requires the permission "circuit.read".
      tags:
        - Proposals
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: circuit_id
          in: path
          description: Circuit ID of the proposal to fetch
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the requested proposal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Proposal"
        '401':
          description: The client is unauthorized
        '404':
          description: The requested circuit proposal was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /admin/submit:
    post:
      tags:
        - Admin Service
      description: |
        Send circuit management payload in bytes to admin service

        This endpoint requires the permission "circuit.write".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '202':
          description: The circuit management payload was accepted
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  /ws/admin/register/{type}:
    get:
      tags:
        - Admin Service
      description: |
        Register the handler for a circuit management type

        This endpoint requires the permission "circuit.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: type
          description: The circuit management type is the type of circuit the handler will manage
          in: path
          required: true
          schema:
            type: string
          x-example: gameroom
        - name: last
          description: A timestamp in milliseconds from the Unix Epoch, indicating the last received event.
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Registration request was successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationRegistration'
        '400':
          description: |
            The circuit management type was invalid or the request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /admin/circuits:
    get:
      summary: Fetches a list of circuits that the node belongs to
      description: |
        This endpoint can be used to view all or some of the circuits that the
        node is a member of. If a node ID is provided via the "filter" query
        parameter, only circuits that have the given node ID as a member will be
        returned. If a circuit status is provided via the "status" query
        parameter, only circuits that have the given circuit status will be
        returned; if no filter is provided, all of the node's `Active` circuits
        will be returned.

        This endpoint requires the permission "circuit.read".
      tags:
        - Circuits
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: offset
          in: query
          description: paging offset
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: maximum number of items to return (max 100)
          required: false
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: Node ID that must be present in the returned circuits
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Circuit status of the returned circuits
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the list of circuits
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Circuit'
                  paging:
                    $ref: '#/components/schemas/Paging'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /admin/circuits/{circuit_id}:
    get:
      summary: Fetches a circuit by its ID
      description: |
        This endpoint can be used to view a specific circuit that the node is a
        member of.

        This endpoint requires the permission "circuit.read".
      tags:
        - Circuits
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: circuit_id
          in: path
          description: ID of the circuit to fetch
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the requested circuit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Circuit"
        '401':
          description: The client is unauthorized
        '404':
          description: The requested circuit was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /authorization/assignments:
    parameters:
      - $ref: "#/components/parameters/auth"
      - $ref: "#/components/parameters/protocol_version"
    get:
      tags:
        - Authorization
      summary: Get all assignments
      description: |
        Gets all assignments.

        This endpoint requires the permission "authorization.rbac.read".

      parameters:
        - $ref: "#/components/parameters/paging"
      responses:
        '200':
          description: Get list of all assignments
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  $ref: "#/components/schemas/Assignment"
        '400':
          description: Malformed query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "400"
                message: "Malformed Query"
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "500"
                message: "Internal Server Error"
    post:
      tags:
        - Authorization
      summary:
        Add a new assignment
      description:
        Adds a new assignment

        This endpoint requires the permission "authorization.rbac.write".
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignmentPayload'
      responses:
        '200':
          description: The assignment has been added
        '400':
          description: Invalid assignment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "400"
                message: "Invalid assignment payload"
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "500"
                message: "Internal Server Error"

  /authorization/assignments/{identity_type}/{identity}:
    parameters:
      - $ref: "#/components/parameters/auth"
      - $ref: "#/components/parameters/protocol_version"
      - $ref: "#/components/parameters/identity_type"
      - $ref: "#/components/parameters/identity"
    get:
      tags:
        - Authorization
      summary:
        Get assignment
      description: |
        Gets the assignment associated with the identity.

        This endpoint requires the permission "authorization.rbac.read".
      responses:
        '200':
          description: Assignment associated with the identity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssignmentData"
        '404':
          description: Assignment not found for given identity.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: "404"
                message: "Assignment not found"
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: "500"
                message: "Internal Server Error"

    patch:
      tags:
        - Authorization
      summary:
        Update assignment.
      description: |
        Updates the assignment associated with the identity.

        This endpoint requires the permission "authorization.rbac.write".
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssignmentUpdate"
      responses:
        '200':
          description: Updated assignment associated with identity
        '404':
          description: Identity not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: "404"
                message: "Identity not found"
        '409':
          description: Assignment violates state constraints
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: "409"
                message: "Assignment is invalid"
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: "500"
                message: "Internal Server Error"

    delete:
      tags:
        - Authorization
      description: |
        Removes the assignment associated with the identity and identity_type.

        This endpoint requires the permission "authorization.rbac.write".
      responses:
        '200':
          description: Assignment is removed.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: "500"
                message: "Internal Server Error"

  /authorization/maintenance:
    get:
      tags:
        - Authorization
      description: |
        Checks whether or not maintenance mode is enabled

        This endpoint requires the permission "authorization.maintenance.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: Successfully checked maintenance mode
          content:
            text/plain:
              schema:
                type: string
                properties:
                  message:
                    type: string
                    enum:
                      - "true"
                      - "false"
        '401':
          description: The client is unauthorized
    post:
      tags:
        - Authorization
      description: |
        Sets whether or not maintenance mode is enabled

        This endpoint requires the permission "authorization.maintenance.write".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: enabled
          in: query
          description: |
            If "true", maintenance mode will be enabled; if "false", maintenance
            mode will be disabled.
          required: true
          schema:
            type: boolean
      responses:
        '200':
          description: Successfully checked maintenance mode
          content:
            text/plain:
              schema:
                type: string
                properties:
                  message:
                    type: boolean
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized

  /authorization/permissions:
    get:
      tags:
        - Authorization
        - Permissions
      description: |
        Fetches the list of all REST API permissions

        This endpoint requires the permission "authorization.permissions.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: Successfully retrieved the list of REST API permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Permission'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized

  /authorization/roles:
    get:
      summary: Fetches a list of roles
      description: |
        This endpoint can be used to view all of the available roles configured
        for the node.  These roles control access to various permissions in the
        system.

        This endpoint requires the permission "authorization.rbac.read".
      tags:
        - Roles
        - Permissions
        - RBAC
        - Authorization
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: offset
          in: query
          description: paging offset
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: maximum number of items to return (max 100)
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successfully retrieved the requested list of roles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
                  paging:
                    $ref: '#/components/schemas/Paging'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Roles
        - Permissions
        - RBAC
        - Authorization
      summary: Add a role
      description: |
        This endpoint can be used to add a new role to the Splinter Role-based
        authorization system. The role must conform to the role schema and have
        unique "role_id" value.

        This endpoint requires the permission "authorization.rbac.write".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
      responses:
        '200':
          description: The role was successfully added
        '400':
          description: The request was malformed or the role was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /authorization/roles/{role_id}:
    get:
      summary: Fetches a role by its ID
      description: |
        This endpoint can be used to view a specific role.

        This endpoint requires the permission "authorization.rbac.read".
      tags:
        - Roles
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: role_id
          in: path
          description: ID of the role to fetch
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the requested role
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Role'
        '401':
          description: The client is unauthorized
        '404':
          description: The requested role was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /registry/nodes:
    post:
      summary: Add a node to the registry
      description: |
        This endpoint can be used to add a new node to the Splinter registry.
        The node must be valid (see the Splinter registry documentation for
        details on node validity).

        This endpoint requires the permission "registry.write".
      tags:
        - Splinter Registry
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisteredNode'
      responses:
        '200':
          description: The node was successfully added to the registry
        '400':
          description: The request was malformed or the node was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    get:
      summary: List nodes in the registry
      description: |
        This endpoint can be used to view all or some of the nodes in the
        registry. If metadata filters are provided via the "filter" query
        parameter, only nodes that match the given filters will be returned. See
        the Splinter registry documentation for details on metadata filters.

        This endpoint requires the permission "registry.read".
      tags:
        - Splinter Registry
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: offset
          in: query
          description: paging offset
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: maximum number of items to return (max 100)
          required: false
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: |
            url-encodeded stringified JSON containing property filters on the
            node's metadata properties in the format
              {METADATA_PROPERTY:[{"operator":OPERATOR,"value":VALUE}]}
          required: false
          schema:
            type: string
          example: "%7B%22company%22%3A%5B%22%3D%22%2C%22Cargill%22%5D%7D"
      responses:
        '200':
          description: The list of nodes was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegisteredNode'
                  paging:
                    $ref: '#/components/schemas/Paging'
        '400':
          description: The request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /registry/nodes/{identity}:
    get:
      summary: Fetch a node in the registry by its identity
      description: |
        This endpoint can be used to view a specific nodes in the registry.

        This endpoint requires the permission "registry.read".
      tags:
        - Splinter Registry
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: identity
          in: path
          description: identity of node to fetch
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The node was successfully retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/RegisteredNode"
        '401':
          description: The client is unauthorized
        '404':
          description: The node was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      summary: Add or replace a node in the registry
      description: |
        This endpoint can be used to add a new node to the registry, or replace
        an existing node. When replacing an existing node, the node identity
        cannot be changed. This action is idempotent.

        This endpoint requires the permission "registry.write".
      tags:
        - Splinter Registry
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: identity
          in: path
          description: identity of node to add/replace
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisteredNode'
      responses:
        '200':
          description: The node has been added or replaced
        '400':
          description: The request was malformed or the node was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete a node from the registry
      description: |
        This endpoint can be used to remove a node from the registry.

        This endpoint requires the permission "registry.write".
      tags:
        - Splinter Registry
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: identity
          in: path
          description: identity of node to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The node has been deleted from the registry
        '401':
          description: The client is unauthorized
        '404':
          description: The node was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /scabbard/{circuit}/{service_id}/batches:
    post:
      summary: Submit a list of batches to the Scabbard service
      description: |
        This endpoint can be used to submit batches to a Scabbard service. The
        body of the request must be a list of valid Sabre batches. If the
        batches are submitted successfully, the response will contain a link for
        checking the status of the submitted batches.

        This endpoint requires the permission "scabbard.write".
      tags:
        - Scabbard
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: circuit
          in: path
          description: Circuit the targeted service belongs to
          required: true
          schema:
            type: string
        - name: service_id
          in: path
          description: ID of the targeted service
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Batch was submitted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Link"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: |
            The scabbard service with the given circuit and service id was not
            found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests have been made to process batches
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /scabbard/{circuit}/{service_id}/batch_statuses:
    get:
      summary: Get the statuses of a list of batches
      description: |
        This endpoint can be used to check the status of one or more batches
        that were submitted to a Scabbard service. The IDs of the batches to
        check should be specified with the `ids` query parameter. The `wait`
        query parameter requests that the server wait for the given number of
        seconds for the batches to be committed; however, this wait time is not
        guaranteed.

        This endpoint requires the permission "scabbard.read".
      tags:
        - Scabbard
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: circuit
          in: path
          description: Circuit the targeted service belongs to
          required: true
          schema:
            type: string
        - name: service_id
          in: path
          description: ID of the targeted service
          required: true
          schema:
            type: string
        - name: ids
          in: query
          description: Comma-separated list of batch IDs
          required: true
          schema:
            type: string
        - name: wait
          in: query
          description: |
            Time (in seconds) to wait for batches to be committed. If not
            provided, the server will return the batch statuses immediately. If
            the parameter is provided without a value, the default time (300
            seconds) will be used.
          required: false
          schema:
            type: integer
            default: 300
      responses:
        '200':
          description: The statuses of the batches were successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchStatus'
        '400':
          description: The request was malformed or no batch IDs were provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: |
            The scabbard service with the given circuit and service id was not
            found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '408':
          description: |
            The batches were not committed before the specified wait time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /scabbard/{circuit}/{service_id}/state:
    get:
      summary: Get a list of entries from a Scabbard service's state
      description: |
        This endpoint can be used to fetch a list of entries from a Scabbard
        service's state. The entries can be filtered using an address prefix
        provided with the `prefix` query parameter.

        This endpoint requires the permission "scabbard.read".
      tags:
        - Scabbard
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: circuit
          in: path
          description: Circuit the targeted service belongs to
          required: true
          schema:
            type: string
        - name: service_id
          in: path
          description: ID of the targeted service
          required: true
          schema:
            type: string
        - name: prefix
          in: query
          description: |
            An address prefix for filtering state entries. If no prefix is
            specified, all state entries will be returned.
          required: false
          schema:
            type: string
            example: 00ec01
      responses:
        '200':
          description: The state entries were successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    address:
                      type: string
                    value:
                      type: array
                      items:
                        type: integer
        '400':
          description: The request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: |
            The scabbard service with the given circuit and service id was not
            found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /scabbard/{circuit}/{service_id}/state/{address}:
    get:
      summary: Get the value at an address in a Scabbard service's state
      description: |
        This endpoint can be used to fetch the value at a specific address in a
        Scabbard service's state.

        This endpoint requires the permission "scabbard.read".
      tags:
        - Scabbard
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: circuit
          in: path
          description: Circuit the targeted service belongs to
          required: true
          schema:
            type: string
        - name: service_id
          in: path
          description: ID of the targeted service
          required: true
          schema:
            type: string
        - name: address
          in: path
          description: The address of the value to retrieve from state
          required: true
          schema:
            type: string
            example: 000000a87cb5eafdcca6a814e4add97c4b517d3c530c2f44b31d18e3b0c44298fc1c14
      responses:
        '200':
          description: The value was successfully retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
        '401':
          description: The client is unauthorized
        '404':
          description: |
            The scabbard service with the given circuit and service id was not
            found, or there is no value at the given address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /biome/register:
    post:
      tags:
        - Biome
      description: Create new user with username and password credentials
      parameters:
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  description: username of a new user
                hashed_password:
                  description: |
                     Hashed password to be used for user authentication
              required:
                - username
                - hashed_password
              example:
                username: alice@acme.com
                hashed_password: F4AABE0B40C9ABB8B6FD2EEACB39C965
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: "User created successfully"
                  data:
                    type: object
                    $ref: '#/components/schemas/BiomeNewUser'
        '400':
          description: Invalid request
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/login:
    post:
      tags:
        - Biome
      description: Authenticates a user with username and password credentials
      parameters:
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  description: username of user
                hashed_password:
                  description: |
                    Hashed password to be used for user authentication

              required:
                - username
                - hashed_password
              example:
                username: alice@acme.com
                hashed_password: |-
                  8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successful login"
                  user_id:
                    type: string
                    description: "Internal unique identifier for the user"
                    example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
                  token:
                    type: string
                    description: "JWT access token used for authorizing access to protected resources"
                    example: "Biome:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2\
                      VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE\
                      0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8h\
                      A0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
                  refresh_token:
                    type: string
                    description: "JWT refresh token used for obtaining a new access to token"
                    example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lk\
                      IjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0Iiwia\
                      XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_x\
                      riYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
        '400':
          description: Invalid request
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/logout:
    patch:
      tags:
        - Biome
      description: Removes access tokens associated with a user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User successfully logged out"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/token:
    post:
      tags:
        - Biome
      description: Issues a new access token
      parameters:
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                refresh_token:
                  description: a refresh token issues by biome

              required:
                - refresh_token
              example:
                refresh_token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lk\
                  IjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0Iiwia\
                  XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_x\
                  riYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: "JWT access token used for authorizing access to protected resources"
                    example: "Biome:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2\
                      VyX2lkIjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE\
                      0IiwiaXNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8h\
                      A0ru_xriYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
        '400':
          description: Invalid request
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '401':
          description: Access token is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBiome'
        '403':
          description: Refresh token is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/verify:
    post:
      tags:
        - Biome
      description: Verifies a user with username and password credentials
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  description: username of user
                hashed_password:
                  description: |
                    Hashed password to be used for user authentication
              required:
                - username
                - hashed_password
              example:
                username: alice@acme.com
                hashed_password: |-
                  8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Successful verification"
                  user_id:
                    type: string
                    description: "Internal unique identifier for the user"
                    example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/users:
    get:
      tags:
        - Biome
      description: |
        Lists all users

        This endpoint requires the permission "biome.user.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: List of users registered in Biome
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    username:
                      type: string
                      description: "Username used for login"
                      example: "alice@acme.com"
                    user_id:
                      type: string
                      description: "Internal unique identifier for the user"
                      example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/users/{user_id}:
    get:
      tags:
      - Biome
      description: |
        Fetch a user by ID

        This endpoint requires the permission "biome.user.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: user_id
          in: path
          description: ID of the user
          required: true
          schema:
            type: string
            example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    description: "Username used for login"
                    example: "alice@acme.com"
                  user_id:
                    type: string
                    description: "Internal unique identifier for the user"
                    example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: Resource not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
    put:
      tags:
      - Biome
      description: |
        Update a user

        This endpoint requires the permission "biome.user.write".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: user_id
          in: path
          description: ID of the user
          required: true
          schema:
            type: string
            example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                  description: Existing username of user
                hashed_password:
                  type: string
                  description: |
                    Hashed password to be used for user authentication
                new_password:
                  type: string
                  description: |
                    Hash of the new password to be used for user authentication
                new_key_pairs:
                    type: array
                    items:
                      $ref: '#/components/schemas/BiomeNewUserKey'
              required:
                - username
                - hashed_password
              example:
                username: alice@acme.com
                hashed_password: |-
                  8945622435187243046536949706b5272644c71336c7254563679727565494b376d4b3554696b734662685962652f6v52562e437a70462f6552489c8b
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Credentials and key updated successfully"
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BiomeUserKey'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: Resource not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
    delete:
      tags:
        - Biome
      description: |
        Delete a user

        This endpoint requires the permission "biome.user.write".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: user_id
          in: path
          description: ID of the user
          required: true
          schema:
            type: string
            example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User deleted successfully"
        '401':
          description: The client is unauthorized
        '404':
          description: User with {user_id} not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/profiles:
    get:
      tags:
        - Biome
      description: |
        List all user profiles

        This endpoint requires the permission "biome.profile.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: List of profiles for all users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BiomeProfile'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/profiles/{user_id}:
    get:
      tags:
      - Biome
      description: |
        Fetch a profile by ID

        This endpoint requires the permission "biome.profile.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: user_id
          in: path
          description: ID of the user
          required: true
          schema:
            type: string
            example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiomeProfile'
        '401':
          description: The client is unauthorized
        '404':
          description: Resource not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/profile:
    get:
      tags:
        - Biome
      description: Get the profile of the authenticated user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: User's profile
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/BiomeProfile'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/keys:
    get:
      tags:
      - Biome
      description: List keys of a user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: User's keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BiomeUserKey'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
    put:
      tags:
      - Biome
      description: Replace all keys for the user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BiomeUserKey'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Keys replaced successfully"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
    patch:
      tags:
      - Biome
      description: Update a key's display name
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              properties:
                public_key:
                  type: string
                  description: Public key
                new_display_name:
                  type: string
                  description: |
                    Updated display name for the key
              required:
                - public_key
                - new_display_name
              example:
                public_key: "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118"
                new_display_name: |-
                  Admin key pair
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Key updated successfully"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: Resource not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
    post:
      tags:
      - Biome
      description: Add a new key for user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BiomeUserKey'
      responses:
        '200':
          description: User added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Key added successfully"
                  data:
                    $ref: '#/components/schemas/BiomeUserKey'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /biome/keys/{public_key}:
    get:
      tags:
      - Biome
      description: Fetch key of a user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: public_key
          in: path
          description: Public key of the user
          required: true
          schema:
            type: string
            example: "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118"
      responses:
        '200':
          description: User's key
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BiomeUserKey'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: Resource not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
    delete:
      tags:
      - Biome
      description: Delete key of a user
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: public_key
          in: path
          description: Public key of the user
          required: true
          schema:
            type: string
            example: "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118"
      responses:
        '200':
          description: User's key deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User deleted successfully"
                  data:
                    $ref: '#/components/schemas/BiomeUserKey'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
        '404':
          description: Resource not found
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/ErrorBiome'

  /oauth/login:
    get:
      tags:
        - OAuth
      description: |
        Provides a redirect to the node's configured OAuth provider to
        authenticate the user.
      parameters:
        - $ref: "#/components/parameters/protocol_version"
        - name: redirect_url
          in: query
          description: |
            The URL the client will be redirected to once the OAuth
            authentication process has been completed. If this parameter is not
            provided, Splinter will attempt to retrieve the `referer` header
            of the request. If this header value is also not available and the
            `redirect_url` does not have a value, Splinter will respond with
            400 Bad Request.
          required: false
          schema:
            type: string
      responses:
        '302':
          description: Found redirect
          headers:
            Location:
              description: URL of the OAuth provider
              schema:
                type: string
        '400':
          description: |
            Request was malformed or no `redirect_url` was provided and the server
            was unable to retrieve the request's `referer` header value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Error'

  /oauth/callback:
    get:
      tags:
        - OAuth
      description: |
        Receives an authorization code from the OAuth provider to create an
        access token for the user. Redirects to a URL provided by the client
        when the OAuth authentication process was initiated.
      parameters:
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '302':
          description: |
            Splinter has successfully exchanged the authorization code provided
            by the OAuth provider has been successfully exchanged for an access
            token. The application may then be redirected to the `redirect_url`
            provided when the OAuth authentication process was initiated.
            The `redirect_url` has the access token and other user data required
            to log in the user to the application appended to it as query
            parameters.
          headers:
            Location:
              description: |
                Client URL provided at the beginning of the OAuth authentication
                process, with the user's information appended as query parameters.
              schema:
                type: string
        '400':
          description: |
            Request was malformed or no authorization request was found correlating
            to the authorization code and the server was unable to retrieve the
            request's `referer` header value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Error'

  /oauth/logout:
    get:
      tags:
        - OAuth
      description: Removes a user's access and refresh tokens from storage.
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User successfully logged out"
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Error'

  /oauth/users:
    get:
      tags:
        - OAuth
      description: |
        Lists all OAuth users

        This endpoint requires the permission "oauth.user.read".
      parameters:
        - $ref: "#/components/parameters/auth"
        - $ref: "#/components/parameters/protocol_version"
        - name: offset
          in: query
          description: paging offset
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: maximum number of items to return (max 100)
          required: false
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: List of users registered in Biome's OAuth
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthUser'
                  paging:
                    $ref: '#/components/schemas/Paging'
        '400':
          description: Request was malformed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The client is unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error occurred
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/Error'

components:
  parameters:
    auth:
      name: Authorization
      in: header
      description: |
        The client's authorization, which the server resolves to an identity.
        Currently supports Biome JWT (if Biome credentials is enabled), Cylinder
        JWT, and OAuth2 bearer tokens.
      required: true
      schema:
        type: string
      examples:
        Biome:
          summary: Biome example
          value: Bearer Biome:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lk\
            IjoiZjM1YWFjYzEtYTljZC00ZWRhLWI2ZDAtMmVmYWRkZjBjOGE0IiwiaXNzIjoic2V\
            sZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_xriYX7qryl08ZEp86t5HD\
            _AEVPEUXY70Ehc
        Cylinder:
          summary: Cylinder example
          value: Bearer Cylinder:eyJhbGciOiJzZWNwMjU2azEiLCJ0eXAiOiJjeWxpbmR\
            lcitqd3QifQ==.eyJpc3MiOiIwMjc5YmU2NjdlZjlkY2JiYWM1NWEwNjI5NWNlODcwY\
            jA3MDI5YmZjZGIyZGNlMjhkOTU5ZjI4MTViMTZmODE3OTgifQ==.71Vw3+m9R4b8iZU\
            zhRHOAtX/hO5WYA9PgMe27/CeZ6NhIXFYkBBzreoIGpHbfJ8UxT+1MLUgjsQB8TISaf\
            neRA==
        OAuth2:
          summary: OAuth2 example
          value: Bearer OAuth2:55eeea7ce2b472d69d406990939baa698e34e955

    protocol_version:
      name: SplinterProtocolVersion
      in: header
      description: |
        The protocol version which the client can understand. If not provided,
        the node will respond using its latest protocol version.
      required: false
      schema:
        type: integer
        example: 2

    identity_type:
      name: identity_type
      description: Enum of possible identity types.
      in: path
      required: true
      schema:
        type: string
        enum:
          - key
          - user

    identity:
      name: identity
      description: The unique identity string.
      in: path
      required: true
      schema:
        type: string

    paging:
      name: paging_query 
      in: query
      description: An offset and limit for paginated results.
      required: true
      schema:
        type: object
        properties:
          limit:
            type: integer
          offset:
            type: integer
  schemas:
    BiomeNewUser:
      additionalProperties: false
      properties:
        user_id:
          type: string
        username:
          type: string

    Assignment:
      properties:
        identity:
          type: object
          $ref: '#/components/schemas/Identity'
        roles:
          type: array
          items:
            type: string

    AssignmentData:
      properties:
        data:
          type: object
          $ref: '#/components/schemas/Assignment'

    AssignmentUpdate:
      properties:
        roles:
          type: array
          items:
            type: string

    AssignmentPayload:
      properties:
        identity:
          type: object
          $ref: '#/components/schemas/IdentityPayload'
        roles:
          type: array
          items:
            type: string

    IdentityPayload:
      properties:
        key:
          type: string
        user:
          type: string

    Identity:
      additionalProperties: false
      properties:
        key:
          type: string
        User:
          type: string

    Error:
      additionalProperties: false
      properties:
        message:
          description: A message describing the error that occurred
          type: string
          example: DatabaseError({description})
      required:
        - message

    ErrorBiome:
      additionalProperties: false
      properties:
        code:
          description: Error code
          type: string
          example: "400"
        message:
          description: A message describing the error that occurred
          type: string
          example: "Invalid payload"
      required:
        - message

    ErrorResponse:
      additionalProperties: false
      properties:
        code:
          description: Http response code
          type: string
          example: "400"
        message:
          description: A message describing the error that occurred.
          type: string
          example: "Invalid query"


    Status:
      additionalProperties: false
      properties:
        version:
          description: Rest API version
          type: string
          example: "0.7.1"
        node_id:
          description: Node id
          type: string
          example: node-009
        display_name:
          description: Human-readable name for the node
          type: string
          example: Cargill Node 009
        service_endpoint:
          type: string
          description: The node's service endpoint
          example: tcp://foo.bar.biz
        network_endpoints:
          description: The node's locally-bound network endpoints
          type: array
          items:
            type: string
            example: tcp://foo.bar.biz
        advertised_endpoints:
          description: The node's network endpoints that are publicly accessible
          type: array
          items:
            type: string
            example: tcp://foo.bar.biz
      required:
        - version

    ApplicationRegistration:
      additionalProperties: false
      properties:
        status:
          description: Registration status
          type: string
          enum:
            - OK
            - ERROR
        circuit_management_type:
          description: Circuit management type
          type: string
          example: gameroom
        error_reason:
          description: Error message if the registration failed
          type: string

    RegisteredNode:
      type: object
      properties:
        identity:
          type: string
        endpoints:
          type: array
          items:
            type: string
        display_name:
          type: string
        keys:
          type: array
          items:
            type: string
        metadata:
          type: object
      example:
        identity: node-123123-asdf
        endpoints:
          - tcps://12.0.0.123:8431
        display_name: Cargill - Node 1
        keys:
          - "03e0e5086beffc640ec0d149d4f1197fdde0f338afac774541831281c6fd91cbe0"
        metadata:
          company: Cargill
          status: Up

    Link:
      type: object
      properties:
        link:
          type: string
          description: Link to get status of batches that were submitted
          example: "/scabbard/abcde-01234/ABCD/batch_statuses?ids=6ff35474a572087e08fd6a54d563bd8172951b363e5c9731f1a40a855e14bba45dac515364a08d8403f4fb5d4a206174b7f63c29e4f4e425dc71b95494b8a798"

    BatchStatus:
      type: object
      properties:
        id:
          type: string
          description: The batch's ID
          example: 6ff35474a572087e08fd6a54d563bd8172951b363e5c9731f1a40a855e14bba45dac515364a08d8403f4fb5d4a206174b7f63c29e4f4e425dc71b95494b8a798
        status:
          type: object
          description: Batch status
          properties:
            statusType:
              type: string
              enum:
                - Unknown
                - Invalid
                - Valid
                - Pending
                - Committed
            message:
                type: array
                items:
                  type: object
                  properties:
                    transaction_id:
                      type: string
                      example: f4e147ff464013deccb3e68bb8619beffb29ff86b401257c93bcf8ef76d7ca173fa84b4f4a58414ad2d00a2c9f810cbb726e01cd26ebd44720239d9d35853099
                    error_message:
                      type: string
                      example: "Wasm contract returned invalid transaction: xo, 0.3.3"
                    error_data:
                      type: array
                      items:
                        type: integer
                        description: Byte array for arbitrary error data. Each byte is represented as an unsigned integer ranging from 0-255.

    Circuit:
      type: object
      properties:
        id:
          type: string
          example: 01234-ABCDE
        members:
          description: Circuit members in the circuit
          type: array
          items:
              $ref: '#/components/schemas/CircuitMember'
        roster:
          description: All services defined for the circuit
          type: array
          items:
            $ref: '#/components/schemas/CircuitService'
        management_type:
          type: string
          example: gameroom
        display_name:
          description: Human readable name for the circuit
          type: string
          nullable: true
        circuit_status:
            description: The status of the circuit
            type: string
            nullable: true
            enum:
              - Active
              - Disbanded
              - Abandoned

    CircuitService:
      type: object
      properties:
        service_id:
          type: string
          example: abcd
        service_type:
          type: string
          example: scabbard
        node_id:
          description: The node ID that is allowed to run this service
          type: string
          example: alpha-node-000

    CircuitMember:
      type: object
      properties:
        node_id:
          type: string
          example: alpha-node-000
        endpoints:
          type: array
          items:
            type: string
            example: tcps://12.0.0.123:8431
        public_key:
          type: string
          example: 026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118

    Proposal:
      type: object
      properties:
        proposal_type:
          type: string
          enum:
            - Create
            - UpdateRoster
            - AddNode
            - RemoveNode
            - Disband
        circuit_id:
          type: string
          example: 01234-ABCDE
        circuit_hash:
          type: string
          example: 8ce518770b962429a953b10220905ac9adf86a855f0b085695f444edf991b8ca
        circuit:
            type: object
            properties:
              circuit_id:
                type: string
                example: 01234-ABCDE
              members:
                type: array
                items:
                  $ref: '#/components/schemas/ProposedCircuitMember'
              roster:
                type: array
                items:
                  $ref: '#/components/schemas/ProposedCircuitService'
              management_type:
                type: string
                example: gameroom
              application_metadata:
                type: string
                format: binary
              comments:
                description: Arbitrary comments to describe the proposed circuit
                type: string
              display_name:
                description: Human readable name for the circuit
                type: string
                nullable: true
              circuit_version:
                  description: The protocol version the circuit adheres to
                  type: integer
              circuit_status:
                  description: The status of the circuit
                  type: string
                  enum:
                    - Active
                    - Disbanded
                    - Abandoned
        votes:
          type: array
          items:
            $ref: '#/components/schemas/Vote'
        requester:
          type: string
          example: 026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118
        requester_node_id:
          type: string
          example: alpha-node-000

    ProposedCircuitMember:
      type: object
      properties:
        node_id:
          type: string
          example: alpha-node-000
        endpoints:
          type: array
          items:
            type: string
            example: tcps://12.0.0.123:8431
        public_key:
          type: string
          example: 026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118

    ProposedCircuitService:
      type: object
      properties:
        service_id:
          type: string
          example: abcd
        service_type:
          type: string
          example: scabbard
        node_id:
          description: The node ID that is allowed to run this service
          type: string
          example: alpha-node-000
        arguments:
          description: |-
            Arbitrary arguments to be passed to this service on initialization,
            formatted as an array of (key, value) pairs
          type: array
          items:
            type: array
            items:
              type: string
            minItems: 2
            maxItems: 2

    Vote:
      type: object
      properties:
        public_key:
          type: string
          example: 026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118
        vote:
          type: string
          enum:
            - Accept
            - Reject
        voter_node_id:
          type: string
          example: alpha-node-000

    Paging:
      type: object
      properties:
        current:
          type: string
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        first:
          type: string
        prev:
          type: string
        next:
          type: string
        last:
          type: string
      example:
        current: /registry/nodes?offset=10&limit=10
        offset: 10
        limit: 10
        total: 50
        first: /registry/nodes?offset=0&limit=10
        prev: /registry/nodes?offset=0&limit=10
        next: /registry/nodes?offset=20&limit=10
        last: /registry/nodes?offset=40&limit=10

    BiomeUserKey:
      type: object
      properties:
        display_name:
          type: string
          description: "Display name for key"
          example: "Biome Admin Key"
        encrypted_private_key:
          type: string
          description: "Encrypted private key"
          example: "XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_x\
            riYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
        public_key:
          type: string
          description: "Public key"
          example: "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118"
        user_id:
          type: string
          description: "Internal unique identifier for the user"
          example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"

    BiomeNewUserKey:
      type: object
      properties:
        display_name:
          type: string
          description: "Display name for key"
          example: "Biome Admin Key"
        encrypted_private_key:
          type: string
          description: "Encrypted private key"
          example: "XNzIjoic2VsZi1pc3N1ZWQiLCJleHAiOjE1ODAyMzkyMjh9.P8hA0ru_x\
            riYX7qryl08ZEp86t5HD_AEVPEUXY70Ehc"
        public_key:
          type: string
          description: "Public key"
          example: "026c889058c2d22558ead2c61b321634b74e705c42f890e6b7bc2c80abb4713118"

    BiomeCredentials:
      type: object
      properties:
        user_id:
          type: string
          description: "Internal unique identifier for the user"
          example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
        username:
          type: string
          description: "Username of a user"
          example: "bob@biome.com"

    Permission:
      type: object
      properties:
        permission_id:
          type: string
          description: "Unique identifier for the permission"
          example: "circuit.read"
        permission_display_name:
          type: string
          description: "A human readable name of the permission"
          example: "Circuit read"
        permission_description:
          type: string
          description: "A helpful description of the permission"
          example: "Allows the client to modify circuit state"

    Role:
      type: object
      properties:
        role_id:
          type: string
          description: "Unique identifier for the role"
          example: "circuit-administrator"
        display_name:
          type: string
          description: "A human readable name of the role."
          example: "Circuit Administrator"
        permissions:
          type: array
          description: "An array of permissions included with this role."
          items:
            type: string

    BiomeProfile:
      type: object
      properties:
        user_id:
          type: string
          description: "Internal unique identifier for the user"
          example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"
        subject:
          type: string
          description: "Oauth provider's unique identifier for the user"
          example: "129367690558975733497"
        name:
          type: string
          description: "User's name"
          example: "Alice Foo"
        given_name:
          type: string
          description: "The given name of the user"
          example: "Alice"
        family_name:
          type: string
          description: "The family name of the user"
          example: "Foo"
        email:
          type: string
          description: "The email address of the user"
          example: "alice@gmail.com"
        picture:
          type: string
          description: "The profile picture for the user's account"
          example: "https://lh6.googleusercontent.com/AMZpcempiaceeiA/s96-c/photo.jpg"

    OAuthUser:
      type: object
      properties:
        subject:
          type: string
          description: "Oauth provider's unique identifier for the user"
          example: "129367690558975733497"
        user_id:
          type: string
          description: "Biome's internal unique identifier for the user"
          example: "f35aacc1-a9cd-4eda-b6d0-2efaddf0c8a4"

tags:
  - name: Biome
    description: Routes supporting user management in Splinter applications. Optionally compiled.
  - name: Proposals
  - name: Admin Service
  - name: Circuits
  - name: Authorization
  - name: Permissions
  - name: Roles
  - name: RBAC
  - name: Splinter Registry
  - name: Scabbard
  - name: OAuth