API Reference

The Trusera platform exposes a REST API at /api/v1/. All endpoints (except auth, health, and SSO callbacks) require authentication via JWT token or API key.

Base URL: https://your-instance.trusera.dev/api/v1

Authentication

Headers

Authorization: Bearer <jwt_token>

Or with an API key:

Authorization: Bearer tsk_<api_key>

Rate limits

Endpoint group	Limit
Auth endpoints	30 requests/minute
Scan creation	10 requests/minute
Webhook testing	5 requests/minute
API key generation	5 requests/minute
All other endpoints	200 requests/minute

Health

`GET /api/v1/health`

Health check endpoint. No authentication required.

`GET /api/v1/metrics`

Application metrics. No authentication required.

Auth endpoints

`POST /api/v1/auth/login`

Authenticate with email and password. Returns JWT tokens.

Request body:

{
  "email": "[email protected]",
  "password": "your-password"
}

`POST /api/v1/auth/register`

Create a new user account.

Request body:

{
  "email": "[email protected]",
  "password": "your-password",
  "name": "User Name"
}

`GET /api/v1/auth/me`

Get the current authenticated user profile.

Required role: Any authenticated user

`PUT /api/v1/auth/profile`

Update the authenticated user's profile.

Required role: Any authenticated user

`PUT /api/v1/auth/password`

Change the authenticated user's password.

Required role: Any authenticated user

`POST /api/v1/auth/api-key`

Generate a new API key.

Required role: Any authenticated user

Response:

{
  "key": "tsk_abc123...",
  "id": "uuid",
  "name": "My CI Key",
  "created_at": "2026-01-15T10:00:00Z"
}

The full key is only returned once at creation time.

`GET /api/v1/auth/api-keys`

List all API keys for the authenticated user.

`DELETE /api/v1/auth/api-key/:keyId`

Delete an API key.

`POST /api/v1/auth/api-key/:keyId/revoke`

Revoke an API key (soft disable).

`POST /api/v1/auth/refresh`

Refresh the JWT access token.

`POST /api/v1/auth/logout`

Invalidate the current session.

`POST /api/v1/auth/onboarding-complete`

Mark user onboarding as complete.

`DELETE /api/v1/auth/account`

Delete the authenticated user's account.

Scans

`POST /api/v1/scans`

Create a new scan.

Required role: Analyst or higher

Request body:

{
  "target": "/path/to/scan",
  "deep": false,
  "n8n_url": null,
  "n8n_api_key": null
}

`GET /api/v1/scans`

List all scans. Supports pagination.

Query parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20)

`GET /api/v1/scans/:id`

Get a specific scan by ID.

`GET /api/v1/scans/:id/components`

List all components found in a scan.

`GET /api/v1/scans/:id/graph`

Get the dependency graph for a scan. Returns nodes and edges for visualization.

`GET /api/v1/scans/:id/compliance`

Get compliance evaluation results for a scan.

`GET /api/v1/scans/:id/compare/:otherId`

Compare two scans and return the differences (added, removed, changed components).

`POST /api/v1/scans/:id/export`

Export a scan in the specified format.

Request body:

{
  "format": "cyclonedx"
}

Supported formats: cyclonedx, sarif, spdx3, html, csv, markdown, junit

Compliance

`GET /api/v1/scans/:id/compliance`

Get compliance results for a scan, evaluated against all active frameworks.

`POST /api/v1/compliance/rules`

Create a custom compliance rule.

Required role: Editor or higher

Request body:

{
  "name": "No hardcoded keys",
  "description": "Block scans with hardcoded API keys",
  "framework": "custom",
  "condition": {
    "field": "flags",
    "operator": "contains",
    "value": "hardcoded_api_key"
  },
  "severity": "critical"
}

`GET /api/v1/compliance/rules`

List all custom compliance rules.

`PUT /api/v1/compliance/rules/:id`

Update a custom compliance rule.

Required role: Editor or higher

`DELETE /api/v1/compliance/rules/:id`

Delete a custom compliance rule.

Required role: Editor or higher

Policies

`POST /api/v1/policies`

Create a new policy.

