v4.0 Users API

TrueSight Network Automation REST API – UserService
The base URL for the API is:

https://serverName:portNumber/bca-networks/api

users

{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/users
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

filter.name

query

Filter for users matching this name, asterisk wildcards allowed


string

orderBy

query

Sort by the specified attribute (enabledFlag, lastSuccessfulLoginTimestamp, name, role, or a listable user dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+name"

string 
Enum: [
 "+enabledFlag",
 "-enabledFlag",
 "+lastSuccessfulLoginTimestamp",
 "-lastSuccessfulLoginTimestamp",
 "+name",
 "-name",
 "+role",
 "-role"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of users to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

[ 
  UserDTO
]

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access users


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/users
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new user


copyPreferencesFromUser

query

Name or database key of an existing user whose preferences (containing saved views) are to be copied into the new user's preferences; when present, the new user gets a copy of the existing user's views, which the new user is free to manipulate thereafter without affecting the existing user; when null, the new user starts out with no preferences or views


string

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

201

Created: New user successfully added


400

Bad request: Input user DTO is missing or the new user is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to add a new user


404

Not found: No single matching accessible copyPreferencesFromUser found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/users/all_logged_in_users
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

orderBy

query

Sort by the specified attribute (username, emailAddress, loginTimestamp, loggedInFromAddress, minutesIdle, roles, or sessionType) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+userName"

string 
Enum: [
 "+username",
 "-username",
 "+emailAddress",
 "-emailAddress",
 "+loginTimestamp",
 "-loginTimestamp",
 "+loggedInFromAddress",
 "-loggedInFromAddress",
 "+minutesIdle",
 "-minutesIdle",
 "+roles",
 "-roles",
 "+sessionType",
 "-sessionType"
]

offset

query

Return the specified page number

1

integer

limit

query

Define the number of rows in a page or the maximum number of user sessions to return

25

integer

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access users


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/users/current_logged_in_user
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/users/current_logged_in_user/granted_rights
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/users/current_logged_in_user/page_sizes
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

{ 
}

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Yellow" title="PUT"/}}

 /v4.0/users/current_logged_in_user/page_sizes/{listName}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

listName

path

The name of the component list whose page size is being updated


string * 
Enum: [
 "aclSearchReport",
 "changeSummaryReport",
 "compliancySummaryReport",
 "combogroups",
 "conditions",
 "configExports",
 "configImports",
 "configurationComparisonReport",
 "configurationSearchReport",
 "customActionCapturedResults",
 "customActionIndexPivotedCapturedResults",
 "deviceAdapters",
 "deviceAdapterCapabilitiesReport",
 "deviceAgentInfo",
 "deviceImports",
 "deviceInventoryReport",
 "devices",
 "deviceSecurityProfiles",
 "discrepancySummaryReport",
 "dynamicFields",
 "emailDistributions",
 "events",
 "eventReceivers",
 "externalEventFilters",
 "externalLinks",
 "groups",
 "itemResults",
 "jobApprovalTypes",
 "jobConflictsReport",
 "jobDetails",
 "jobs",
 "jobSummaryReportChanges",
 "keywords",
 "loginSession",
 "osImageHistoryReport",
 "osImages",
 "policies",
 "predefinedJobs",
 "quarantineReport",
 "realms",
 "remoteFileServers",
 "reportActivity",
 "roles",
 "ruleExports",
 "ruleImports",
 "rules",
 "ruleSets",
 "securityVulnerabilities",
 "securityVulnerabilityImporters",
 "snmpManagers",
 "substitutionParameters",
 "templateGroups",
 "transcriptComparisonReport",
 "transcriptSearchReport",
 "users"
]

size

query

The new value for the page size, which will be used whenever the component list is displayed


integer *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

400

Bad request: Input listName or size is missing or invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Yellow" title="PUT"/}}

 /v4.0/users/current_logged_in_user/password
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

oldPassword

formData

The current password of who is logged in


string *

newPassword

formData

The new password of who is logged in


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

400

Bad request: Input old password is incorrect, input new password is invalid or has already been used, or the system is using external authentication (and thus does not maintain passwords)


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Red" title="DELETE"/}}

 /v4.0/users/login_session/{sessionId}
Click here to expand...


Description

Forces a user to be logged out; if a web service session is terminated, the session will complete any currently active API call.

Parameters

Name

Located in

Description

Default

Schema

sessionId

path

Identifier of the login session to be terminated


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


String *

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: The login session cannot be terminated; cannot terminate your own session


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to terminate a login session


404

Not found: No matching login session found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Blue" title="GET"/}}

 /v4.0/users/{nameOrKey}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the user of interest


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to access users


404

Not found: No single matching accessible user found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Yellow" title="PUT"/}}

 /v4.0/users/{nameOrKey}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the user to be modified


string *

body

body

Complete new attribute values for the user; anything left out will be considered to be null and will be nulled out in the user; any required dynamic fields missing or null in the input will revert to default values


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input user DTO is missing or modified user is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to modify the user


404

Not found: No single matching accessible user found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Red" title="DELETE"/}}

 /v4.0/users/{nameOrKey}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the user to be deleted


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

string

400

Bad request: User is currently in use, or it is a root user who cannot be deleted


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to delete the user


404

Not found: No single matching accessible user found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Yellow" title="PATCH"/}}

 /v4.0/users/{nameOrKey}
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the user to be modified


string *

body

body

New attribute values for the user, in JSON Patch format


Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

200

successful operation

400

Bad request: Input JSON patch information is missing or modified user is invalid


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to modify the user


404

Not found: No single matching accessible user found


500

Internal server error: Unexpected exception occurred


{{status subtle="false" colour="Green" title="POST"/}}

 /v4.0/users/{nameOrKey}/release
Click here to expand...


Parameters

Name

Located in

Description

Default

Schema

nameOrKey

path

Name or database key of the user to be released


string *

Authorization

header

Authorization token formatted as 'Bearer [token]'


string *

Responses

Code

Description

Schema

400

Bad request: User is not locked


401

Unauthorized: Failed to provide a suitable Authorization header or accessToken cookie, or the specified user is not logged in


403

Forbidden: Not allowed to release or unlock the user


404

Not found: No single matching accessible user found


500

Internal server error: Unexpected exception occurred

Object Definitions

Object

Schema

ComponentId


Click here to expand...


{ 
    id: string 
    The database key of the component; an incoming component can be identified either by its database key, or by its unique name, or by its name with qualifiers which are unique when combined; when this database key is present, it takes precedence and componentName and qualifiers(when present) are used to verify the retrieved component 

     componentName: string 
    The name of the component; an incoming component can be identified either by its database key, or by its unique name, or by its name with qualifiers which are unique when combined; this name is used to verify any component retrieved by database key, and is used if there is no database key or if the database key fails to resolve; for componentType Configuration and HardwareInventory, componentName is the created timestamp (in milliseconds); for componentType SecurityVulnerability, componentName is the securityVulnerabilityID; for componentType SnmpManagerStation, componentName is the address 

     componentType: string * 
    The type of the component, used to verify what is retrieved by key/name; valid values are: Combogroup, Condition, Configuration, Device, DeviceAdapter, DeviceAgent, DeviceSecurityProfile DynamicField, EmailDistributionList, Group, HardwareInventory, JobApprovalType, Keyword, Model, OsImage, PredefinedJob, Realm, RemoteFileServer, Role, Rule, RuleSet, SecurityVulnerability, SnmpManagerStation, Template, and User 

     qualifiers: { 
      Any additional single qualifier needed to identify the component uniquely, when the name alone is not sufficient; the map key is the extra attribute name string; the map value string completes the identification of the component; for componentType Configuration and HardwareInventory: key=deviceKey, value=database key of the device the item belongs to, key=deviceName, value=name of the device the item belongs to, key=timestamp, value=creation date/time in server display format; for componentType DeviceAdapter: key=adapterType, value=type of the device adapter, key=parent, value=parent or owner used for organizing certain types of adapters, key=vendorName, value=name of the vendor that owns a device type; for componentType DynamicField: key=type, value=base class name of the component associated with the dynamic field; for componentType Group, ComboGroup: key=realmName, value=name of the realm the group belongs to; for componentType Model: key=vendorGuid, value=the vendor GUID; for componentType OsImage: key=filename, value=name of the file(s) making up the image; for componentType SecurityVulnerability: key=vendorGuid, value=the vendor GUID 
    } 
}

DynamicFieldValueDTO


Click here to expand...


{ 
    id: string 
    The database key of the dynamic field whose value this is (read-only) 

     name: string 
    The name of the dynamic field (read-only) 

     values: [ 
      The value(s) for the dynamic field; for a single-value field, only the first entry is relevant; read-only for Auto Derived and Configuration Profiled types 

       string 
    ] 

     dynamicFieldDetailsLink: string 
    Link to get more detailed information about the dynamic field (read-only) 
}

GrantedNetworkRightsDTO


Click here to expand...


{ 
    realm: ComponentId
    The realm that has network rights 

     rights: [ 
      The network rights the user is granted in the realm via the roles the user belongs to 

       string 
    ] 
}

GrantedRightsDTO


Click here to expand...


{ 
    fullNetworkRightsFlag: boolean 
    Whether or not the user is granted full network rights; when true, the user is granted all network rights in all realms, so the networkRights and networkRightsInAnyRealm fields are null 

     networkRights: [ 
      The network rights the user is granted per realm via the roles the user belongs to 

       GrantedNetworkRightsDTO      ] 

     networkRightsInAnyRealm: [ 
      The network rights the user is granted in any realm, across all roles the user belongs to, which includes rights granted via group ACLs 

       string 
    ] 

     systemRights: [ 
      The system rights the user is granted via the roles the user belongs to 

       string 
    ] 
}

JsonPatch


Click here to expand...


[ 
    A list of JSON Patch operations 

     JsonPatch.OneOperation
  ]

JsonPatch.OneOperation

JsonPatch.Pointer


Click here to expand...


string 
  Pointer or path to an element or property

JsonPatch.Add


Click here to expand...


{ 
    op: string * 
   Enum: [
     "add"
   ]
    value: any * 
    path: JsonPatch.Pointer*
}

JsonPatch.Remove


Click here to expand...


{ 
    op: string * 
   Enum: [
     "remove"
   ]
    path: JsonPatch.Pointer*
}

JsonPatch.Replace


Click here to expand...


{ 
    op: string * 
   Enum: [
     "replace"
   ]
    value: any * 
    path: JsonPatch.Pointer*
}

JsonPatch.Move


Click here to expand...


{ 
    op: string * 
   Enum: [
     "move"
   ]
    path: JsonPatch.Pointer*
    from: JsonPatch.Pointer*
}

JsonPatch.Copy


Click here to expand...


{ 
    op: string * 
   Enum: [
     "copy"
   ]
    path: JsonPatch.Pointer*
    from: JsonPatch.Pointer*
}

JsonPatch.Test

Click here to expand...


{ 
    op: string * 
   Enum: [
     "test"
   ]
    value: any * 
    path: JsonPatch.Pointer*
}

LoggedInUserDTO

Click here to expand...


{ 
    sessionID: string 
    The unique identifier for this login session, which can be used to terminate this session 

     emailAddress: string 
    The user's e-mail address 

     loggedInFromAddress: string 
    Where the user logged in from 

     loginTimestamp: date-time 
    When the user logged into the systemexample = 2018-01-31T13:45:00.000+0000 

     minutesIdle: integer 
    How long this session has been idle or inactive 

     roles: string 
    Role(s) to which this user belongs 

     sessionType: string 
    What type of session this is (GUI, SSH proxy, or web services); if this session is executing a web services call, also contains what call is being executed 

     username: string 
    The user's name 
}

UserDTO

Click here to expand...


{ 
    id: string 
    The user's unique database key (read-only) 

     name: string * 
    The user's unique display name and login username; cannot be modified after creation 

     accountCreatedOnTimestamp: date-time 
    When the user was created (read-only) 
    Example: 2018-01-31T13:45:00.000+0000

     canCopyFlag: boolean 
    Whether or not the logged-in user is allowed to copy this user (read-only) 

     canDeleteFlag: boolean 
    Whether or not the logged-in user is allowed to delete this user (read-only) 

     canEditFlag: boolean 
    Whether or not the logged-in user is allowed to edit this user (read-only) 

     emailAddress: string * 
    The e-mail address of the user, for receiving reports and other exported information and for job approval requests 

     enabledFlag: boolean 
    Whether or not the user account is enabled; when not enabled, the user cannot log in 

     forcePasswordChangeFlag: boolean 
    Whether or not the user must change his password the next time he logs in to the user interface; ignored when external authentication is in use; during create and update requests, this flag is automatically set in the resulting user when appropriate; note this flag is enabled any time user A creates or changes the password of user B, even when user B is set for no password expiration, to ensure user A does not know user B's password 

     isLockedFlag: boolean 
    Whether or not this user is currently locked out from logging in (read-only) 

     lastPasswordChangeTimestamp: date-time 
    When the password was last changed; null when external authentication is in use (read-only) 
    Example: 2018-01-31T13:45:00.000+0000

     lastSuccessfulLoginTimestamp: date-time 
    When the user last logged in; null when user has never logged in (read-only) 
    Example: 2018-01-31T13:45:00.000+0000

     password: string 
    The user's login password; required when local authentication is in use; ignored when external authentication is in use 

     passwordEncryptedFlag: boolean 
    Whether or not the password is encrypted 

     passwordNeverExpiresFlag: boolean 
    Whether or not the password expires and must be changed; when false, the password expires per the 'Require Users to Change Passwords After' system parameter; when true, the password does not expire and the system parameter does not apply; ignored when external authentication is in use 

     roles: [ 
      The role(s) this user belongs to, which grant access to devices and functionality; a user must be associated with at least one role 

       ComponentId
    ] * 

     rootAccountFlag: boolean 
    Whether or not this is a root account as defined during installation; you cannot add a root account; you cannot disable or delete a root account; and a root account must always be associated with the Administrator role (read-only) 

     dynamicFields: [ 
      The dynamic fields 

       DynamicFieldValueDTO
    ] 
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*