Synack users API

openapi: 3.1.0
info:
  title: Assessment Service Assessment Groups users API
  version: 1.0.0
  description: 'APIs for managing Assessment and related operations on the Synack.

    '
  contact:
    name: Synack Engineering
    email: engineering@synack.com
servers:
- url: https://client.synack.com/api/assessment
  description: Commercial
- url: https://client.synack.us/api/assessment
  description: FedRAMP (Medium)
security:
- bearerAuth: []
tags:
- name: users
  description: Users of credentials.
paths:
  /v2/user-role-credentials/{credentialUid}/assigned-users/{userUid}:
    parameters:
    - $ref: '#/components/parameters/CredentialUIDPath'
    - $ref: '#/components/parameters/UserUIDPath'
    put:
      x-excluded: true
      operationId: putUserRoleCredentialUser
      tags:
      - users
      description: Assign a user to a user-role credential. Credentials with sharing of "one" will return a 409 status code when a request is received to add further users. Credentials with sharing of "all" will return a 409 status code on any request to add users. There is not limit to the number of users that may be added for sharing of "many".
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
    delete:
      x-excluded: true
      operationId: deleteUserRoleCredentialUser
      tags:
      - users
      description: Remove a user from a user-role credential.
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gw
        - asset_client_ow
        - asset_boss_ow
        - asset_client_lw
        - asset_boss_lw
  /v2/user-role-credentials:
    parameters:
    - in: query
      name: organizationUid
      schema:
        $ref: '#/components/schemas/OrganizationUID'
      required: true
      description: Unique identifier for an organization.
    - in: query
      name: listingUid
      schema:
        $ref: '#/components/schemas/ListingUID'
      required: true
      description: Unique identifier for a listing.
    - in: query
      name: userUid
      schema:
        $ref: '#/components/schemas/UserUID'
      required: true
      description: Unique identifier for a user.
    post:
      x-excluded: true
      operationId: assignUserRoleCredentialsToUser
      tags:
      - users
      description: Assign user role credentials to a user for mobile application or web application assets in a listing.
      responses:
        '200':
          description: The assignments occurred successfully
        '204':
          $ref: '#/components/responses/204NoContent'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '409':
          $ref: '#/components/responses/409Conflict'
        '500':
          $ref: '#/components/responses/500InternalServerError'
        '503':
          $ref: '#/components/responses/503ServiceUnavailable'
      security:
      - OAuth2:
        - asset_gr
        - asset_or
        - asset_lr
        - asset_srt_lr
  /v1/users/whoami:
    get:
      operationId: getCurrentUser
      summary: Get current user information
      description: Retrieve information about the currently authenticated user
      tags:
      - users
      responses:
        '200':
          description: User information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
  /v1/users:
    get:
      tags:
      - users
      summary: Fetch users
      description: Fetch all organization users (members & admins). Banned users will not be included. Requires admin privileges.
      responses:
        '200':
          description: Successfully fetched users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      tags:
      - users
      summary: Create a new member/admin
      description: Create a new member/admin and grant it access to assessments (if any). Requires admin privileges.
      requestBody:
        description: Request body.
        content:
          application/json:
            schema:
              required:
              - email
              type: object
              properties:
                email:
                  type: string
                  description: E-mail address for the user
                first_name:
                  type: string
                  description: First name of the user
                last_name:
                  type: string
                  description: Last name of the user
                admin:
                  type: boolean
                  description: Flag to indicate whether to grant admin privileges
                  default: false
                assessments:
                  type: array
                  description: IDs of assessments to grant user access to
                  items:
                    type: string
                send_invite:
                  type: boolean
                  description: Flag to indicate whether to send the user the invitation URL by e-mail
                  default: true
        required: true
      responses:
        '201':
          description: The newly created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Payload includes unpermitted parameters, given assessment IDs are invalid or user creation failed (e.g. e-mail already exists)
          content: {}
        '403':
          description: The requesting party does not have admin privileges
          content: {}
  /v1/users/{id}:
    get:
      tags:
      - users
      summary: Fetch user account
      description: Fetch information about a user account. Requires admin privileges.
      parameters:
      - name: id
        in: path
        description: ID of the user
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully got users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: No such user
          content: {}
    put:
      tags:
      - users
      summary: Update user account status
      description: Update existing user (reactivate and/or grant admin privileges). The user is automatically notified by e-mail upon account reactivation. Requires admin privileges.
      parameters:
      - name: id
        in: path
        description: ID of the user
        required: true
        schema:
          type: string
      - name: admin
        in: query
        description: Flag to indicate whether to grant/remove admin privileges
        schema:
          type: boolean
      - name: reactivate
        in: query
        description: Flag to indicate whether to reactivate (unban) the user
        schema:
          type: boolean
      responses:
        '200':
          description: The updated created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Payload includes unpermitted parameters
          content: {}
        '403':
          description: The requesting party does not have admin privileges
          content: {}
        '404':
          description: No such user
          content: {}
    delete:
      tags:
      - users
      summary: Ban/delete user
      description: Ban/delete a user account. Requires admin privileges.
      parameters:
      - name: id
        in: path
        description: ID of the user
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully banned user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
            application/xml:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          description: The requesting party does not have admin privileges
          content: {}
        '404':
          description: No such user
          content: {}
