OpenAPI Specification
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