Required role: Editor or higher

`GET /api/v1/policies`

List all policies.

`GET /api/v1/policies/:id`

Get a specific policy.

`PUT /api/v1/policies/:id`

Update a policy.

Required role: Editor or higher

`DELETE /api/v1/policies/:id`

Delete a policy.

Required role: Admin only

`POST /api/v1/scans/:id/evaluate`

Evaluate a scan against all active policies.

Required role: Analyst or higher

`GET /api/v1/scans/:id/violations`

Get policy violations for a scan.

`GET /api/v1/scans/:id/evaluations`

Get all policy evaluations for a scan.

`GET /api/v1/policies/:id/evaluations`

Get all evaluations for a specific policy.

Dashboard

`GET /api/v1/dashboard/overview`

Get dashboard overview data including recent scans, severity distribution, and trend data.

Required role: Any authenticated user

Schedules

`POST /api/v1/schedules`

Create a scheduled scan.

Required role: Editor or higher

`GET /api/v1/schedules`

List all scheduled scans.

`PUT /api/v1/schedules/:id`

Update a scheduled scan.

Required role: Editor or higher

`DELETE /api/v1/schedules/:id`

Delete a scheduled scan.

Required role: Admin only

Organizations

`POST /api/v1/organizations`

Create an organization.

`GET /api/v1/organizations`

List organizations.

`GET /api/v1/organizations/:orgId`

Get organization details.

`DELETE /api/v1/organizations/:orgId`

Delete an organization.

Required role: Admin only

`POST /api/v1/organizations/:orgId/members`

Add a member to an organization.

Required role: Admin only

`GET /api/v1/organizations/:orgId/members`

List organization members.

`DELETE /api/v1/organizations/:orgId/members/:userId`

Remove a member from an organization.

Required role: Admin only

SSO / OIDC

`PUT /api/v1/organizations/:orgId/sso`

Configure SSO for an organization.

Required role: Admin only

`GET /api/v1/organizations/:orgId/sso`

Get SSO configuration.

`POST /api/v1/organizations/:orgId/sso/toggle`

Enable or disable SSO.

Required role: Admin only

`DELETE /api/v1/organizations/:orgId/sso`

Remove SSO configuration.

Required role: Admin only

Public SSO endpoints (no auth required):

GET /api/v1/sso/:orgSlug/check - Check if SSO is enabled for an org
GET /api/v1/sso/:orgSlug/login - Initiate OIDC login flow
GET /api/v1/sso/:orgSlug/callback - OIDC callback handler

Webhooks

`POST /api/v1/webhooks`

Create a webhook.

Required role: Admin only

Request body:

{
  "url": "https://example.com/webhook",
  "events": ["scan.completed", "alert.triggered"],
  "secret": "optional-signing-secret"
}

`GET /api/v1/webhooks`

List all webhooks.

`GET /api/v1/webhooks/:id`

Get webhook details.

`PUT /api/v1/webhooks/:id`

Update a webhook.

Required role: Admin only

`DELETE /api/v1/webhooks/:id`

Delete a webhook.

Required role: Admin only

`GET /api/v1/webhooks/:id/deliveries`

List delivery history for a webhook.

`POST /api/v1/webhooks/:id/test`

Send a test webhook delivery.

Required role: Admin only

Alert Rules and Alerts

`POST /api/v1/alert-rules`

Create an alert rule.

Required role: Admin only

`GET /api/v1/alert-rules`

List all alert rules.

`GET /api/v1/alert-rules/:id`

Get an alert rule.

`PUT /api/v1/alert-rules/:id`

Update an alert rule.

Required role: Admin only

`DELETE /api/v1/alert-rules/:id`

Delete an alert rule.

Required role: Admin only

`GET /api/v1/alerts`

List all triggered alerts.

`GET /api/v1/alerts/:id`

Get alert details.

`POST /api/v1/alerts/:id/acknowledge`

Acknowledge an alert.

Required role: Analyst or higher

`POST /api/v1/alerts/:id/resolve`

Resolve an alert.

Required role: Analyst or higher

Connectors

`POST /api/v1/connectors/n8n/credentials`