components:
  responses:
    403Forbidden:
      description: Forbidden
    500InternalServerError:
      description: Internal Server Error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    409Conflict:
      description: Conflict.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    404NotFound:
      description: Not found.
    503ServiceUnavailable:
      description: Service Unavailable.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    204NoContent:
      description: No content.
    401Unauthorized:
      description: Unauthorized.
  schemas:
    ProblemDetails:
      type: object
      description: 'See [RFC 7807: Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807)'
      properties:
        type:
          type: string
          readOnly: true
        title:
          type: string
          readOnly: true
        status:
          type: integer
          format: int32
          minimum: 100
          maximum: 511
          description: HTTP Status code.
          readOnly: true
        detail:
          type: string
          description: Message detailing the problem.
          readOnly: true
        instance:
          type: string
          description: generated problem instance number to correlate with logs
          readOnly: true
        failedValidation:
          type: array
          description: Array of failed validation rules.
          readOnly: true
          items:
            $ref: '#/components/schemas/FailedValidation'
        failedValidations:
          type: array
          description: Array of indexed failed validation rules.
          readOnly: true
          items:
            $ref: '#/components/schemas/IndexedFailedValidations'
        maxBatchSize:
          type: integer
          description: Maximum processable batch size.
          readOnly: true
        batchSize:
          type: integer
          description: Batch size sent when batch is too large.
          readOnly: true
    IndexedFailedValidations:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based index indicating the which item in request containing an array of items has failed validation.
          readOnly: true
        failedValidation:
          type: array
          description: Array of failed validation rules.
          readOnly: true
          items:
            $ref: '#/components/schemas/FailedValidation'
    UID:
      type: string
      pattern: ^[0-9a-f]{12}
      readOnly: true
      description: Unique Identifier.
    FailedValidation:
      type: object
      required:
      - message
      properties:
        property:
          type: string
          readOnly: true
        value:
          type: string
          readOnly: true
        message:
          type: string
          readOnly: true
    OrganizationUID:
      type: string
      pattern: ^[-_0-9a-z]{1,50}
      description: Unique identifier for an organization.
    UserUID:
      type: string
      pattern: ^[-_0-9a-z]{1,100}
      description: Unique identifier for a user.
    ListingUID:
      type: string
      pattern: ^[-_0-9a-z]{1,50}
      description: Unique identifier for an listing.
      readOnly: true
    User:
      required:
      - assessment_ids
      - banned
      - email
      - id
      type: object
      properties:
        id:
          type: integer
          format: int64
        email:
          type: string
          description: e-mail address of the user
        assessment_ids:
          type: array
          description: IDs of assessments the user has access to
          items:
            type: string
        admin:
          type: boolean
          description: boolean flag to indicate whether the user has admin privileges (only visible to admin
        invite_url:
          type: string
          description: invitation URL (only visible to admins)
        banned:
          type: boolean
          description: boolean flag to indicate whether the user has been banned
  parameters:
    CredentialUIDPath:
      name: credentialUid
      in: path
      schema:
        $ref: '#/components/schemas/UID'
      required: true
      description: Unique identifier for an asset credential.
    UserUIDPath:
      name: userUid
      in: path
      schema:
        type: string
      required: true
      description: Unique identifier for a user.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT