Important

   

This version of the product has reached end of support. The documentation is available for your convenience. However, you must be logged in to access it. You will not be able to leave comments.

Users API

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

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


GET /v3.0/users


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 (name, lastSuccessfulLoginTimestamp, role, or a listable user dynamic field name) in the specified order (prefix with a '+' for ascending or a '-' for descending)

"+name"

string
Enum: [
  "+name",
  "-name",
  "+lastSuccessfulLoginTimestamp",
  "-lastSuccessfulLoginTimestamp",
  "+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 the specified user is not logged in


403

Forbidden: Not allowed to access users


500

Internal server error: Unexpected exception occurred


POST /v3.0/users


Parameters

Name

Located in

Description

Default

Schema

body

body

Complete attributes of the new user


#UserDTO

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 new user is invalid


401

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


403

Forbidden: Not allowed to add a new user


500

Internal server error: Unexpected exception occurred


GET /v3.0/users/all_logged_in_users


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

[
   #LoggedInUserDTO
]

401

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


403

Forbidden: Not allowed to access users


500

Internal server error: Unexpected exception occurred


DELETE /v3.0/users/login_session/{sessionId}


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


GET /v3.0/users/{nameOrKey}


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

#UserDTO

401

Unauthorized: Failed to provide a suitable Authorization header 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


PUT /v3.0/users/{nameOrKey}


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


#UserDTO

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

#UserDTO

400

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


401

Unauthorized: Failed to provide a suitable Authorization header 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


DELETE /v3.0/users/{nameOrKey}


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


PATCH /v3.0/users/{nameOrKey}


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


#JsonPatch

Authorization

header

Authorization token formatted as 'Bearer [token]'


string*

Responses

Code

Description

Schema

200

successful operation

#UserDTO

400

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


401

Unauthorized: Failed to provide a suitable Authorization header 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



Object Definitions

Object

Schema

ComponentId



{
    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
 
    componentType: string*
    The type of the component, used to verify what is retrieved by key/name; valid values are: Combogroup, Condition, Configuration, Device, DynamicField, EmailDistributionList, Group, Keyword, Model, OsImage, Realm, 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: key=deviceName, value=name of the device the configuration belongs to; 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



{
    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)
}

JsonPatch



[
    A list of JSON Patch operations
 
     #JsonPatch.OneOperation
  ]

JsonPatch.OneOperation

JsonPatch.Pointer



string
  Pointer or path to an element or property

JsonPatch.Add



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

JsonPatch.Remove



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

JsonPatch.Replace



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

JsonPatch.Move



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

JsonPatch.Copy



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

JsonPatch.Test



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

LoggedInUserDTO



{
    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)
 
    username: string
    The user's name
}

UserDTO



{
    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
 
    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
 
    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
    ]
}

Was this page helpful? Yes No Submitting... Thank you

Comments