openapi.yaml

# Copyright (c) 2021 Cisco Systems, Inc. and its affiliates
# All rights reserved.
# Use of this source code is governed by a BSD 3-Clause License
# that can be found in the LICENSE file.

openapi: '3.0.3'
info:
  version: 1.0.0
  title: Stream Management API for OpenID Shared Security Events
  description: |
    [OpenID Spec](https://openid.net/specs/openid-sse-framework-1_0.html#management)

    HTTP API to be implemented by Event Transmitters. This API can be used by
    Event Receivers to query and update the Event Stream configuration and
    status, to add and remove subjects, and to trigger verification.
  license:
    name: MIT

paths:
  /.well-known/sse-configuration:
    $ref: './paths/transmitter-configuration.yaml'
  /.well-known/sse-configuration/{issuer}:
    $ref: './paths/transmitter-configuration-with-issuer.yaml'
  /stream:
    $ref: './paths/stream-configuration.yaml'
  /status:
    $ref: './paths/status.yaml'
  /add-subject:
    $ref: './paths/add-subject.yaml'
  /remove-subject:
    $ref: './paths/remove-subject.yaml'
  /verification:
    $ref: './paths/verification.yaml'
  /jwks.json:
    $ref: './paths/jwks.yaml'
  /poll:
    $ref: './paths/poll.yaml'
  /register:
    $ref: './paths/register.yaml'
  /trigger-event:
    $ref: './paths/trigger-event.yaml'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

  parameters:
    issuer:
      $ref: './parameters/path/issuer.yaml'
    subject:
      $ref: './parameters/query/subject.yaml'

  schemas:
    StreamStatus:
      $ref: './schemas/StreamStatus.yaml'
    TransmitterConfiguration:
      $ref: './schemas/TransmitterConfiguration.yaml'
    StreamConfiguration:
      $ref: './schemas/StreamConfiguration.yaml'
    UpdateStreamStatus:
      $ref: './schemas/UpdateStreamStatus.yaml'

    PollDeliveryMethod:
      $ref: './schemas/PollDeliveryMethod.yaml'
    PushDeliveryMethod:
      $ref: './schemas/PushDeliveryMethod.yaml'

    RegisterResponse:
      $ref: './schemas/RegisterResponse.yaml'
    TriggerEventParameters:
      $ref: './schemas/TriggerEventParameters.yaml'

    # Request Body params
    AddSubjectParameters:
      $ref: './schemas/AddSubjectParameters.yaml'
    PollParameters:
      $ref: './schemas/PollParameters.yaml'
    RegisterParameters:
      $ref: './schemas/RegisterParameters.yaml'
    RemoveSubjectParameters:
      $ref: './schemas/RemoveSubjectParameters.yaml'
    VerificationParameters:
      $ref: './schemas/VerificationParameters.yaml'

    # Simple Subjects
    Account:
      $ref: './schemas/subject/Account.yaml'
    DID:
      $ref: './schemas/subject/DID.yaml'
    Email:
      $ref: './schemas/subject/Email.yaml'
    IssSub:
      $ref: './schemas/subject/IssSub.yaml'
    JwtID:
      $ref: './schemas/subject/JwtID.yaml'
    Opaque:
      $ref: './schemas/subject/Opaque.yaml'
    PhoneNumber:
      $ref: './schemas/subject/PhoneNumber.yaml'
    SamlAssertionID:
      $ref: './schemas/subject/SamlAssertionID.yaml'

    # Nested Subjects
    SimpleSubject:
      $ref: './schemas/subject/SimpleSubject.yaml'
    Aliases:
      $ref: './schemas/subject/Aliases.yaml'
    ComplexSubject:
      $ref: './schemas/subject/ComplexSubject.yaml'

    # Subject
    Subject:
      $ref: './schemas/subject/Subject.yaml'

    # Errors
    Error:
      $ref: './schemas/Error.yaml'

  responses:
    BadRequest:
      # 400
      description: Request body cannot be parsed or the request is otherwise invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      # 401
      description: Authorization failed or is missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      # 403
      description: User not authorized to access resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      # 404
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      # 429
      description: Event Receiver is sending too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
tags:
- name: StreamManagement
  description: |-
    [Spec](https://openid.net/specs/openid-sse-framework-1_0.html#management)
    Stream Management endpoints provided by an Event Transmitter so that Event Transmitters may configure Event Streams.
- name: Transmitter
  description: |-
    Additional endpoints provided by an Event Transmitter. These are not needed during Stream Managment, but are used
    by Event Receivers for event processing.
- name: OutOfBand
  description: |-
    Endpoints that are NOT a part of the [Open ID Spec](https://openid.net/specs/openid-sse-framework-1_0.html), but
    that exist for convenience within this demo.