openapi: 3.0.3
info:
  version: 0.0.1
  title: CyCognito API V1 Reference Assets Users API
  description: 'The CyCognito API V1 is a REST API that allows you to post and get data from our main data entities—assets and issues. You can also manage the scope of your attack surface, attribute assets to organizations, and verify the identity of IP scans on your assets. Our legacy API (V0) documentation is available for download [here](https://platform.cycognito.com/CyCognito-API-V0-Reference.pdf). While V0 is still being supported, please note that this API is undergoing deprecation.

    | Code | Name | Description |

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

    | 200 | OK | Success |

    | 400 | Bad Request | The request is malformed—e.g., the body cannot be properly parsed, expected fields are not included in the body, or unsupported request header values. |

    | 403 | Access Restricted | There are insufficient permissions or a valid API key was not provided. |

    | 404 | Not Found | The provided resource was not found. |

    | 405 | Method Not Allowed | The HTTP method is not allowed for the given resource. |

    | 415 | Unsupported Media Type | The request content type is not supported. |

    | 5XX | | Server failure |  |

    '
tags:
- name: Users
paths:
  /v1/users:
    get:
      description: Get user data for all users registered in your CyCognito account.
      security:
      - apiAuth: []
      summary: Get all user data
      tags:
      - Users
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      description: The user's full name.
                      type: string
                      example: Marty McFly
                    email:
                      description: The user's email address.
                      type: string
                      example: marty@acme.com
                    roles:
                      description: 'Indicates the user''s permission levels corresponding to their teams. In the following example, the user has IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: {"Team1": "it-user", "Team2":"admin", "":""viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
                      type: object
                      additionalProperties:
                        type: string
                      example: "{\n  \"Team1\": \"it-user\",\n  \"Team2\": \"admin\",\n  \"\": \"viewer\"\n}"
                    activated:
                      description: Indicates whether or not the user has activated their account.
                      type: boolean
                      example: 'true'
                    invited-at:
                      description: Indicates the date and time at which the user received an invitation to the CyCognito platform.
                      anyOf:
                      - type: string
                        format: date-time
                      - type: 'null'
                      example: '2024-05-18T09:29:26.259Z'
                    invited-by:
                      description: The user who sent the invitation to the specified user.
                      type: string
                      example: Biff Tannen
                    last-login:
                      description: Indicates the date and time at which the user last signed in to the CyCognito platform.
                      anyOf:
                      - type: string
                        format: date-time
                      - type: string
                      - type: 'null'
                      example: 2024-05-20T10:31.368Z
                  required:
                  - name
                  - email
                  - roles
                  - activated
                  - invited-by
                  - last-login
    post:
      description: Create a new user.
      security:
      - apiAuth: []
      summary: Create user
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: The full name of the new user.
                  type: string
                  example: Marty McFly
                email:
                  description: The new user's email address.
                  type: string
                  example: marty@acme.com
                roles:
                  description: 'Designates the new user''s permission levels corresponding to their teams. In the following example, the new user will have IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: `{"Team1": "it-user", "Team2":"admin", "":"viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
                  type: object
                  additionalProperties:
                    type: string
                    enum:
                    - viewer
                    - it-user
                    - admin
                    - analyst
                    - guest
                  example: "{\n  \"Team1\": \"it-user\",\n  \"Team2\": \"admin\",\n  \"\": \"viewer\"\n}"
              required:
              - name
              - email
              - roles
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Indicates whether a new user was successfully added and an invitation was sent.
                    type: string
                    example: New user invitation was sent
                required:
                - status
  /v1/users/{email}:
    get:
      description: Get user data for the specified individual user.
      security:
      - apiAuth: []
      summary: Get individual user data
      tags:
      - Users
      parameters:
      - name: email
        in: path
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - type: object
                  properties:
                    name:
                      description: The user's full name.
                      type: string
                      example: Marty McFly
                    email:
                      description: The user's email address.
                      type: string
                      example: marty@acme.com
                    roles:
                      description: 'Indicates the user''s permission levels corresponding to their teams. In the following example, the user has IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: {"Team1": "it-user", "Team2":"admin", "":""viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
                      type: object
                      additionalProperties:
                        type: string
                      example: "{\n  \"Team1\": \"it-user\",\n  \"Team2\": \"admin\",\n  \"\": \"viewer\"\n}"
                    activated:
                      description: Indicates whether or not the user has activated their account.
                      type: boolean
                      example: 'true'
                    invited-at:
                      description: Indicates the date and time at which the user received an invitation to the CyCognito platform.
                      type: string
                      format: date-time
                      example: '2024-05-18T09:29:26.259Z'
                    invited-by:
                      description: The user who sent the invitation to the specified user.
                      type: string
                      example: Biff Tannen
                    last-login:
                      description: Indicates the date and time at which the user last signed in to the CyCognito platform.
                      anyOf:
                      - type: string
                        format: date-time
                      - type: string
                      - type: 'null'
                      example: 2024-05-20T10:31.368Z
                  required:
                  - name
                  - email
                  - roles
                  - activated
                  - invited-at
                  - invited-by
                  - last-login
                - type: string
    put:
      description: Edit single teams or roles for the specified user.
      security:
      - apiAuth: []
      summary: Edit single user teams or roles
      tags:
      - Users
      parameters:
      - name: email
        in: path
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  description: 'Designates the new user''s permission levels corresponding to their teams. In the following example, the new user will have IT user permissions in Team1, Admin permissions in Team2, and Viewer permissions in all other teams: {"Team1": "it-user", "Team2":"admin", "":"viewer"}`. Supported user roles are *admin*, *viewer*, *guest*, *it-user*, and *analyst-ext*. <span name="kb-user-roles-explanation">Read more</span>.'
                  type: object
                  additionalProperties:
                    type: string
                    enum:
                    - viewer
                    - it-user
                    - admin
                    - analyst
                    - guest
                  example: "{\n  \"Team1\": \"it-user\",\n  \"Team2\": \"admin\",\n  \"\": \"viewer\"\n}"
              required:
              - roles
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Indicates whether the user's role within the specified team was updated.
                    type: string
                    example: User was edited.
                required:
                - status
    delete:
      description: Remove a CyCognito user from the current team associated with <span name="kb-api-key-management-link">your API key</span>.
      security:
      - apiAuth: []
      summary: Delete user
      tags:
      - Users
      parameters:
      - name: email
        in: path
        schema:
          type: string
        required: true
        description: The email of the user who you want to remove from the current team associated with <span name="kb-api-key-management-link">your API key</span>.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: Indicates whether a user was successfully removed from the team.
                    type: string
                    example: User was deleted
                required:
                - status
components:
  securitySchemes:
    apiAuth:
      type: apiKey
      name: Authorization
      in: header