Skip to main content

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 groupLimit
Auth endpoints30 requests/minute
Scan creation10 requests/minute
Webhook testing5 requests/minute
API key generation5 requests/minute
All other endpoints200 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": "user@example.com",
  "password": "your-password"
}

POST /api/v1/auth/register​

Create a new user account.

Request body:

{
  "email": "user@example.com",
  "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:

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems 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