RegScale API Documentation

The RegScale API enables secure, real-time integration with external systems. This guide explains what the API is, how to use it, authentication methods, security features, and record relationships.

Authentication

All RegScale API calls require a JSON Web Token (JWT) for authorization. Include the token in the Authorization header of each request:

HTTP

Authorization: Bearer <auth_token>

Method 1: API Login

Send a POST request to:

/api/authentication/login

Request body:

JSON

{
  "username": "your_username",
  "password": "your_password",
  "oldPassword": ""
}

The response includes an auth_token and user details. Use this token in subsequent API requests.

Method 2: Copy from User Profile

1. In RegScale, click your name in the top right → My Profile
2. Scroll to Current Access Token
3. Click the copy icon

Tokens are valid for 24 hours and carry the permissions of the authenticated user.

Method 3: Service Accounts

Administrators can create service accounts for long-term, automated integrations:

• Navigate to Admin Panel → Setup → Service Accounts
• Set a name, purpose, and expiration
• Copy the generated token for use in code or secure storage

These tokens inherit Administrator privileges and do not consume user licenses.

---

Security

JWT Validation

• JWTs are signed server-side to prevent tampering
• Include user roles and metadata used for access control
• Expire based on the configured session timeout

Role-Based Access

RegScale APIs enforce two levels of access control:

• Authentication required: Most endpoints require a valid JWT
• Role required: Some endpoints require specific roles for access

Unauthorized requests return 401 (unauthenticated) or 403 (unauthorized) errors. Roles are assigned by system administrators and take effect upon the user’s next login.

---

API Explorer (Swagger)

To interact with the RegScale API using Swagger:

1. Click your name → APIs
2. Click Authorize
3. Paste your Bearer token

Swagger allows you to:

• Browse available endpoints
• Submit test inputs
• Execute requests
• View request/response data, curl commands, and headers

Swagger follows the OpenAPI specification and is useful for development and testing.

---

Relating Records

RegScale supports relationships between records using the ParentModule and ParentId fields:

JSON

{
  "ParentModule": "<module_value>",
  "ParentId": "<record_id>"
}

Module Mapping

Module	Value	ID
Assessment	assessments	2
Assessment Plans	assessmentplans	33
Asset	assets	3
Capability	capabilities	37
Case	cases	28
Categorization	categorization	29
Catalogue	catalogues	4
Causal Analysis	causalanalysis	24
Changes	changes	31
Component	components	27
Continuous Monitoring	continuousmonitoring	30
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
Program	programs	36
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
Threat Model	threatmodels	35

Notes:

• Security Controls are children of Catalogues.
• Control Implementations are tied to a Security Plan or Component.

Some modules may only be available to administrators.