edge-api/source/management/sessions.yml

---
paths:
  sessions:
    get:
      summary: List sessions
      description: |
        Retrieves a list of active sessions resources; supports filtering, sorting, and pagination. Requires admin access.

        Sessions are tied to an API session and are moved when an API session times out or logs out. Active sessions
        (i.e. Ziti SDK connected to an edge router) will keep the session and API session marked as active.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Session
      operationId: listSessions
      parameters:
        - $ref: '../shared/parameters.yml#/limit'
        - $ref: '../shared/parameters.yml#/offset'
        - $ref: '../shared/parameters.yml#/filter'
      responses:
        '200':
          $ref: '#/responses/listSessionsManagement'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  sessions-id:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    get:
      summary: Retrieves a single session
      description: Retrieves a single session by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Session
      operationId: detailSession
      responses:
        '200':
          $ref: '#/responses/detailSessionManagement'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    delete:
      summary: Delete a session
      description: Delete a session by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Session
      operationId: deleteSession
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/deleteResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '409':
          $ref: '../shared/standard-responses.yml#/responses/cannotDeleteReferencedResourceResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  sessions-id-route-path:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    get:
      summary: Retrieves a single session's router path
      description: Retrieves a single session's route path by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Session
      operationId: detailSessionRoutePath
      responses:
        '200':
          $ref: '#/responses/detailSessionRoutePath'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

responses:
  detailSessionRoutePath:
    description: A single session's route path
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/detailSessionRoutePathEnvelope'
  listSessionsManagement:
    description: A list of sessions
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/listSessionsManagementEnvelope'
  detailSessionManagement:
    description: A single session
    headers:
      WWW-Authenticate:
        description: "Denotes different type of security token related information"
        type: array
        items:
          type: string
    schema:
      $ref: '#/definitions/detailSessionManagementEnvelope'


definitions:
  detailSessionRoutePathEnvelope:
    type: object
    required:
      - meta
      - data
    properties:
      meta:
        $ref: '../shared/standard-responses.yml#/definitions/meta'
      data:
        $ref: '#/definitions/sessionRoutePathDetail'
  sessionRoutePathDetail:
    type: object
    properties:
      routePath:
        type: array
        items:
          type: string
  listSessionsManagementEnvelope:
    type: object
    required:
      - meta
      - data
    properties:
      meta:
        $ref: '../shared/standard-responses.yml#/definitions/meta'
      data:
        $ref: '#/definitions/sessionManagementList'
  detailSessionManagementEnvelope:
    type: object
    required:
      - meta
      - data
    properties:
      meta:
        $ref: '../shared/standard-responses.yml#/definitions/meta'
      data:
        $ref: '#/definitions/sessionManagementDetail'
  sessionManagementList:
    type: array
    items:
      $ref: '#/definitions/sessionManagementDetail'
  sessionManagementDetail:
    allOf:
      - $ref: '../shared/sessions.yml#/definitions/sessionDetail'
      - type: object
        properties:
          servicePolicies:
            type: array
            items:
              $ref: '../shared/base-entity.yml#/definitions/entityRef'