How To Use the OpenAPI Integration | ObjectSecurity OT.AI Platform

To facilitate a transparent user experience and to enable full third-party integration with the ObjectSecurity OT.AI Platform, OpenAPI Initiative functionality is natively integrated into the platform.

The "OpenAPI Page" details the API routes for interacting with the OT.AI Platform. The API routes, corresponding description, and 'Send" button are all listed on the left panel. Clicking the "Send" button queries the route, producing output on the right panel. Additionally, you may toggle between different API routes via a dropdown menu:

Additionally, some API routes require additional parameters or arguments. These parameters and arguments are listed on the left panel if needed:

External Usage

Our API may also be queried externally from any network connection with access to your deployment. Depending on your deployment type, the URL used to query the routes will differ.

Offline/On-Prem Virtual Machine:

Typically, an Offline/On-Prem virtual machine will be accessible via localhost. In this case, the following URL format will suffice:

https://localhost/rbui/<route>

If your On-Prem virtual machine is hosted on a private network, the following URL format will suffice, with ip_address referring to the IP address of your deployment on your local network.

https://<ip_address>/rbui/<route>

(The <route> here refers to any route described in the Available Routes section.)

Cloud Deployment:

For Cloud Deployments, the API will be accessible from anywhere on the Internet. The following URL will be used, with deployment_name referring to the name of your cloud deployment.

https://<deployment_name>.objectsecurity.io/rbui/<route>

(The <route> here refers to any route described in the Available Routes section.)

Note on bearer token:

Most OT.AI Platform API routes require a Bearer authentication token. You can learn to get this Bearer token under Authentication in the Available Routes section.

You can read more about Bearer tokens here.

Available Routes

This section provides a general overview of the purpose and output of each route. Information regarding the specific parameters and exact output schema can be found in the application itself.

General:

General routes handle the most basic usage of the OT.AI Platform, mainly including fetching data to view.

• GET /assessor/getassets
  You can use this route to get a list of your assets. Assets have a set of binaries that have each been analyzed.

• POST /assessor/getbinaries
  Use this route to get the set of analyzed binaries in a given asset.

• POST /assessor/getresults
  Use this route to get analysis results for a given binary.
  

• POST /assessor/getcwe
  Get additional information on specific CWEs.
  

Assessments & Analysis:

These routes handle the analysis process, including the ability to queue up and start various assessments.

• GET /assessor/getassetprogress
  Gets the current analysis progress of all ongoing analyses in the user's current organization. 

• GET /assessor/listbinaries
  Gets the set of binaries uploaded to the dropzone.

• POST /saas/addfile
  Uploads a binary to the dropzone. 

• POST /saas/rmfile
  Removes a binary from the dropzone.
  

• POST /saas/start
  Starts the analysis procedure on the binaries in the dropzone. 

Asset Management:

These routes handle the managing of assets after they have been analyzed. Various actions can be taken on assets, including deleting or updating multiple asset fields.

• GET /assessor/getnumnew
  Gets the number of new assets in an organization. New assets are those that haven't been viewed yet after being analyzed. 

• POST /assessor/deleteasset
  Deletes an asset from an organization. 

• POST /assessor/renameasset
  Renames an asset.

• POST /assessor/update/assetdescription
  Updates an asset's description.

• POST /assessor/updateassettype
  Updates an asset's type.
  
  

• POST /assessor/markassetviewed
  Marks an asset as viewed.

• GET /saas/asset/{assetid}/audit
  Gets the audit log for an asset. 

Facility Management:

These routes handle the management of facilities. Facilities each have a location and set of child assets located within the facility.

• GET /assessor/getfacilities
  Gets all the facilities in the organization. 

• POST /assessor/createfacility
  Creates a new facility.

• POST /assessor/updatefacility
  Updates an existing facility. 

• GET /assessor/getassetsinfacility/{facility_id}
  Get the assets in a facility.

• GET /assessor/deletefacility/{facility_id}
  Deletes a facility. 

• GET /assessor/getdefaultfacility
  Each organization has a default facility that cannot be deleted. All assets in an organization are analyzed in this default facility by default.

Authentication:

Authentication routes manage user login, role-based querying, and 2FA.

• POST /saas/mfalogin
  Gets an "access_token" that may be set as the Bearer Token when calling the "/saas/validate_totp" route. This route acts as the first factor of 2-factor authentication. "/saas/validate_totp" acts as the second factor. 

• GET /saas/generate_totp
  Generates a time-based one-time password for the current user. This TOTP can be converted into a QR code and scanned with Google Authenticator for 2 Factor Authentication.

• POST /saas/validate_totp
  Validates a user's time-based one-time password and returns to them a token that may be set as the Bearer Token when accessing all other routes of the API. This route acts as the second factor of 2-factor authentication, with "/saas/mfalogin" being the first. 

• POST /saas/auth/user/add
  Creates a new user.

• POST /saas/auth/password
  Updates a user's password. 

• GET /saas/auth/userinvite/user/{user_id}
  Invites a user to the server. Returns a token specific to the "user_id" set in the API route. The token may be redeemed by the user using the "/saas/auth/userinvite/redeem/{invite}" route. 

• GET /saas/auth/userinvite/redeem/{invite}
  Redeems an invite generated using the "/auth/userinvite/user/{user_id}" route. Returns a token that may be used to set up a new account. 

• POST /saas/auth/user/eula/accept
  Accepts the EULA for the calling user. 

• GET /saas/auth/user/{userid}/profile
  Gets a user's profile.

Organization Management:

These routes handle the managing of organizations. Organizations each have a set of child facilities and a set of child users. Organizations may have multiple administrators. The server SUPERADMIN is a part of every organization, and there may only ever be one SUPERADMIN at a time.

• GET /assessor/getdashboard
  Gets the data needed to generate the dashboard on the UI. 

• GET /saas/auth/userall
  Gets all the users in an organization. 

• POST /saas/auth/user/addroles
  Assigns a user new roles in an organization. This is equivalent to adding a user to an organization, should the user not already have roles in the organization.

• POST /saas/auth/user/removeroles
  Remove roles from a user in an organization. This is equivalent to removing a user from an organization, should the user not have any remaining roles in the organization after this route has been called. 

• POST /saas/auth/user/setorg
  Swaps the org a user is currently viewing.  

• POST /saas/auth/organization/add
  Adds an organization.

• POST /saas/auth/organization/update
  Updates an organization.

• GET /saas/org/audit
  Gets the audit log of an organization. The audit log tracks the history of all analyzed assets in the organization.