Save n8n instance credentials for scanning.

Required role: Editor or higher

Request body:

{
  "name": "Production n8n",
  "url": "https://n8n.example.com",
  "api_key": "n8n-api-key"
}

`GET /api/v1/connectors/n8n/credentials`

List saved n8n credentials.

Required role: Analyst or higher

`DELETE /api/v1/connectors/n8n/credentials/:id`

Delete saved n8n credentials.

Required role: Editor or higher

`POST /api/v1/connectors/n8n/test`

Test connectivity to an n8n instance.

Required role: Analyst or higher

Audit Log

`GET /api/v1/audit-log`

Query the audit log.

Required role: Admin only

`DELETE /api/v1/audit-log/cleanup`

Clean up old audit log entries.

Required role: Admin only

WebSocket

`GET /api/v1/ws`

WebSocket endpoint for real-time scan progress updates. Authentication is passed via query parameter.

wss://your-instance.trusera.dev/api/v1/ws?token=<jwt_token>

Messages are JSON-encoded and include scan progress events, completion notifications, and error reports.

Internal endpoints

These endpoints are used by the scanner service and require a separate internal API key (not JWT).

`POST /api/v1/internal/scans/:id/result`

Submit scan results from the scanner service.

Authentication: Internal API key header

Authentication
- Headers
- Rate limits
Health
- GET /api/v1/health
- GET /api/v1/metrics
Auth endpoints
Scans
Compliance
Policies
Dashboard
- GET /api/v1/dashboard/overview
Schedules
Organizations
SSO / OIDC
Webhooks
Alert Rules and Alerts
Connectors
Audit Log
- GET /api/v1/audit-log
- DELETE /api/v1/audit-log/cleanup
WebSocket
- GET /api/v1/ws
Internal endpoints
- POST /api/v1/internal/scans/:id/result

Authentication​

Headers​

Rate limits​

Health​

GET /api/v1/health​

GET /api/v1/metrics​

Auth endpoints​

POST /api/v1/auth/login​

POST /api/v1/auth/register​

GET /api/v1/auth/me​

PUT /api/v1/auth/profile​

PUT /api/v1/auth/password​

POST /api/v1/auth/api-key​

GET /api/v1/auth/api-keys​

DELETE /api/v1/auth/api-key/:keyId​

POST /api/v1/auth/api-key/:keyId/revoke​

POST /api/v1/auth/refresh​

POST /api/v1/auth/logout​

POST /api/v1/auth/onboarding-complete​

DELETE /api/v1/auth/account​

Scans​

POST /api/v1/scans​

GET /api/v1/scans​

GET /api/v1/scans/:id​

GET /api/v1/scans/:id/components​

GET /api/v1/scans/:id/graph​

GET /api/v1/scans/:id/compliance​

GET /api/v1/scans/:id/compare/:otherId​

POST /api/v1/scans/:id/export​

Compliance​

GET /api/v1/scans/:id/compliance​

POST /api/v1/compliance/rules​

GET /api/v1/compliance/rules​

PUT /api/v1/compliance/rules/:id​

DELETE /api/v1/compliance/rules/:id​

Policies​

POST /api/v1/policies​

GET /api/v1/policies​

GET /api/v1/policies/:id​

PUT /api/v1/policies/:id​

DELETE /api/v1/policies/:id​

POST /api/v1/scans/:id/evaluate​

GET /api/v1/scans/:id/violations​

GET /api/v1/scans/:id/evaluations​

GET /api/v1/policies/:id/evaluations​

Dashboard​

GET /api/v1/dashboard/overview​

Schedules​

POST /api/v1/schedules​

GET /api/v1/schedules​

PUT /api/v1/schedules/:id​

DELETE /api/v1/schedules/:id​

Organizations​

POST /api/v1/organizations​

GET /api/v1/organizations​

GET /api/v1/organizations/:orgId​

DELETE /api/v1/organizations/:orgId​

POST /api/v1/organizations/:orgId/members​

GET /api/v1/organizations/:orgId/members​

DELETE /api/v1/organizations/:orgId/members/:userId​

SSO / OIDC​

