nova-security-api.yml

openapi: 3.0.3
x-apiname: novaSecurityApi
x-responsetime: 10000

x-providerName: postmanova.com

servers:
  - url: https://f63cb6ed-1814-4022-a576-12423186dae7.mock.pstmn.io

info:
  contact:
    name: Example Support 
    email: "admin@admin.edu"
    url: "http://www.postman.com"
  description: |-
    **The NOVA Security Users Management API allows you to programmatically access NOVA network users and perform admin tasks.**

    When integrating the NOVA Security User Management API with other systems, it is good practice to keep an eye on activity that may pose a security risk. 

    You should have received instructions on setting up administrative roles and API keys when you received your invite to this workspace, but if you need assistance with that, please reach out to your manager and we can get those to you right away. 


    ## Associated Resources
    - There is an **OpenAPI file** that was used to generate this collection, which you can find in the "APIs" tab on the left vertical sidebar. As the API itself evolves, we will use the two-way Git sync to update the spec from Bitbucket to Postman, and thus translate those changes over to this documentation collection. 
    - Be sure to check back to this collection before you start implementing, and click the Watch icon on the API to be alerted to any changes   


    <img alt="Watch API Icon" src="https://user-images.githubusercontent.com/20145532/129741324-cb48e900-d793-4d3c-88db-dbc9fc0ece7d.png">
    - **Monitor**: Under the Monitors tab on the same vertical toolbar, we have set up a monitor that runs the collection once a day and displays the results of the tests. 
    - **Mock Server**: As this API is liable to expose sensitive information, we have set up a mock server to return example responses. You can still send the requests, just make sure the `baseUrl` variable is filled in with the monitor url to receive a response.
    - **Visualizations**: To make data easier to spot-check, we have implemented a visualization on the `GET All API Users` request that lets you search and filter users by their last login.   


    <img alt="user table visualization" src="https://user-images.githubusercontent.com/20145532/129748924-1adbfacb-c281-4c2d-8c0d-0eef38d0cbf9.gif" width="500">



    # Terms to Know

    A **NOVA Network User** is defined as any user who has logged on to your service that is monitored under the NOVA security umbrella. You can configure which services are covered in your partner portal. 


    # Authentication

    An API Key is required to be sent as part of every request to the NOVA Security API, in the form of an `X-Api-Key` request header.  You can get your key from the NOVA security portal or through your manager or team administrator.

    An API Key tells our API server that the request it received came from you. Everything that you have access to in Postman is accessible with an API Key that is generated by you.

    For ease of use inside Postman, you could store your API key in an [environment variable](https://www.getpostman.com/docs/environments) called `postman_api_key` and this [Collection](https://www.getpostman.com/docs/network) will automatically use it to make API calls.



    ## Using the API Key as a query parameter

    Every request that accepts API Key as `X-Api-Key` request header, also accepts the key when sent as `apikey` URL query parameter.

    API key sent as part of the header has a higher priority in case you send the key using both request header and query parameter.
    ```
    # API Reference
  title: NOVA Security APIs
  version: 1.0.0
  license:
    name: BSD-1-Clause
    url: https://opensource.org/license/bsd-1-clause/
  termsOfService: https://example.com/tos
  
security:
  - api_key: []

tags:
  - description: This folder contains the requests around system users available to administrative users. 
    name: Admin
  - description: This folder contains endpoints available to monitor network security.
    name: Network
paths:
  "/admin/{adminId}/users":
    get:
      description: |-
        This call fetches details about the all the network users currently registered in the system.

        The response will contain an array `users` object which would be a list of all the network users along with their details.

      operationId: getAllNetworkUsers
      responses:
        "200":
          content:
            application/json:
              examples:
                Get all network users:
                  value:
                    users:
                      - createdAt: 2019-02-12 19:34:49
                        createdBy: "42068"
                        id: 024660a6-c837-46ca-91d8-7e8dd7c669de
                        name: "George Costanza"
                        updatedAt: 2019-02-12 19:34:49
                      - createdAt: 2019-02-12 19:34:49
                        createdBy: "42068"
                        id: 00932d3b-20f1-454f-a77e-38b4023163ea
                        name: "Elaine Benes"
                        updatedAt: 2019-02-12 19:34:49
              schema:
                  $ref: '#/components/schemas/User'
                  items:
                    $ref: '#/components/schemas/User'
                  type: array
          description: Get all network users
        "500":
          description: Internal server error
      summary: Get all network users
      tags:
        - Admin
    parameters:
      - in: path
        description: Get all users
        example: all-users
        name: adminId
        required: true
        schema:
          $ref: '#/components/schemas/User'
          type: string
      - in: header
        description: Get all users
        example: all-users
        name: x-mock-response-name
        schema:
          $ref: '#/components/schemas/User'
          type: string
  "/admin/{adminId}/users/{userId}":
    delete:
      description: |-
        This call deletes an existing network user having the specified id.  

        Response contains an `user` object with `id` of the network user which was deleted.

      operationId: deleteANetworkUser
      responses:
        "200":
          content:
            application/json:
              examples:
                Delete a network user:
                  value:
                    user:
                      id: 03c17f53-7e2e-427d-b55a-006b244f29ff
              schema:
                $ref: '#/components/schemas/User'
                properties:
                  user:
                    properties:
                      id:
                        example: 03c17f53-7e2e-427d-b55a-006b244f29ff
                        type: string
                    type: object
                type: object
          description: Delete a network user
        "500":
          description: Internal server error
      summary: Delete a network user
      tags:
        - Admin 
         
    get:
      description: |-
        This call fetches details about the specified network user.

        The response will contain a `user` object which would contain all the details of the network user.

      operationId: getNetworkuser
      responses:
        "200":
          content:
            application/json:
              examples:
                Get a network user:
                  value:
                    user:
                      $ref: '#/components/schemas/user'                
          description: Get a network user
        "500":
          description: Internal server error
      summary: Get a network user
      tags:
        - Admin 
    parameters:
      - in: path
#        description: Get user
        example: 1234-4321-1234-4321
        name: adminId
        required: true
        schema:
          $ref: '#/components/schemas/User'
          type: string
      - in: path
        description: Get user
#        example: 1234-4321-1234-4321
        name: userId
        required: true
        schema:
          $ref: '#/components/schemas/User'
          type: string
    put:
      description: |-
        This call updates an existing network user.  

        Request body should contain a `user` object with the fields which need to be updated. Only field which can be updated is `name`.

        Response contains a `user` object with all the details related to the created network user, namely, `id`, `name`, `email` etc.

      operationId: updateNetworkuser
      requestBody:
        content:
          application/json:
            example:
              user:
                name: "George Costanza"
            schema:
              $ref: '#/components/schemas/User'
              properties:
                user:
                  properties:
                    name:
                      example: "George Costanza"
                      type: string
                  type: object
              type: object
      responses:
        "200":
          content:
            application/json:
              examples:
                Update a network user:
                  value:
                    user:
                      createdAt: 2019-07-26T11:24:15.000Z
                      createdBy: "42068"
                      id: d71cf403-c549-4c7c-9dc6-a6a105acf67c
                      name: "George Costanza"
                      updatedAt: 2019-08-09T09:27:36.000Z
                      updatedBy: "5665"
          description: Update a network user
        "500":
          description: Internal server error
      summary: Update a network user
      tags:
        - Admin 
         
  /network:
    get:
      description: |-
        The `/network` endpoint returns a network report with statistics on user activity, resource management, and found security risks. 
        The response contains an array of network information containing the `name`, `id`, `owner` and `uid` of each network.

      operationId: networkActivityReport
      responses:
        "200":
          content:
            application/json:
              examples:
                Valid Response:
                  value:
                    network:
                      - instanceId: dac5eac9-148d-a32e-b76b-3edee9da28f7
                        name: Instance eu-1
                        users: 631643
                        monthly_active_users: 5000
                        weekly_active_users: 3333
                        average_minutes_per_user: 19   
                      - instanceId: dac5eac9-148d-a32e-b76b-90586jfke0r9
                        name: Instance us-1
                        users: 477 
                        monthly_active_users: 35
                        weekly_active_users: 22
                        average_minutes_per_user: 10
                      - instanceId: dac5eac9-148d-a32e-b76b-cnu94308rcn8
                        name: Instance ca-1
                        users: 235436
                        monthly_active_users: 7890
                        weekly_active_users: 567
                        average_minutes_per_user: 11
              schema:
                $ref: '#/components/schemas/User'
                properties:
                  network:
                    items:
                      properties:
                        id:
                          example: dac5eac9-148d-a32e-b76b-3edee9da28f7
                          type: string
                        name:
                          example: Cloud API
                          type: string
                        owner:
                          example: "631643"
                          type: string
                        uid:
                          example: 631643-dac5eac9-148d-a32e-b76b-3edee9da28f7
                          type: string
                      type: object
                    type: array
                type: object
          description: Valid Response
#        "500":
#          description: Internal server error
      summary: All network usage
      tags:
        - network
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
    BasicAuth:
      type: http
      scheme: basic
  schemas:
    User:            
      type: object
      properties:
        createdAt:
          example: 2019-07-21T16:31:15.000Z
          type: string
        createdBy:
          example: "42068"
          type: string
        id:
          example: 03c17f53-7e2e-427d-b55a-006b244f29ff
          type: string
        name:
          example: "George Costanza"
          type: string         
        updatedAt:
          example: 2019-07-21T16:31:15.000Z
          type: string
        updatedBy:
          example: "5665"
          type: string