openapi: 3.0.3
info:
  title: Push Security REST API
  version: v1
  description: >-
    ## Overview


    The Push Security REST API provides programmatic access to the
    administrative functionality of the Push platform. This API adheres to
    RESTful principles, featuring resource-oriented URLs that are predictable
    and easy to navigate.


    The API uses JSON-formatted request bodies and responses along with standard
    HTTP response codes, authentication methods, and HTTP verbs.


    [Rate limits](#section/Rate-limits) are in place to ensure consistent
    performance for all users.


    ## Authentication


    To interact with the Push Security API, you'll need an API key for
    authentication. To create or manage your API keys, go to the
    [Settings](https://pushsecurity.com/app/settings/api-keys) page in the Push
    admin console.


    When generating a new key, you have two permission levels to choose from:
    `Read only` and `Full access`. A `Read only` key lets you make GET requests,
    while `Full access` allows for all types of requests.


    To authenticate your API requests, include a header named `x-api-key` and
    set its value to your API key.


    All API calls must be made over HTTPS.


    ## Rate limits


    The Push Security API enforces rate limiting to ensure equitable access and
    maintain performance. Each user is permitted up to 10 API requests per
    second, with a temporary burst capacity that allows an additional 10
    requests for brief intervals.


    If you surpass these limits, the API will return a 429 status code as an
    indication.


    ## Errors


    The Push Security API uses standard HTTP response codes to signal the
    outcome of an API call. Here's what you need to know:


    2xx codes: These indicate that your request was successful.


    4xx codes: A client-side issue, usually because something is missing or
    incorrect in your request.


    5xx codes: These suggest a problem on our end, although these occurrences
    are infrequent.


    ### Common Response Codes


    | HTTP Code | Description                                             |

    |-----------|---------------------------------------------------------|

    | 200 OK    | Your request was successfully processed.                 |

    | 400 Bad Request | Your request is missing something or is incorrect.
    Double-check your parameters.  |

    | 429 Too Many Requests | You've exceeded the rate limits. Consider
    implementing exponential backoffs in your API calls.  |

    | 500 Server Error | Something's not right on our end.                     
    |


    ## Versioning


    You're currently working with version 1 of the Push Security API. Should
    there be any breaking changes in the future, we'll bump up the API version
    number. If you hold an active API key, we'll send you notifications over
    email about the deprecation date for the older version.
  contact:
    name: support
    email: support@pushsecurity.com
    url: https://pushsecurity.com/contact/
  termsOfService: https://pushsecurity.com/legal/terms/
  license:
    url: https://pushsecurity.com/legal/terms/
    name: Commercial
x-amazon-apigateway-request-validators:
  all:
    validateRequestBody: true
    validateRequestParameters: true
  params:
    validateRequestBody: false
    validateRequestParameters: true
  none:
    validateRequestBody: false
    validateRequestParameters: false
x-amazon-apigateway-api-key-source: AUTHORIZER
servers:
  - url: https://api.pushsecurity.com
paths:
  /v1/employees:
    get:
      summary: List employees
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmployeeInList'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-employees
      parameters:
        - in: query
          name: chatopsEnabled
          schema:
            type: boolean
          description: >-
            Filter by whether they have ChatOps enabled<blockquote>Note: this is
            a legacy value available for use by Push accounts that are using
            employee ChatOps topics. This value will be removed in a future
            version of the API, however, no timeline has been set. Push will
            provide ample notice of deprecation ahead of time, as well as a
            replacement option.</blockquote>
        - in: query
          name: licensed
          schema:
            type: boolean
          description: Filter by whether they are licensed on the Push platform
        - in: query
          name: groups
          schema:
            type: array
            items:
              type: string
          description: Filter by groups the employee is in.
        - in: query
          name: email
          schema:
            type: string
          description: >-
            Filter by email address. Accepts partial email addresses for
            wildcard searches.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
    post:
      operationId: post-employees
      summary: Add an employee
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      requestBody:
        description: Create a new employee.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  description: The first name of the employee.
                  example: John
                lastName:
                  type: string
                  description: The last name of the employee.
                  example: Doe
                email:
                  type: string
                  description: The email address of the employee.
                  example: john.doe@example.com
                enrolBrowser:
                  type: boolean
                  description: >-
                    Whether the employee will be sent an email to ask them to
                    install the Push browser extension.
                  example: true
              required:
                - firstName
                - lastName
                - email
                - enrolBrowser
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeInEvent'
        '400':
          description: Bad Request
  /v1/employees/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the employee
    get:
      summary: Retrieve an employee
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: Bad Request
        '404':
          description: Employee Not Found
      operationId: get-employees-id
    patch:
      summary: Update an employee
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      operationId: patch-employees-id
      responses:
        '200':
          description: >-
            OK. Returns `null` if you unlicense an employee that hasn't got any
            accounts
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Employee'
                    type: string
                    nullable: true
                    description: Returned when unlicensing an employee
        '400':
          description: >-
            Bad Request with status EMPLOYEE_NOT_LICENSED,
            EXCEEDED_MAX_LICENSED_EMPLOYEES or CHATOPS_NOT_IN_WORKING_STATE
        '404':
          description: Employee Not Found
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: >-
                    A new primary email address for the employee. This must be
                    one of the known email addresses for the employee.
                  format: email
                firstName:
                  type: string
                  description: A new first name for the employee
                lastName:
                  type: string
                  description: A new last name for the employee
                chatopsEnabled:
                  type: boolean
                  description: >-
                    Set whether the employee has ChatOps
                    enabled<blockquote>Deprecation notice: this value no longer
                    does anything unless you still have access to the legacy
                    Employee chat topics functionality on your account. It will
                    be removed in the next API version.</blockquote>
                  deprecated: true
                licensed:
                  type: boolean
                  description: Set whether the employee is licensed on the Push platform
                groups:
                  type: array
                  description: >-
                    Set the groups an employee is in (this will overwrite the
                    existing groups)
                  items:
                    type: string
      tags:
        - Employees
  /v1/employees/{id}/enrollmentLink:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the employee
    post:
      summary: Generate a browser enrollment link
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      operationId: post-employees-id-enrollmentLink
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    description: >-
                      Enrollment URL that can be used to link a browser
                      extension to this employee
                    example: >-
                      https://pushsecurity.com/setup/browser?step=INSTALL&token=e194ec91-6961-454b-acf3-1a8f4e1fc606
        '400':
          description: Bad Request
        '404':
          description: Employee Not Found
      tags:
        - Employees
  /v1/employees/{id}/groups:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the employee
    post:
      operationId: post-employee-id-groups
      summary: Add an employee to a group.
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      requestBody:
        description: Add an employee to a group
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  type: string
                  description: The name of the group.
                  example: Engineering team
              required:
                - group
      responses:
        '200':
          description: OK. Returns all groups associated with the employee.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      type: string
                    description: The groups associated with the employee.
                    example:
                      - Engineering team
                      - Marketing team
                required:
                  - groups
        '400':
          description: Invalid input
        '404':
          description: Employee Not Found
    delete:
      operationId: delete-employee-id-groups
      summary: Delete an employee from a group
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      requestBody:
        description: Delete an employee from a group.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  type: string
                  description: The group to remove employee from.
                  example: Engineering team
              required:
                - group
      responses:
        '200':
          description: >-
            OK. Returns all groups still associated with the employee after
            being removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      type: string
                    description: The groups associated with the employee.
                    example:
                      - Other team
                required:
                  - groups
        '400':
          description: Invalid input
        '404':
          description: >-
            The employee with the given ID is not found or the employee is not a
            member of the given group.
  /v1/employees/{id}/merge:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the employee
    post:
      operationId: post-employees-id-merge
      summary: Merge employees
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      requestBody:
        description: Merge a list of employees with the primary one given.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secondaryEmployeeIds:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 5
                  description: A list of employee IDs.
                  example:
                    - 72d0347a-2663-4ef5-b1c5-df39163f1603
                    - 87569da6-fb7a-4df7-8ce2-246c14044911
              required:
                - secondaryEmployeeIds
      responses:
        '200':
          description: OK. Returns the details of the primary employee.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: Invalid input
        '404':
          description: Employee Not Found
  /v1/employees/{id}/unmerge:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the employee
    post:
      operationId: post-employees-id-unmerge
      summary: Unmerge employee
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Employees
      requestBody:
        description: Unmerge an email address from a target employee
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The email address to unmerge from the target employee
                  example: john.hill@example.com
              required:
                - email
      responses:
        '200':
          description: OK. Unmerge operation has completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
        '400':
          description: Invalid input
        '404':
          description: Employee Not Found
        '500':
          description: Internal server error
  /v1/accounts:
    get:
      summary: List accounts
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Accounts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-accounts
      parameters:
        - in: query
          name: email
          schema:
            type: string
          description: >-
            Filter by email address. Accepts partial email addresses for
            wildcard searches.
        - in: query
          name: appType
          schema:
            type: string
          description: Filter by the app associated with this account.
        - in: query
          name: employeeId
          schema:
            type: string
          description: Filter by an employee ID associated with this account.
        - in: query
          name: passwordId
          schema:
            type: string
          description: Filter by a password ID associated with this account.
        - in: query
          name: lastUsedTimestampAfter
          schema:
            type: integer
          description: >-
            Filter by when the account was last used by an employee - start
            time. This is a UNIX timestamp (in seconds).
        - in: query
          name: lastUsedTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the account was last used by an employee - end time.
            This is a UNIX timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/accounts/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the account
    get:
      summary: Retrieve an account
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Accounts
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Bad Request
        '404':
          description: Account Not Found
      operationId: get-accounts-id
    delete:
      summary: Forget an account
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      operationId: delete-accounts-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAccount'
        '400':
          description: Bad Request
        '404':
          description: Account Not Found
      tags:
        - Accounts
  /v1/accounts/{id}/loginMethods:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the account
    delete:
      operationId: delete-accounts-id-login-methods
      summary: Delete a login method from an account
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Accounts
      requestBody:
        description: Delete one of the login methods from the account.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                loginMethod:
                  type: string
                  enum:
                    - USERNAME_PASSWORD
                    - OKTA_SWA
                    - OIDC
                    - SAML
                    - FEDCM
                  description: The login method to remove from the account.
                  example: OIDC
              required:
                - loginMethod
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Bad Request
  /v1/accounts/{id}/usedBy:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the account
      - schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 500
        name: limit
        in: query
        required: false
        description: Used for pagination. Number of objects to return.
      - schema:
          type: integer
        name: offset
        in: query
        required: false
        description: >-
          Used for pagination. Number of objects to skip. Cannot be set when
          `nextToken` is also set.
        deprecated: true
      - schema:
          type: string
        name: nextToken
        in: query
        required: false
        description: >-
          Used for pagination. Token to be used for the next request. Cannot be
          set when `offset` is also set.
    get:
      summary: List all employees who are using an account
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Accounts
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountUser'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-accounts-id-used-by
  /v1/apps:
    get:
      summary: List apps
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/App'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-apps
      parameters:
        - in: query
          name: creationTimestampAfter
          schema:
            type: integer
          description: >-
            Filter by when the app was first observed - start time. This is a
            UNIX timestamp (in seconds).
        - in: query
          name: creationTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the app was first observed - end time. This is a UNIX
            timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/apps/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the app
    get:
      operationId: get-apps-id
      summary: Retrieve an app
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          description: Bad Request
    patch:
      operationId: patch-apps-id
      summary: Update an app
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps
      requestBody:
        description: Update an app's approval status, sensitivity level, and/or notes.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                approvalStatus:
                  type: string
                  enum:
                    - APPROVED
                    - NOT_APPROVED
                    - UNDER_REVIEW
                  description: >-
                    The desired approval status for the app. If `null`, the
                    current approval status will be unset.
                  example: APPROVED
                  nullable: true
                sensitivityLevel:
                  type: string
                  enum:
                    - HIGH
                    - MEDIUM
                    - LOW
                  description: >-
                    The desired sensitivity level for the app. If `null`, the
                    current sensitivity level will be unset.
                  example: HIGH
                  nullable: true
                notes:
                  type: string
                  description: >-
                    The desired notes for the app. If `null`, any existing notes
                    will be deleted.
                  example: 'Last security audit: 16 January 2024'
                  nullable: true
                ownerId:
                  type: string
                  description: >-
                    The employee ID for the owner of this app. If `null`, the
                    current owner will be unset.
                  nullable: true
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          description: Bad Request
  /v1/apps/{id}/labels:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the app
    post:
      operationId: post-apps-id-labels
      summary: Add a label to an app.
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps
      requestBody:
        description: Add a label to an app.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: The label to add to the app (max 50 characters)
                  example: personal-use
              required:
                - label
      responses:
        '200':
          description: OK. Returns all labels associated with the app.
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: array
                    items:
                      type: string
                    description: The labels associated with the app.
                    example:
                      - personal-use
                      - other-label
                required:
                  - labels
        '400':
          description: Invalid input
        '404':
          description: App Not Found
    delete:
      operationId: delete-apps-id-labels
      summary: Delete a label from an app.
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps
      requestBody:
        description: Delete a label from an app.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: The label to delete from the app.
                  example: personal-use
              required:
                - label
      responses:
        '200':
          description: >-
            OK. Returns all labels still associated with the app after the label
            is deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  labels:
                    type: array
                    items:
                      type: string
                    description: The labels associated with the app.
                    example:
                      - other-label
                required:
                  - labels
        '400':
          description: Invalid input
        '404':
          description: >-
            The app with the given ID is not found or the given label is not
            associated with the app.
  /v1/browsers:
    get:
      summary: List browsers
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Browsers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Browser'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-browsers
      description: Retrieve a list of browser objects
      parameters:
        - in: query
          name: email
          schema:
            type: string
          description: >-
            Filter by email address. Accepts partial email addresses for
            wildcard searches.
        - in: query
          name: employeeId
          schema:
            type: string
          description: Filter by employee ID.
        - in: query
          name: browser
          schema:
            $ref: '#/components/schemas/BrowserType'
          description: Filter by browser name.
        - in: query
          name: os
          schema:
            $ref: '#/components/schemas/OSType'
          description: Filter by operating system name.
        - in: query
          name: lastOnlineTimestampAfter
          schema:
            type: integer
          description: >-
            Filter by when the browser was last used by an employee - start
            time. This is a UNIX timestamp (in seconds).
        - in: query
          name: lastOnlineTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the browser was last used by an employee - end time.
            This is a UNIX timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/browsers/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the browser
    get:
      summary: Retrieve a browser
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Browsers
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Browser'
        '400':
          description: Bad Request
      operationId: get-browsers-id
  /v1/browserExtensions:
    get:
      summary: List browser extensions
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Browser Extensions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrowserExtension'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-browser-extensions
      description: Retrieve a list of browser extension objects
      parameters:
        - in: query
          name: extensionId
          schema:
            type: string
          description: Filter by the ID of the extension
        - in: query
          name: employeeId
          schema:
            type: string
          description: Filter by an employee ID associated with this extension.
        - in: query
          name: browserId
          schema:
            type: string
          description: Filter by a browserId associated with this extension.
        - in: query
          name: deploymentMode
          schema:
            $ref: '#/components/schemas/DeploymentMode'
          description: Filter by the deployment mode of the extension.
        - in: query
          name: permissions
          schema:
            type: array
            items:
              type: string
          description: Filter for browser extensions that have certain permissions.
        - in: query
          name: hostPermissions
          schema:
            type: array
            items:
              type: string
          description: >-
            Filter for browser extensions that have certain host permission
            patterns.
        - in: query
          name: enabled
          schema:
            type: boolean
          description: Filter for extension that are enabled or disabled.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/controls/blockedUrls:
    get:
      operationId: get-controls-blockedUrls
      summary: List all blocked URLs
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - URL blocking
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: string
                      $ref: '#/components/schemas/BlockedURL'
                    example:
                      - '*://*.example.com/*'
                      - '*://other.example.com/path/to*'
        '400':
          description: Bad Request
    post:
      operationId: post-controls-blockedUrls
      summary: Add a new blocked URL
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - URL blocking
      requestBody:
        description: >-
          A URL pattern used to block access to matching sites. A maximum of
          2,000 blocked URLs is supported.
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ControlsBlockedUrlsHostPath'
                - $ref: '#/components/schemas/ControlsBlockedUrlsUrl'
            examples:
              allPathsForHost:
                summary: >-
                  Block all paths for the given host using the default path
                  wildcard.
                value:
                  host: domain.com
              allPathsForSubdomain:
                summary: >-
                  Block all paths for the given subdomain using the default path
                  wildcard.
                value:
                  host: sub.domain.com
              wildcards:
                summary: Wildcards used both in the host and path.
                value:
                  host: '*.sub.domain.com'
                  path: path/*/something/*
              fullUrlSpecificDomain:
                summary: Block all URLs on a specific domain
                value:
                  url: domain.com
              fullUrlSubdomain:
                summary: Block all URLs on any subdomain of a specific domain
                value:
                  url: '*.domain.com'
              fullUrlPathPattern:
                summary: >-
                  Block paths matching the pattern on any subdomain of a
                  specific domain
                value:
                  url: '*.sub.domain.com/path/*/something/*'
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedURL'
        '400':
          description: Bad Request
    delete:
      operationId: delete-controls-blockedUrls
      summary: Delete all blocked URLs
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - URL blocking
      responses:
        '200':
          description: OK
          headers: {}
          content: {}
        '400':
          description: Bad Request
  /v1/controls/stolenCredentials:
    post:
      operationId: post-controls-stolenCredentials
      summary: Add new stolen credentials
      description: >-
        Add stolen credentials sourced from other threat intelligence feeds
        within your organization.
      x-codeSamples:
        - lang: curl
          source: |
            curl -i -X POST \
            https://api.pushsecurity.com/v1/controls/stolenCredentials \
            -H 'Content-Type: application/json' \
            -H 'x-api-key: YOUR_API_KEY_HERE' \
            -d '[{
              "email": "john.hill@example.com",
              "password": "myAm@z!ngP4$$w0rdTh4tUcantGu3$$",
              "metadata": {
                "key": "value"
              }
            }]'
        - lang: Python
          source: |
            import requests

            url = "https://api.pushsecurity.com/v1/controls/stolenCredentials"

            payload = [
              {
                "email": "john.hill@example.com",
                "password": "myAm@z!ngP4$$w0rdTh4tUcantGu3$$",
                "metadata": {
                  "key": "value"
                }
              }
            ]

            headers = {
              "Content-Type": "application/json",
              "x-api-key": "YOUR_API_KEY_HERE"
            }

            response = requests.post(url, json=payload, headers=headers)

            data = response.json()
            print(data)
        - lang: Node.js
          source: |
            import fetch from 'node-fetch';

            async function run() {
              const resp = await fetch(
                `https://api.pushsecurity.com/v1/controls/stolenCredentials`,
                {
                  method: 'POST',
                  headers: {
                    'Content-Type': 'application/json',
                    'x-api-key': 'YOUR_API_KEY_HERE'
                  },
                  body: JSON.stringify([
                    {
                      "email": "john.hill@example.com",
                      "password": "myAm@z!ngP4$$w0rdTh4tUcantGu3$$",
                      "metadata": {
                        "key": "value"
                      }
                    }
                  ])
                }
              );

              const data = await resp.json();
              console.log(data);
            }

            run();
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Stolen credential detection
      requestBody:
        description: A list of stolen credentials
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                $ref: '#/components/schemas/StolenCredential'
              minItems: 1
              maxItems: 500
              example:
                - email: john.hill@example.com
                  password: myAm@z!ngP4$$w0rdTh4tUcantGu3$$
                  metadata:
                    key: value
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/StolenCredential'
                    minItems: 1
                    maxItems: 500
        '400':
          description: Bad Request
    delete:
      operationId: delete-controls-stolenCredentials
      summary: Delete all stolen credentials
      description: >-
        Delete all the custom stolen credentials that you have added to your
        organization.
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Stolen credential detection
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
  /v1/findings:
    get:
      summary: List findings
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Findings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/Finding'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-findings
      parameters:
        - in: query
          name: state
          schema:
            type: string
          description: Filter by finding state.
        - in: query
          name: type
          schema:
            type: string
          description: Filter by the type of finding.
        - in: query
          name: employeeId
          schema:
            type: string
          description: Filter by the employee associated with the finding.
        - in: query
          name: appType
          schema:
            type: string
          description: Filter by the app that is associated with the finding.
        - in: query
          name: accountId
          schema:
            type: string
          description: Filter by the account that is associated with the finding.
        - in: query
          name: passwordId
          schema:
            type: string
          description: >-
            Filter by the password identifier that is associated with the
            finding.
        - in: query
          name: creationTimestampAfter
          schema:
            type: string
          description: >-
            Filter by when the finding was first observed - start time. This is
            a UNIX timestamp (in seconds).
        - in: query
          name: creationTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the finding was first observed - end time. This is a
            UNIX timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/findings/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the finding
    get:
      summary: Retrieve a finding
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Findings
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Finding'
        '400':
          description: Bad Request
      operationId: get-findings-id
  /v1/accountsOther:
    get:
      summary: List accounts (other)
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Accounts (Other)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountOther'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-accounts-other
      parameters:
        - in: query
          name: email
          schema:
            type: string
          description: >-
            Filter by email address. Accepts partial email addresses for
            wildcard searches.
        - in: query
          name: otherAppId
          schema:
            type: string
          description: Filter by other app ID.
        - in: query
          name: employeeId
          schema:
            type: string
          description: Filter by an employee ID associated with this account.
        - in: query
          name: lastUsedTimestampAfter
          schema:
            type: integer
          description: >-
            Filter by when the account was last used by an employee - start
            time. This is a UNIX timestamp (in seconds).
        - in: query
          name: lastUsedTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the account was last used by an employee - end time.
            This is a UNIX timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/accountsOther/{id}:
    parameters:
      - schema:
          type: string
          format: uuid
        name: id
        in: path
        required: true
        description: Unique identifier for the account (other) record
    get:
      summary: Retrieve an account (other)
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Accounts (Other)
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountOther'
        '400':
          description: Bad Request
        '404':
          description: Account (Other) Not Found
      operationId: get-accounts-other-id
  /v1/appsOther:
    get:
      summary: List Apps (Other)
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps (Other)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppOther'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      next:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `offset` for the next request
                        example: '501'
                        nullable: true
                        deprecated: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-apps-other
      parameters:
        - in: query
          name: creationTimestampAfter
          schema:
            type: integer
          description: >-
            Filter by when the app was first observed - start time. This is a
            UNIX timestamp (in seconds).
        - in: query
          name: creationTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the app was first observed - end time. This is a UNIX
            timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: offset
          schema:
            type: integer
          description: >-
            Used for pagination. Number of objects to skip. Cannot be set when
            `nextToken` is also set.
          deprecated: true
        - in: query
          name: nextToken
          schema:
            type: string
          description: >-
            Used for pagination. Token to be used for the next request. Cannot
            be set when `offset` is also set.
  /v1/appsOther/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the app (other) record
    get:
      summary: Retrieve an app (other) record
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Apps (Other)
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppOther'
        '400':
          description: Bad Request
        '404':
          description: App (Other) Not Found
      operationId: get-apps-other-id
  /v1/detections:
    get:
      summary: List detections
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Detections
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/DetectionWithEmployee'
                  paging:
                    type: object
                    properties:
                      moreResults:
                        type: boolean
                        description: Whether there are more results available
                        example: true
                      nextToken:
                        type: string
                        description: >-
                          Start of the next page that can be used as the
                          `nextToken` for the next request.
                        example: 0b9972aa-fe8d-4095-82d3-2e13cf3cfd43
                        nullable: true
        '400':
          description: Bad Request
      operationId: get-detections
      description: Retrieve a list of detection objects
      parameters:
        - in: query
          name: archived
          schema:
            type: boolean
          description: Filter by whether the detection has been archived.
        - in: query
          name: severity
          schema:
            $ref: '#/components/schemas/SeverityType'
          description: Filter by the severity.
        - in: query
          name: detectionType
          schema:
            $ref: '#/components/schemas/DetectionType'
          description: Filter by the detection type.
        - in: query
          name: response
          schema:
            $ref: '#/components/schemas/ResponseTypeDetection'
          description: Filter by the response.
        - in: query
          name: classification
          schema:
            $ref: '#/components/schemas/ClassificationType'
          description: Filter by the classification.
        - in: query
          name: creationTimestampAfter
          schema:
            type: integer
          description: >-
            Filter by when the detection was created - start time. This is a
            UNIX timestamp (in seconds).
        - in: query
          name: creationTimestampBefore
          schema:
            type: integer
          description: >-
            Filter by when the detection was created - end time. This is a UNIX
            timestamp (in seconds).
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 500
          description: Used for pagination. Number of objects to return.
        - in: query
          name: nextToken
          schema:
            type: string
          description: Used for pagination. Token to be used for the next request.
  /v1/detections/{id}:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Unique identifier for the detection
    get:
      summary: Retrieve a detection
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Detections
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetectionId'
        '400':
          description: Bad Request
      operationId: get-detections-id
    patch:
      operationId: patch-detections-id
      summary: Update a detection
      x-amazon-apigateway-integration:
        uri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackHandlerFunction.Arn}/invocations
        responses:
          default:
            statusCode: '200'
        passthroughBehavior: never
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        type: aws_proxy
      tags:
        - Detections
      requestBody:
        description: Update a detection's archive status.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                archived:
                  type: boolean
                  description: The desired archive status for the detection.
                  example: true
                classification:
                  type: string
                  nullable: true
                  enum:
                    - TRUE_POSITIVE
                    - BENIGN_TRUE_POSITIVE
                    - FALSE_POSITIVE
                  description: The desired classification for the detection.
                  example: FALSE_POSITIVE
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detection'
        '400':
          description: Bad Request
components:
  securitySchemes:
    x-api-key:
      name: x-api-key
      type: apiKey
      in: header
      description: API key authentication
      x-amazon-apigateway-authtype: token
      x-amazon-apigateway-authorizer:
        type: token
        identitySource: method.request.header.x-api-key
        authorizerUri:
          Fn::Sub: >-
            arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${CustomerApisStackAuthorizerFunction.Arn}/invocations
        identityValidationExpression: psak_[a-f0-9]{32}
        authorizerResultTtlInSeconds: 600
  schemas:
    EmployeeInList:
      title: Employee
      type: object
      nullable: false
      description: This object represents an employee in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the employee
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        email:
          type: string
          description: Primary email address of the employee
          format: email
          example: john.hill@example.com
        firstName:
          type: string
          description: First name of the employee
          example: John
        lastName:
          type: string
          description: Last name of the employee
          example: Hill
        department:
          type: string
          description: Department - as provided by connected API integrations
          example: Security Engineering
        location:
          type: string
          description: Location - as provided by connected API integrations
          example: New York
        licensed:
          type: boolean
          description: Whether the employee is licensed on the Push platform
          example: true
        chatopsEnabled:
          type: boolean
          description: >-
            Whether the employee has ChatOps enabled<blockquote>Deprecation
            notice: this value no longer does anything unless you still have
            access to the legacy Employee chat topics functionality on your
            account. It will be removed in the next API version.</blockquote>
          example: true
          deprecated: true
        groups:
          type: array
          description: Groups the employee is in
          items:
            type: string
          example:
            - engineering
            - marketing
        creationTimestamp:
          type: integer
          description: >-
            When this employee was created, formatted as a UNIX timestamp (in
            seconds)
          example: 1698669223
    EmployeeInEvent:
      title: Employee
      type: object
      description: This object represents an employee in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the employee
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        email:
          type: string
          description: Primary email address of the employee
          format: email
          example: john.hill@example.com
        firstName:
          type: string
          description: First name of the employee
          example: John
        lastName:
          type: string
          description: Last name of the employee
          example: Hill
        department:
          type: string
          description: Department - as provided by connected API integrations
          example: Security Engineering
        location:
          type: string
          description: Location - as provided by connected API integrations
          example: New York
        licensed:
          type: boolean
          description: Whether the employee is licensed on the Push platform
          example: true
        chatopsEnabled:
          type: boolean
          description: >-
            Whether the employee has ChatOps enabled<blockquote>Deprecation
            notice: this value no longer does anything unless you still have
            access to the legacy Employee chat topics functionality on your
            account. It will be removed in the next API version.</blockquote>
          example: true
          deprecated: true
        creationTimestamp:
          type: integer
          description: >-
            When this employee was created, formatted as a UNIX timestamp (in
            seconds)
          example: 1698669223
    Employee:
      title: Employee
      type: object
      nullable: false
      description: This object represents an employee in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the employee
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        email:
          type: string
          description: Primary email address of the employee
          format: email
          example: john.hill@example.com
        knownEmails:
          type: array
          description: All the known email addresses of the employee
          items:
            type: string
          example:
            - john.hill@example.com
            - jhill@example.com
        firstName:
          type: string
          description: First name of the employee
          example: John
        lastName:
          type: string
          description: Last name of the employee
          example: Hill
        department:
          type: string
          description: Department - as provided by connected API integrations
          example: Security Engineering
        location:
          type: string
          description: Location - as provided by connected API integrations
          example: New York
        licensed:
          type: boolean
          description: Whether the employee is licensed on the Push platform
          example: true
        chatopsEnabled:
          type: boolean
          description: >-
            Whether the employee has ChatOps enabled<blockquote>Deprecation
            notice: this value no longer does anything unless you still have
            access to the legacy Employee chat topics functionality on your
            account. It will be removed in the next API version.</blockquote>
          example: true
          deprecated: true
        groups:
          type: array
          description: Groups the employee is in
          items:
            type: string
          example:
            - engineering
            - marketing
        creationTimestamp:
          type: integer
          description: >-
            When this employee was created, formatted as a UNIX timestamp (in
            seconds)
          example: 1698669223
    MfaMethodsType:
      title: MfaMethodsType
      type: string
      enum:
        - APP_TOTP
        - PUSH_NOTIFICATION
        - EMAIL_OTP
        - U2F
        - HARDWARE_TOTP
        - PHONE_CALL
        - SMS_OTP
        - APP_PASSWORD
        - GRID_CARD
        - EXTERNAL_PROVIDER
        - BACKUP_CODES
        - WEBAUTHN
      x-enumDescriptions:
        APP_TOTP: Time-based one-time password via app
        PUSH_NOTIFICATION: Authentication prompt on device
        EMAIL_OTP: One-time password sent to email
        U2F: Physical security key
        HARDWARE_TOTP: Time-based password via hardware token
        PHONE_CALL: Voice verification
        SMS_OTP: One-time password sent via SMS
        APP_PASSWORD: Specialized password for app access
        GRID_CARD: Reference card with codes
        EXTERNAL_PROVIDER: Third-party authentication service
        BACKUP_CODES: Pre-generated one-time codes
        WEBAUTHN: Two-factor authentication with biometrics support
      description: All possible ENUM values for MfaMethods
    Account:
      title: Account
      type: object
      description: This object represents an account in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the account
          example: d6a32ba5-0532-4a66-8137-48cdf409c972
        employeeId:
          type: string
          description: Identifier of primary employee that this account belongs to
          example: 72d0347a-2663-4ef5-b1c5-df39163f1603
        appType:
          type: string
          description: The app associated with this account
          example: ATLASSIAN
        appId:
          type: string
          description: The ID of the app associated with this account
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        email:
          type: string
          description: The email address used to log into the account
          format: email
          example: john.hill@example.com
        mfaRegistered:
          type: boolean
          description: Whether MFA is registered or not. If unknown, `null` is provided.
          nullable: true
          example: true
        mfaMethods:
          type: array
          items:
            $ref: '#/components/schemas/MfaMethodsType'
          description: The MFA methods registered for this account
          nullable: true
        passwordId:
          type: string
          description: >-
            Identifier of the password used on this account. The actual password
            is not sent up by the browser extension and so this is an identifier
            for it instead. This value is `null` if password authentication is
            not used.
          nullable: true
          example: 4c13674f-e88a-4411-bfa2-53a70468a898
        loginMethods:
          type: object
          properties:
            passwordLogin:
              type: boolean
              description: Whether or not this account has been logged into with a password
              example: true
            lastPasswordLoginTimestamp:
              type: integer
              description: >-
                When the account was last logged into using a password,
                formatted as a UNIX timestamp (in seconds)
              example: 1698064423
            oidcLogin:
              type: string
              description: >-
                The identity provider that was used to do an OIDC login on this
                account. This is `null` if no OIDC login has been performed.
              nullable: true
              example: GOOGLE_WORKSPACE
            lastOidcLoginTimestamp:
              type: integer
              description: >-
                When the account was last logged into using OIDC, formatted as a
                UNIX timestamp (in seconds)
              example: 1698064423
            samlLogin:
              type: string
              description: >-
                The identity provider that was used to do a SAML login on this
                account. This is `null` if no SAML login has been performed.
              nullable: true
              example: OKTA
            lastSamlLoginTimestamp:
              type: integer
              description: >-
                When the account was last logged into using SAML, formatted as a
                UNIX timestamp (in seconds)
              example: 1698064423
            oktaSwaLogin:
              type: boolean
              description: Whether or not this account has been logged into with Okta SWA
              example: true
            lastOktaSwaLoginTimestamp:
              type: integer
              description: >-
                When the account was last logged into using Okta SWA, formatted
                as a UNIX timestamp (in seconds)
              example: 1698064423
            vendorSsoLogin:
              type: string
              description: >-
                Whether or not this account has an associated vendor SSO
                provider.
              nullable: true
              example: GOOGLE_WORKSPACE
            fedCmLogin:
              type: string
              description: >-
                The identity provider that was used to do a FedCM login on this
                account. This is `null` if no FedCM login has been performed.
              nullable: true
              example: GOOGLE_WORKSPACE
            lastFedCmLoginTimestamp:
              type: integer
              description: >-
                When the account was last logged into using FedCM, formatted as
                a UNIX timestamp (in seconds)
              example: 1698064423
        creationTimestamp:
          type: integer
          description: >-
            When this account was created, formatted as a UNIX timestamp (in
            seconds)
          example: 1698064423
        lastUsedTimestamp:
          type: integer
          nullable: true
          description: >-
            When the account was last used by an employee, formatted as a UNIX
            timestamp (in seconds)
          example: 1698669168
    DeleteAccount:
      title: Remove Account
      type: object
      description: This object represents a removed account in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the account
          example: d6a32ba5-0532-4a66-8137-48cdf409c972
        object:
          type: string
          description: The type of object that has been removed by this operation
          example: ACCOUNT
        deleted:
          type: boolean
          description: Whether the account has been successfully removed or not
          example: true
    AccountUser:
      title: Account User
      type: object
      description: This object represents an employee in your organization.
      properties:
        employeeId:
          type: string
          description: Identifier of the employee has access to this account
          example: bf4cf562-7830-41ac-80e3-d261da1c9bb9
        lastUsedTimestamp:
          type: integer
          nullable: true
          description: >-
            When the account was last used by an employee, formatted as a UNIX
            timestamp (in seconds)
          example: 1698669223
        passwordManuallyTyped:
          type: boolean
          description: >-
            Whether the password was manually typed (or a password manager was
            used) on the last login. This value is `null` if password
            authentication is not used
          example: true
    ApprovalStatusType:
      title: ApprovalStatusType
      type: string
      enum:
        - UNDER_REVIEW
        - APPROVED
        - NOT_APPROVED
      x-enumDescriptions:
        UNDER_REVIEW: The app is under review
        APPROVED: The app has been approved
        NOT_APPROVED: The app has not been approved
      description: Approval status of the app, `null` if not set
      nullable: true
    SensitivityLevelType:
      title: SensitivityLevelType
      type: string
      enum:
        - HIGH
        - MEDIUM
        - LOW
      x-enumDescriptions:
        HIGH: The sensitivity of the app is high
        MEDIUM: The sensitivity of the app is medium
        LOW: The sensitivity of the app is low
      description: The sensitivity level of the app, `null` if not set
      nullable: true
    App:
      title: App
      type: object
      description: This object represents an app in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for this object
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        type:
          type: string
          description: The type of app, formatted as an ENUM value.
          example: ZAPIER
        approvalStatus:
          $ref: '#/components/schemas/ApprovalStatusType'
        sensitivityLevel:
          $ref: '#/components/schemas/SensitivityLevelType'
        ownerId:
          type: string
          description: Identifier of the employee who is the owner of this platform
          example: 87569da6-fb7a-4df7-8ce2-246c14044911
          nullable: true
        notes:
          type: string
          description: Notes recorded on this app
          example: 'Last security audit: 16 January 2023'
        website:
          type: string
          description: URL to the app's homepage
          example: https://zapier.com/
        description:
          type: string
          description: Description of the app's purpose
          example: >-
            Zapier is a cloud-based automation tool that enables users to
            integrate and automate various web applications without requiring
            extensive coding knowledge, potentially streamlining workflows and
            processes.
        friendlyName:
          type: string
          description: The friendly name of the app
          example: Zapier
        labels:
          type: array
          description: Labels associated with this app
          items:
            type: string
          example:
            - GenAI
            - marketing
        creationTimestamp:
          type: integer
          description: >-
            When the app was first observed, formatted as a UNIX timestamp (in
            seconds)
          example: 1698064423
    BrowserType:
      title: BrowserType
      enum:
        - CHROME
        - FIREFOX
        - EDGE
        - SAFARI
        - OPERA
        - BRAVE
        - ARC
        - ISLAND
        - PRISMA_ACCESS
        - UNKNOWN
      description: The browser used by the employee
    OSType:
      title: OSType
      enum:
        - MACOS
        - WINDOWS
        - LINUX
        - CHROME_OS
        - IOS
        - ANDROID
        - UNKNOWN
      description: The OS used by the employee
    Browser:
      title: Browser
      type: object
      nullable: true
      description: This object represents a browser of an employee in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the browser
          example: 1852b6ab-0cca-4c8d-8f14-4905497504ec
        employeeId:
          type: string
          description: Unique identifier for the employee
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        email:
          type: string
          description: Email address of the employee
          format: email
          example: john.hill@example.com
        version:
          type: string
          description: Version of the browser
          example: 125.0.0.0
        tokenType:
          type: string
          description: Type of enrollment token used
          enum:
            - INDIVIDUAL
            - TEAM
            - LANDING_PAGE
        isActive:
          type: boolean
          description: Whether the browser extension is used by a licensed employee
          example: true
        browser:
          $ref: '#/components/schemas/BrowserType'
        os:
          $ref: '#/components/schemas/OSType'
        extensionVersion:
          type: string
          description: Version of the Push extension
          example: 1.66.17
        language:
          type: string
          description: The browser language
          example: en-US
        profileEmail:
          type: string
          description: The email address of the signed in browser profile
          format: email
          example: john.hill@example.com
        profileSyncEnabled:
          type: boolean
          description: Whether synchronisation is enabled on the browser profile
          example: true
        creationTimestamp:
          type: integer
          description: >-
            When this browser object was created, formatted as a UNIX timestamp
            (in seconds)
          example: 1698669223
        lastOnlineTimestamp:
          type: integer
          description: >-
            When this browser was last seen, formatted as a UNIX timestamp (in
            seconds)
          example: 1716290202
    DeploymentMode:
      title: DeploymentMode
      type: string
      enum:
        - MANAGED
        - DEVELOPMENT
        - MANUAL
        - SIDELOAD
        - OTHER
      description: Which method was used to install this extension
    BrowserExtension:
      title: BrowserExtension
      type: object
      description: This object represents a browser extension in your organization.
      properties:
        id:
          type: string
          description: Unique ID of this browser extension record
          example: 72d0347a-2663-4ef5-b1c5-df39163f1603
        extensionId:
          type: string
          description: Static identifier for the extension.
          example: gmbgaklkmjakoegficnlkhebmhkjfich
        employeeId:
          type: string
          description: Identifier of primary employee that this extension belongs to
          example: 72d0347a-2663-4ef5-b1c5-df39163f1603
        browserId:
          type: string
          description: Identifier of the employee's Push extension
          example: 72d0347a-2663-4ef5-b1c5-df39163f1603
        name:
          type: string
          description: Name of the browser extension
          example: Privacy Badger
        description:
          type: string
          description: Description of the browser extension
          example: Privacy Badger automatically learns to block invisible trackers.
        deploymentMode:
          $ref: '#/components/schemas/DeploymentMode'
        permissions:
          type: array
          description: Permissions required by the browser extension
          items:
            type: string
          example:
            - activeTab
            - contextMenus
            - storage
        hostPermissions:
          type: array
          description: >-
            Host permissions allow extensions to interact with the URLs matching
            these patterns.
          items:
            type: string
          example:
            - https://*/*
            - http://*/*
        version:
          type: string
          description: Version of the browser extension
          example: 3.1.5.2
        versionName:
          type: string
          description: Version number shown to the user
          example: build rc2
        enabled:
          type: boolean
          description: Whether the browser extension is enabled
          example: true
        disabledReason:
          type: string
          description: Reason why the browser extension was disabled
          example: NEW_PERMISSION_REQUIRED
        updateUrl:
          type: string
          description: The URL where the browser extension gets updates from
          example: http://clients2.google.com/service/update2/crx
        homePageUrl:
          type: string
          description: Link to the browser extensions home page
          example: http://www.eff.org/
        creationTimestamp:
          type: integer
          description: >-
            When this browser extension was created, formatted as a UNIX
            timestamp (in seconds)
          example: 1698064423
        lastUpdatedTimestamp:
          type: integer
          description: >-
            When the browser extension was last used by an employee, formatted
            as a UNIX timestamp (in seconds)
          example: 1698064423
    BlockedURL:
      title: Blocked URL
      type: string
      description: >-
        This object represents a URL pattern used to block access to matching
        sites.
      example: '*://*.example.com/*'
    ControlsBlockedUrlsHostPath:
      type: object
      properties:
        host:
          type: string
          description: >-
            The host part of the URL pattern. This can be a domain or a
            subdomain. Wildcards are supported for subdomains.
          example: '*.sub.domain.com'
        path:
          type: string
          description: >-
            The path part of the URL pattern. Wildcards are supported. If not
            specified, the wildcard `*` is assumed, matching all paths for the
            given host.
          example: /path/to*
      required:
        - host
    ControlsBlockedUrlsUrl:
      type: object
      properties:
        url:
          type: string
          description: >-
            The whole URL pattern - a combination of host and path. The host can
            be a domain or a subdomain. Wildcards are supported for subdomains
            and path. If not specified, the wildcard `*` is assumed for path,
            matching all paths for the derived host.
          example: '*.sub.domain.com/path/to*'
      required:
        - url
    StolenCredential:
      title: Stolen Credential
      type: object
      description: This object represents a stolen credential.
      properties:
        email:
          type: string
          description: Email address of employee.
          example: john.hill@example.com
        password:
          type: string
          description: >-
            Plain text password. Note that uploading hashes will never match and
            only plain text passwords can be used.
          example: myAm@z!ngP4$$w0rdTh4tUcantGu3$$
        metadata:
          title: Metadata
          type: object
          nullable: true
          description: >-
            Metadata provided from the TI provider about where these credentials
            were found. This will be attached to any Stolen Credentials finding
            that matched with these credentials
    FindingType:
      title: FindingType
      type: string
      enum:
        - MFA_NOT_REGISTERED
        - REUSED_PASSWORD
        - SHARED_ACCOUNT
        - UNUSED_THIRD_PARTY_APP
        - WEAK_PASSWORD
        - LEAKED_PASSWORD
        - PASSWORD_MANAGER_NOT_USED
        - STOLEN_CREDENTIALS
      x-enumDescriptions:
        MFA_NOT_REGISTERED: This account does not have MFA.
        REUSED_PASSWORD: The password used on the account is being reused.
        SHARED_ACCOUNT: The account credentials are being shared with another employee.
        UNUSED_THIRD_PARTY_APP: The third-party integration has not been used in 90 days or more.
        WEAK_PASSWORD: The password used on the account is weak.
        LEAKED_PASSWORD: The password used on the account has been leaked in a data breach.
        PASSWORD_MANAGER_NOT_USED: >-
          The employee typically uses manually typed passwords, rather than a
          password manager.
        STOLEN_CREDENTIALS: The credentials used on the account have been identified as stolen.
      description: The type of finding
    FindingState:
      type: string
      enum:
        - OPEN
        - RESOLVED
      x-enumDescriptions:
        OPEN: The finding has been confirmed and is open.
        RESOLVED: The finding has been resolved and is no longer an issue.
      description: The state of the finding
    WeakPasswordReasonsType:
      title: FindingType
      type: string
      enum:
        - COMMON_BASE_WORD
        - BANNED_BASE_WORD
      x-enumDescriptions:
        COMMON_BASE_WORD: The base word is a derivative of top 10000 most used passwords.
        BANNED_BASE_WORD: The password is a derivative of a custom banned word.
      description: Reason a password is weak
    Finding:
      title: Finding
      type: object
      description: This object represents a finding in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the finding
          example: d6a32ba5-0532-4a66-8137-48cdf409c972
        type:
          $ref: '#/components/schemas/FindingType'
        state:
          $ref: '#/components/schemas/FindingState'
        employeeId:
          type: string
          description: >-
            ID of the employee this finding is linked to, `null` if finding is
            not linked to an employee.
          example: 379ac7ea-ff2a-42ef-af37-06d2020dc46a
          nullable: true
        passwordId:
          type: string
          description: >-
            ID of the password this finding is linked to, `null` if finding is
            not linked to a password.
          example: c4a045a1-5331-4714-af83-6a361e98960d
          nullable: true
        accountId:
          type: string
          description: >-
            ID of the account this finding is linked to, `null` if finding is
            not linked to an account.
          nullable: true
        appType:
          type: string
          description: >-
            The type of app this finding is linked to, `null` if finding is not
            linked to an app.
          example: PUSH_SECURITY
          nullable: true
        appId:
          type: string
          description: >-
            ID of the app this finding is linked to, `null` if finding is not
            linked to an app.
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
          nullable: true
        weakPasswordReasons:
          type: array
          items:
            $ref: '#/components/schemas/WeakPasswordReasonsType'
          description: Reasons a password is weak, `null` if not a WEAK_PASSWORD finding.
          nullable: true
        creationTimestamp:
          type: integer
          description: >-
            When this finding was first observed, formatted as a UNIX timestamp
            (in seconds)
          example: 1698064423
    AccountOther:
      title: Account (other)
      type: object
      description: This object represents an account (other) in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for the account
          example: 1009e8cb-497b-49ae-ac87-e083e42078d2
        employeeId:
          type: string
          description: Identifier of primary employee that this account belongs to
          example: 72d0347a-2663-4ef5-b1c5-df39163f1603
        otherAppId:
          type: string
          description: The ID of the app associated with this account
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        email:
          type: string
          description: The email address used to log into the account
          format: email
          example: john.hill@example.com
        loginMethods:
          type: object
          required:
            - passwordLogin
            - oidcLogin
            - samlLogin
            - fedCmLogin
          properties:
            passwordLogin:
              type: boolean
              description: Whether or not this account has been logged into with a password
              example: true
            oidcLogin:
              type: string
              description: >-
                The identity provider that was used to do an OIDC login on this
                account. This is `null` if no OIDC login has been performed.
              nullable: true
              example: GOOGLE_WORKSPACE
            samlLogin:
              type: string
              description: >-
                The identity provider that was used to do a SAML login on this
                account. This is `null` if no SAML login has been performed.
              nullable: true
              example: OKTA
            fedCmLogin:
              type: string
              description: >-
                The identity provider that was used to do a FedCM login on this
                account. This is `null` if no FedCM login has been performed.
              nullable: true
              example: GOOGLE_WORKSPACE
        creationTimestamp:
          type: integer
          description: >-
            When the account was first observed, formatted as a UNIX timestamp
            (in seconds)
          example: 1698064423
        lastUsedTimestamp:
          type: integer
          nullable: true
          description: >-
            When the account was last used by an employee, formatted as a UNIX
            timestamp (in seconds)
          example: 1698669168
    AppOther:
      title: App (Other)
      type: object
      description: This object represents an app (other) in your organization.
      properties:
        id:
          type: string
          description: Unique identifier for this object
          example: 35603905-ff98-4b7d-8940-eb1906a2bdf6
        domain:
          type: string
          description: >-
            Domain the user logged into. This value is null if a OIDC login is
            used
          example: app.pushsecurity.com
          nullable: true
        oauthAppId:
          type: string
          description: >-
            ID of the oauth app from the Identity Provider. This value is null
            if a password login is used.
          example: '1234567890'
          nullable: true
        name:
          type: string
          description: Name of the app. This value is null if a password login is used.
          example: Push Security
          nullable: true
        hidden:
          type: boolean
          description: Whether the app is hidden or not.
        requestSupportStatus:
          type: string
          description: Current request support status of the app
          example: DISCOVERED
        creationTimestamp:
          type: integer
          description: >-
            When the app was first observed, formatted as a UNIX timestamp (in
            seconds)
          example: 1698064423
    SeverityType:
      title: SeverityType
      enum:
        - LOW
        - MEDIUM
        - HIGH
        - CRITICAL
      description: The severity of the detection
    DetectionType:
      title: DetectionType
      enum:
        - PHISHING
        - STOLEN_CREDENTIALS
        - BLOCKED_URL
        - MALWARE_DELIVERY
      description: The type of detection
    ResponseTypeDetection:
      title: ResponseType
      enum:
        - BLOCKED
        - EMPLOYEE_IGNORED_WARNING
        - EMPLOYEE_WARNED
        - NOT_BLOCKED
      description: The response for the detection
    ClassificationType:
      title: ClassificationType
      nullable: false
      type: string
      enum:
        - NOT_SET
        - TRUE_POSITIVE
        - BENIGN_TRUE_POSITIVE
        - FALSE_POSITIVE
      description: The classification for the detection
    DetectionWithEmployee:
      title: Detection
      type: object
      description: >-
        This object represents a detection event, indicating an employee has
        triggered an alert.
      properties:
        id:
          type: string
          description: Identifier of the detection
          example: c478966c-f927-411c-b919-179832d3d50c
        employeeId:
          type: string
          description: Identifier for the employee that triggered the detection.
          example: 37cda962-7e78-49bc-8721-1becd16276a3
        employee:
          $ref: '#/components/schemas/EmployeeInEvent'
        browserId:
          type: string
          description: >-
            Identifier of the browser that was used when the detection was
            triggered.
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        severity:
          type: string
          description: The severity of the detection.
          example: HIGH
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
        detectionType:
          type: string
          description: The type of detection.
          example: PHISHING
          enum:
            - PHISHING
            - BLOCKED_URL
            - STOLEN_CREDENTIALS
            - MALWARE_DELIVERY
        response:
          type: string
          description: The response to the detection.
          example: BLOCKED
          enum:
            - BLOCKED
            - EMPLOYEE_IGNORED_WARNING
            - EMPLOYEE_WARNED
            - NOT_BLOCKED
        creationTimestamp:
          type: integer
          description: >-
            When the detection was created. Formatted as a UNIX timestamp (in
            seconds).
          example: 1698604061
        archived:
          type: boolean
          description: Whether the detection has been archived.
          example: true
    DetectionEventType:
      title: DetectionEventType
      enum:
        - PHISHING_TOOL_DETECTED
        - CLONED_LOGIN_PAGE_DETECTED
        - SSO_PASSWORD_USED
        - PROTECTED_PASSWORD_ENTERED
        - STOLEN_CREDENTIALS
        - BLOCKED_URL_VISITED
        - MALICIOUS_COPY_PASTE_DETECTED
      description: The type of detection event.
    ControlModeType:
      title: ControlModeType
      type: string
      nullable: true
      enum:
        - INFORM
        - ACKNOWLEDGE
        - REASON
        - BLOCK
        - WARN
        - MONITOR
      description: All possible ENUM values for control modes.
    ResponseTypeDetectionEvent:
      title: ResponseType
      enum:
        - BLOCKED
        - EMPLOYEE_IGNORED_WARNING
        - EMPLOYEE_WARNED
        - NOT_BLOCKED
      description: The response for the detection event.
    DetectionChildEvent:
      title: DetectionChildEvent
      type: object
      description: This object represents an event that is associated with a detection.
      properties:
        id:
          type: string
          description: Identifier of the detection event.
          example: c478966c-f927-411c-b919-179832d3d50c
        creationTimestamp:
          type: integer
          description: >-
            When the event was created. Formatted as a UNIX timestamp (in
            seconds).
          example: 1698604061
        detectionEventType:
          $ref: '#/components/schemas/DetectionEventType'
        accountId:
          type: string
          description: >-
            Identifier of the account that the detection event is associated
            with.
          example: 37cda962-7e78-49bc-8721-1becd16276a3
          nullable: true
        appType:
          type: string
          description: The type of app that the detection event is associated with.
          example: PUSH_SECURITY
          nullable: true
        phishingToolIndicator:
          type: string
          example: AITM_TOOL_EVILGINX_01
          nullable: true
        controlMode:
          $ref: '#/components/schemas/ControlModeType'
          nullable: true
        description:
          type: string
          description: >-
            The description of the detection event. Note: this is subject to
            change and should not be used to match on this object.
          example: Phishing attempt detected
          nullable: true
        clonedLoginPageIndicator:
          type: string
          example: MICROSOFT_01
          nullable: true
        response:
          $ref: '#/components/schemas/ResponseTypeDetectionEvent'
        email:
          type: string
          description: >-
            The email associated with the account related to the detection
            event.
          example: john.hill@example.com
          nullable: true
        url:
          type: string
          description: The URL that the detection event was triggered on.
          example: https://example.com/phishing
          nullable: true
        referrerUrl:
          type: string
          description: The referrer URL.
          example: https://mail.google.com
          nullable: true
        clonedLoginPageUrls:
          type: array
          items:
            type: string
          description: The legitimate login page URL that was cloned.
          example:
            - https://example.com/phishing
          nullable: true
        sourceIpAddress:
          type: string
          description: The source IP address.
          example: 8.158.25.38
        metadata:
          type: string
          description: The metadata associated with the detection event.
          example: >-
            {"source_type": "Telegram", "breach_type": "Stealer Malware Logs",
            "breach_publication_date": "2025-04-01"}
        experimental:
          type: boolean
          description: Indicates if this detection event is experimental.
          example: false
    DetectionId:
      title: Detection
      type: object
      description: >-
        This object represents a detection event, indicating an employee has
        triggered an alert.
      properties:
        id:
          type: string
          description: Identifier of the detection
          example: c478966c-f927-411c-b919-179832d3d50c
        employeeId:
          type: string
          description: Identifier for the employee that triggered the detection.
          example: 37cda962-7e78-49bc-8721-1becd16276a3
        employee:
          $ref: '#/components/schemas/EmployeeInEvent'
        browserId:
          type: string
          description: >-
            Identifier of the browser that was used when the detection was
            triggered.
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        severity:
          $ref: '#/components/schemas/SeverityType'
        detectionType:
          $ref: '#/components/schemas/DetectionType'
        response:
          $ref: '#/components/schemas/ResponseTypeDetection'
        creationTimestamp:
          type: integer
          description: >-
            When the detection was created. Formatted as a UNIX timestamp (in
            seconds).
          example: 1698604061
        archived:
          type: boolean
          description: Whether the detection has been archived.
          example: true
        classification:
          type: string
          description: The classification of the detection.
          nullable: true
          example: FALSE_POSITIVE
          enum:
            - TRUE_POSITIVE
            - BENIGN_TRUE_POSITIVE
            - FALSE_POSITIVE
        events:
          type: array
          items:
            $ref: '#/components/schemas/DetectionChildEvent'
          description: The events associated with the detection.
    Detection:
      title: Detection
      type: object
      description: >-
        This object represents a detection event, indicating an employee has
        triggered an alert.
      properties:
        id:
          type: string
          description: Identifier of the detection
          example: c478966c-f927-411c-b919-179832d3d50c
        employeeId:
          type: string
          description: Identifier for the employee that triggered the detection.
          example: 37cda962-7e78-49bc-8721-1becd16276a3
        browserId:
          type: string
          description: >-
            Identifier of the browser that was used when the detection was
            triggered.
          example: 2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0
        severity:
          type: string
          description: The severity of the detection.
          example: HIGH
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - CRITICAL
        detectionType:
          type: string
          description: The type of detection.
          example: PHISHING
          enum:
            - PHISHING
            - BLOCKED_URL
            - STOLEN_CREDENTIALS
            - MALWARE_DELIVERY
        response:
          type: string
          description: The response to the detection.
          example: BLOCKED
          enum:
            - BLOCKED
            - EMPLOYEE_IGNORED_WARNING
            - EMPLOYEE_WARNED
            - NOT_BLOCKED
        classification:
          type: string
          description: The classification of the detection.
          nullable: true
          example: FALSE_POSITIVE
          enum:
            - TRUE_POSITIVE
            - BENIGN_TRUE_POSITIVE
            - FALSE_POSITIVE
        creationTimestamp:
          type: integer
          description: >-
            When the detection was created. Formatted as a UNIX timestamp (in
            seconds).
          example: 1698604061
        archived:
          type: boolean
          description: Whether the detection has been archived.
          example: true
x-internal: false
tags:
  - name: Accounts
    description: >-
      These objects represent the accounts (owned by employees) in your
      organization.
  - name: Accounts (Other)
    description: >-
      These objects represent the accounts (other) (owned by employees) in your
      organization.
  - name: Apps
    description: >-
      These objects represent the apps that have been found in your
      organization.
  - name: Apps (Other)
    description: >-
      These objects represent the apps (other) that have been found in your
      organization.
  - name: URL blocking
    description: These objects represent the blocked URLs configured in your organization.
  - name: Browsers
    description: >-
      These objects represent the browsers (used by employees) in your
      organization.
  - name: Employees
    description: These objects represent the employees in your organization.
  - name: Findings
    description: >-
      These objects represent the findings that have been found in your
      organization.
  - name: Stolen credential detection
    description: >-
      Manage custom stolen credentials that you have added to your organization
      for monitoring and enforcement.
x-tagGroups:
  - name: Entities
    tags:
      - Accounts
      - Accounts (Other)
      - Apps
      - Apps (Other)
      - Browsers
      - Browser Extensions
      - Detections
      - Employees
      - Findings
  - name: Controls
    tags:
      - URL blocking
      - Stolen credential detection
security:
  - x-api-key: []
