16 REST API

The REST API lets scripts and other systems read and maintain TraxrGRC records without the browser: loading risks from a spreadsheet, exporting compliance status to a dashboard, or creating incidents from a ticketing tool. It is used by developers and administrators who build such integrations. This chapter explains how access works and what is available; the machine-readable reference is the OpenAPI document, served at /api/v1/openapi on your installation. That address needs no token, so you can load it into an OpenAPI viewer or a client generator directly.

The API covers the main records of each module. Some screens have no API equivalent, among them Settings, the Report Center and its CSV downloads, and the Dashboard.

16.1 Authentication

API requests use bearer tokens:

  1. A user with Create on API tokens (an administrator, by default) creates a token in Settings → API Tokens (see Administration & Settings). Give it a name, an optional expiry date, and the module scopes it may use.
  2. The full token, starting with aat_, is shown once, at creation. Copy it somewhere safe. TraxrGRC stores only a hash of it.
  3. Send it on every request in the Authorization header:
curl -H "Authorization: Bearer aat_your_token_here" \
  https://grc.example.com/api/v1/risks

A request is refused in these cases:

StatusBodyCause
401{ "error": "unauthorized" }No token, an unknown token, or a token that is revoked or expired; also a token whose creator has been deleted or deactivated.
403{ "error": "forbidden" }The token's scopes do not include the module and right the request needs, or its creator no longer holds that right.

Revoked or expired tokens stop working immediately. Every refused request is recorded in the Audit Log (module security, action permission.denied) with the reason and the token.

16.2 Conventions

TopicBehavior
Base URL/api/v1 on your installation's address.
FormatJSON request and response bodies.
Success envelope{ "data": ... }. A create returns status 201 with { "data": { "id": "..." } }.
Error envelope{ "error": "..." } with an HTTP status: 400 for invalid input (invalid-input), 401 unauthenticated, 403 forbidden, 404 not found, 409 for a conflict with the record's current state, and a short message for other refusals.
ListsPaginated with page (from 1) and pageSize (default 25, at most 200), for example GET /api/v1/risks?page=2&pageSize=50. The data is { rows, total, page, pageSize }.
IdentityA token acts as the user who created it. That user's permissions apply on top of the token's scopes, including the own ownership level, so a list returns only the records the creator could see in the browser.
Scope of side effectsScopes bound everything a request does. A request that also touches another module (a DPIA creating a risk, a record linked to a vendor) needs that module's right in the token's scopes too, or it is refused (403, or 404 for a link to a record the token cannot read).
AuditAPI changes are recorded in the Audit Log like any other change, naming both the token and its creator.
NotificationsChanges made through the API send no notification rule emails unless an administrator turns this on (see Notifications in Administration & Settings).

16.3 What is available

Each operation in the OpenAPI document states the scope it requires, for example "Requires the API token scope risks:read". The scope names match the role permission names: reading needs Read on the module, and changes need Create, Update, Delete or Review as described in the module's chapter.

AreaPaths under /api/v1Covers
Risks/risks, /risk-classifications, /risk-scaleRisks with computed scores, treatments, reviews; the classification list and the risk scale (changing those needs Settings rights)
Controls/controlsControls and their tests
Assets/assetsThe asset catalog
Business units/business-unitsThe business unit hierarchy
Compliance/compliance/packages, /compliance/analyses, /compliance/poamPackages and their items, analyses and their exceptions, the POA&M register (read; ?status=, ?severity=, ?source=, ?overdue=true)
Policies/policiesPolicies, content, versions, reviews and approvals recorded outside the app
Third parties/third-partiesThird parties, contacts, linked risks, sub-processors and transfer impact assessments
Incidents/incidentsIncidents, closing, breach details and breach notifications
Audits/auditsAudit plans and findings
Projects/projectsProjects
Awareness/awareness/programs, /awareness/resultsPrograms, test submissions and results
Data privacy/data-privacyRecords of processing, transfers, links, reviews, the Article 30 register and DPIAs
Account reviews/account-reviewsReview programs, their items and CSV import
Assessments/assessments/templates, /assessments/requestsQuestionnaire templates and requests
Custom fields/custom-fieldsField definitions and per-record values
Evidence/evidenceEvidence and reports, their links, files with SHA-256 (list, upload, download with an X-Content-SHA256 header, remove), locking and unlocking, Verify files, and the auditor package (/evidence/package, a zip)

Consult the OpenAPI document for the exact paths, parameters, request bodies and responses.