API Administration

Welcome to the API Administration Documentation. Below we outline various topics of interest to Agency Administrators in overseeing the API. For API design information see the API Documentation. For the API schema definitions, please open the System, CAD, Records or Jail links on the home page to navigate to the appropriate Swagger page.

Creating API Users

The first step in creating a new interface is to grant API access to the appropriate user(s).

The first decision to be made is if the vendor needs a dedicated "system user" for their server or if officers will log into the other system and use their ProSuite user for interface activity. Let's look at a couple of examples.

Scenario 1: System Level Users

You are building an interface to export Jail data to another system. Booking data is exported in real time every time it changes.

In this scenario you will want to use a system user, since the vendor's server will be following a stream of updates and processing the data.

Scenario 2: Personnel Level Users

You are building an interface to provide police and fire agencies additional capabilities in the field.

Fire units will be able to send CAD a command to indicate a fire has been controlled.
Law Units will be able to download CFS information.
Law supervisors will be able to set units to off duty status and change which personnel is associated with a unit.

In this scenario you will want to use officer users, since each Personnel entry already has distinct permissions for their role which will error if the user attempts to do tasks that are beyond their permissions e.g. if the fire unit tries to download CFS information, their user would not have permission and thus would error.

Note that a server model COULD be made to work in this scenario; the vendor could build their own permission scheme and have the agency manually keep the configuration in sync with ProSuite. However, this might require additional development effort from the vendor and additional configuration effort from the agency.

System Users special behaviors:

They do NOT have a forced password reset every 90 days like normal users. This is to ensure the interface doesn't suddenly stop working in the middle of operations.
Changing password every 90 days is a CJIS requirement. This means you need to establish a process with the vendor to update the password periodically. Typically you will want to schedule a time to update the password that will have minimal disruption to your operations.
System users are NOT able to login to ProSuite. As these users are intended to be a server rather than a person, it doesn't make sense to allow access to the application. If access to both the API and ProSuite is needed, consider making them not a system user instead.
System users can always set permissions on an individual basis even if the system is configured to require permissions be assigned at the group level. All interfaces need different access, so this ensures appropriate permissions can always be provided without forcing a group creation for a single user.
System users are not required to setup Multi-factor Authentication if used by your agency. Since these users are a server contacting the API rather than a person, they would not have a cell phone to complete the passcode generation process. It is recommended to use server-focused security mechanisms such as Host Key Fingerprinting or setting up a VPN connection between the servers if you need to provide an additional layer of security for these users.

Implementing Users in the ProSuite Personnel Module

The best implementation is going to depend on the specifics of the interface and the 3rd party capabilities. Generally, if there is a desire to make use of the ProSuite permissions, an Officer user may be better whereas for a server sending or receiving updates a system user will be optimal.

Once you have determined whether to create a system user or to grant API access to various personnel, you can do so in the Personnel module by granting the Public Safety Suite Professional API access in Sign In Credentials Section. Once API access has been granted, another checkbox will appear allowing you to designate them a system user.

PermissionsExample

API users work otherwise exactly like all other users and can be managed the same.

Permissions

Once your user(s) are created, they then need to have permissions assigned. API users have an extra tab on the Personnel screen for API Endpoint Access. You can assign permissions to call a given endpoint grouping on this screen.

Open permissions grant access to GET and POST /search endpoints and allow the vendor to view and export data.
Edit permissions grant access to POST and PUT endpoints and allow the vendor to create, update and import data.
Same as Permissions button in the personnel module can be used to assign the same level of access to the API as was granted to the ProSuite User.

Note that it is a security best practice to grant the smallest possible permission set (PoLP - Principle of Least Privilege). That way if the user's credentials are ever compromised, the malicious party will have as little access as possible. If you are unsure which permissions are NEEDED by the interface, it is recommended to start with the specific record type they need to access, and grant additional permissions as need for them is discovered through the development process. For example, if you are building a CFS interface start with CFS - Open, and if it is discovered you need the vehicle details later, you can grant access to Vehicle Card - Open.

API Documentation

Once the user has been created and permissions assigned, you should provide this website to the vendor along with the credentials for their system user, if applicable, Vendors can then read up on the documentation and access the Swagger pages with the endpoint technical details. They can also make test calls via the Swagger page.

For import interfaces, it is recommended to provide the vendor the training server's page at first so that any test calls do not disrupt your live operations. Only migrate the interface to production once the interface is working as expected.

Auditing the API

API activity can be reviewed and audited in several locations:

Each API authentication appears in the User Login Activity alongside the other access methods.
Each call appears in the audit trail of the record(s) accessed.
These can also be reviewed in the Audit Trail Search.

It may be valuable to create a user login activity report to monitor unexpected API access. Once created, the report can be hosted on your dashboard so that you can keep an eye on any access coming from unusual places or in unusual patterns. This can reduce the detection time required to notice a breach, which in turn can dramatically reduce damages from the unauthorized access.

Additional Logging & Debug Mode

Additional logging is collected for API errors and is stored on the API server for a short duration (up to ~2 weeks). Typically this information includes a stacktrace about the error or indicates the database field or rule that was violated. This data is not exposed via the UI due to technical security reasons but is available to CentralSquare staff should there be a need to debug an issue with the API.

The API also features a debug mode which can be enabled for each endpoint family. While debug mode is enabled, we archive the ingress (what the vendor sends us) and egress (what we send the vendor) files. This can be helpful for debugging situations where it is unclear what data is being exchanged. Certain endpoints may also generate additional logs when debug mode is enabled.

Limit use of Debug Mode

As debug mode may use a lot of memory from archiving two files per API call, it is important that it not remain on for an extended period so as to not cause server memory issues. Be sure to turn it off after generating any needed files.

Endpoint Settings

Each endpoint family has its own settings in ProSuite that can modify the behavior of the related endpoints. You can access this via System Admin -> System/CAD/RMS/Jail API Configurations.

This is where you can enable/configure:

Debug mode
Default Values
How long to wait for a webhook to be considered historical
The Maximum Pagination for POST /search endpoints
Accident & Citation fields for the API
Accidents and Citations have the ability to configure the report fields and behaviors from here. You can set the values to be used in the UI and the endpoints by filling out the table. It is advised to only make changes in coordination with your vendor. e.g. if you rename a field, and they are not aware, that field will stop working until they make the corresponding change on their end.

Webhook Subscription Management

With appropriate permissions, vendors can create webhook subscriptions to be notified when a new or updated record is available. Vendors can update or delete these subscriptions via the appropriate endpoints.

As an administrator, with the Subscriptions - Open Others permission you can audit which webhook subscriptions exist by navigating to Workflow Rules inside ProSuite and then clicking the link on the left menu Manage API Subscriptions. This will load the list of all active webhook subscriptions. Should you see an outdated, or problematic subscription, you can delete it from this screen.

Data Breach Response

Should a user's credentials become compromised, you should open their personnel record and immediately change their password. This will prevent the compromised credentials from being used.

You can also revoke their API access or Endpoint Access permissions. This is recommended if you know a compromise has occurred but the computer or network has not been secured yet. This way, even if the officer has malicious software on their machine that gets the officers new password as quickly as you can change it, you can prevent their user from making any calls while you discover the nature of the breach and secure things.

Once things are secured and the officer has their new password (and, if applicable, restored permissions/access), be sure to review the user login activity and audit trail to determine what records were viewed or modified.