PUT /api/v1/organizations/:orgId/sso​

GET /api/v1/organizations/:orgId/sso​

POST /api/v1/organizations/:orgId/sso/toggle​

DELETE /api/v1/organizations/:orgId/sso​

Public SSO endpoints (no auth required):​

Webhooks​

POST /api/v1/webhooks​

GET /api/v1/webhooks​

GET /api/v1/webhooks/:id​

PUT /api/v1/webhooks/:id​

DELETE /api/v1/webhooks/:id​

GET /api/v1/webhooks/:id/deliveries​

POST /api/v1/webhooks/:id/test​

Alert Rules and Alerts​

POST /api/v1/alert-rules​

GET /api/v1/alert-rules​

GET /api/v1/alert-rules/:id​

PUT /api/v1/alert-rules/:id​

DELETE /api/v1/alert-rules/:id​

Authentication

Headers

Rate limits

Health

`GET /api/v1/health`

`GET /api/v1/metrics`

Auth endpoints

`POST /api/v1/auth/login`

`POST /api/v1/auth/register`

`GET /api/v1/auth/me`

`PUT /api/v1/auth/profile`

`PUT /api/v1/auth/password`

`POST /api/v1/auth/api-key`

`GET /api/v1/auth/api-keys`

`DELETE /api/v1/auth/api-key/:keyId`

`POST /api/v1/auth/api-key/:keyId/revoke`

`POST /api/v1/auth/refresh`

`POST /api/v1/auth/logout`

`POST /api/v1/auth/onboarding-complete`

`DELETE /api/v1/auth/account`

Scans

`POST /api/v1/scans`

`GET /api/v1/scans`

`GET /api/v1/scans/:id`

`GET /api/v1/scans/:id/components`

`GET /api/v1/scans/:id/graph`

`GET /api/v1/scans/:id/compliance`

`GET /api/v1/scans/:id/compare/:otherId`

`POST /api/v1/scans/:id/export`

Compliance

`GET /api/v1/scans/:id/compliance`

`POST /api/v1/compliance/rules`

`GET /api/v1/compliance/rules`

`PUT /api/v1/compliance/rules/:id`

`DELETE /api/v1/compliance/rules/:id`

Policies

`POST /api/v1/policies`

`GET /api/v1/policies`

`GET /api/v1/policies/:id`

`PUT /api/v1/policies/:id`

`DELETE /api/v1/policies/:id`

`POST /api/v1/scans/:id/evaluate`

`GET /api/v1/scans/:id/violations`

`GET /api/v1/scans/:id/evaluations`

`GET /api/v1/policies/:id/evaluations`

Dashboard

`GET /api/v1/dashboard/overview`

Schedules

`POST /api/v1/schedules`

`GET /api/v1/schedules`

`PUT /api/v1/schedules/:id`

`DELETE /api/v1/schedules/:id`

Organizations

`POST /api/v1/organizations`

`GET /api/v1/organizations`

`GET /api/v1/organizations/:orgId`

`DELETE /api/v1/organizations/:orgId`

`POST /api/v1/organizations/:orgId/members`

`GET /api/v1/organizations/:orgId/members`

`DELETE /api/v1/organizations/:orgId/members/:userId`

SSO / OIDC

`PUT /api/v1/organizations/:orgId/sso`

`GET /api/v1/organizations/:orgId/sso`

`POST /api/v1/organizations/:orgId/sso/toggle`

`DELETE /api/v1/organizations/:orgId/sso`

Public SSO endpoints (no auth required):

Webhooks

`POST /api/v1/webhooks`

`GET /api/v1/webhooks`

`GET /api/v1/webhooks/:id`

`PUT /api/v1/webhooks/:id`

`DELETE /api/v1/webhooks/:id`

`GET /api/v1/webhooks/:id/deliveries`

`POST /api/v1/webhooks/:id/test`

Alert Rules and Alerts

`POST /api/v1/alert-rules`

`GET /api/v1/alert-rules`

`GET /api/v1/alert-rules/:id`

`PUT /api/v1/alert-rules/:id`

`DELETE /api/v1/alert-rules/:id`