Getting Started

API Feature

This page contains information to assist our customers with utilizing the Application Programming Interface (API) feature in RegScale. It describes what it is, why you would use it, the benefits, and provides instructions on getting started.

What is it?

APIs are a common way of interchanging data between systems. It is commonly used to securely transfer data between systems in a machine-readable format.

Why would you use it?

APIs are an efficient mechanism for collecting data from your authoritative systems of record into RegScale. There are many reasons to use this feature which include:

• Centralized audit/assessment evidence collection for auditors
• Automating assessments using DevOps techniques
• Visualizing data within RegScale in external tools (i.e. PowerBI)
• Collecting external data for use within RegScale
• Exporting RegScale data for use by external tools

What are the benefits?

This feature has multiple benefits for an organization; to include:

• Eliminates manual data entry processes between systems
• Allows automation of manual audit processes to lower costs
• Data is transferred securely and in a controlled manner; reducing risk of data loss or exposure
• Allows aggregation of compliance data into a single source of truth for rollup reporting
• Allows exporting data for custom reporting

How do I use it?

Instructions for using this feature are provided below:

• The first step is to get your current Bearer Token (a JSON Web Token) or to create a new one within RegScale. To get your existing token, click your name in the top right and select "My Profile". Navigate below the toolbar and you will see the "Current Access Token" shown; see screenshot below:

If you click the "copy" icon on the screen above, it will automatically paste your token to your clipboard where you can paste it in your code or API call. If you are accessing APIs programmatically, you can call the login API as follows:
- Navigate to your RegScale URL + /api/authentication/login
- Pass the username and password to this URL which will return a token dynamically
- Store this token in your script/code to access RegScale APIs based on your authorization level

• The Bearer token will have the permissions of the currently logged in user. You will only have the ability to perform actions that you are authorized for within the application. Tokens expire within 24 hours of login.
• Once the Bearer token is obtained, you can browse the RegScale APIs using our Swagger page. To view the APIs, click your name in the top right and select "APIs". See screenshot below:

• Swagger is a standards-based way for visualizing and interacting with APIs. It follows the OpenAPI specification (OAS) and provides an interactive website for testing APIs.
• The first step to using the RegScale APIs via Swagger is to Authorize yourself. To do this, copy the Bearer token from the previous section then click the "Authorize" button and paste the token into the textbox to complete the authorization. See screenshot below:

• Once you have authorized Swagger, you can interact with any of the list of APIs available within RegScale.
• Click any available API to view the configuration details.
• Where applicable, you can provide inputs to the API to allow for testing.
• Once ready, click the "Execute" button to get the results of the API call.
• Swagger will return the Curl command to call this API via command line, the URL to call (i.e. via PostMan or Python), the results of the API call, and the headers associated with the call. See screenshot below for an example:

• Every piece of functionality available in the RegScale User Interface (UI) is also available programatically via real-time API.
• Swagger can be used to test and verify functionality prior to beginning actual coding for integrations.

Relating Records

RegScale has a flexible underlying system that allows any record to be related to another. This functionality is accomplished via the use of key value pairs such as ParentModule and ParentId where the Id is the primary key of the record to relate and the module corresponds to the RegScale module being related. The table below shows the list of RegScale modules along with the value to store in ParentModule to establish the parent child relationship:

Module	Value	Module ID #
Assessment	assessments	2
Asset	assets	3
Case	cases	28
Catalogue	catalogues	4
Causal Analysis	causalanalysis	24
Changes	changes	31
Component	components	27
Control	security-controls	5
Control Implementation	controls	15
Data Call	datacalls	6
Exception	exceptions	7
Evidence Locker	evidence	32
Incident	incidents	8
Interconnect	interconnects	9
Issue (POAM)	issues	10
Policy	policies	11
Project	projects	12
Questionnaire	questionnaires	26
Requirement	requirements	13
Risk	risks	14
Security Plan	securityplans	16
Security Profile	profiles	17
Supply Chain (Contract)	supplychain	25
Task	tasks	18
Threat	threats	19

NOTE: Security Controls are a child to catalogues. Security Control Implementations are an instance of a security control for a given security plan or component that has a specific implementation.

NOTE: Click the Modules menu bar item in RegScale to generally see the module list above. Some modules not in the list may only be available to Administrators and Maintainer roles