Security & Compliance

Monitor security posture, review audit events, manage alerts, and access compliance artifacts. Public endpoints are available for SBOM and security contact information.

Security Dashboard

GET /v1/security

Retrieve an aggregated security overview for the authenticated user’s organization, including open alerts, recent audit events, compliance status, and risk score. The organization is resolved from the session.

Query Parameters

Response

{
  "data": {
    "overview": {
      "health_score": 85,
      "period_start": "2026-03-13T00:00:00Z",
      "period_end": "2026-04-12T00:00:00Z"
    },
    "alerts": {
      "critical": 0,
      "high": 1,
      "medium": 2,
      "low": 0,
      "total": 3
    },
    "metrics": {
      "total_events": 1204
    },
    "recommendations": []
  }
}

The health score starts at 100 and is reduced by open critical, high, and medium alerts in the reporting window. recommendations is populated only when include_recommendations is set.

Audit Events

List Audit Events

GET /v1/security/audit/events

The organization is resolved from the authenticated session.

Query Parameters

Response

{
  "data": {
    "events": [
      {
        "id": "...",
        "event_type": "role.changed",
        "severity": "high",
        "actor_id": "...",
        "actor_email": "admin@example.com",
        "target_id": "...",
        "description": "Role changed from member to admin",
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0 ...",
        "metadata": {...},
        "created_at": "2026-04-12T15:30:00Z"
      }
    ],
    "pagination": {
      "total": 1204,
      "limit": 50,
      "offset": 0,
      "has_more": true
    }
  }
}

Record an Application Event

POST /v1/security/audit/events

Record an event reported by one of your own applications in the organization’s audit trail, so that actions happening outside Backbuild sit beside the ones Backbuild records. Requires the Write Audit Events permission (audit.write), which organization owners and administrators hold and which you can add to a custom role. Viewing the audit trail does not grant it.

A reported event is always recognizable as reported. Its event_type (and resource_type, if you send one) is in the custom. namespace, which Backbuild’s own events never use, and its details.origin is caller_reported. The acting user and organization come from your session. The event’s own ip_address, user_agent and session_id are the ones Backbuild observed for the request that reported it; the address, user agent and session you send describe the event you are reporting (for example your end user’s) and are stored as claimed, under details.claimed. Sign-in events (login, logout) are recorded by Backbuild only and cannot be reported.

Request Body

{
  "event_type": "custom.crm.record_exported",
  "action": "export",
  "outcome": "success",
  "severity": "low",
  "resource_type": "custom.crm.report",
  "resource_id": "...",
  "ip_address": "198.51.100.23",
  "details": {
    "format": "pdf",
    "record_count": 150
  }
}

Response

Returns the stored audit-event record.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "event_type": "custom.crm.record_exported",
    "action": "export",
    "actor_id": "...",
    "actor_type": "user",
    "resource_type": "custom.crm.report",
    "resource_id": "...",
    "details": {
      "origin": "caller_reported",
      "reporter": { "credential": "session" },
      "reported": {
        "outcome": "success",
        "severity": "low",
        "details": { "format": "pdf", "record_count": 150 }
      },
      "claimed": { "ip_address": "198.51.100.23" }
    },
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ...",
    "session_id": "...",
    "request_id": "...",
    "created_at": "2026-04-13T10:00:00Z"
  }
}

Response Codes

Security Alerts

List Alerts

GET /v1/security/alerts

The organization is resolved from the authenticated session.

Query Parameters

Create Alert

POST /v1/security/alerts

The organization is resolved from the authenticated session. Requires the Create Security Alert permission (security_alert.create), which organization owners and administrators hold and which you can add to a custom role.

Request Body

{
  "alert_type": "unusual_login_location",
  "title": "Unusual login location detected",
  "severity": "high",
  "description": "Login from unrecognized IP address in a new country",
  "risk_score": 72,
  "metadata": {
    "ip_address": "198.51.100.23",
    "country": "XX",
    "user_id": "..."
  }
}

System-assigned fields (id, status, created_at) are never supplied in the request body; they are assigned by the platform. A new alert is always created in open status.

Response

Returns the full created alert record on success.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "alert_type": "unusual_login_location",
    "severity": "high",
    "title": "Unusual login location detected",
    "description": "Login from unrecognized IP address in a new country",
    "source": null,
    "actor_id": null,
    "resource_type": null,
    "resource_id": null,
    "status": "open",
    "metadata": {
      "ip_address": "198.51.100.23",
      "country": "XX",
      "user_id": "..."
    },
    "created_at": "2026-04-13T10:00:00Z"
  }
}

Response Codes

Update Alert

PUT /v1/security/alerts/:id

Request Body

{
  "status": "acknowledged",
  "resolution_notes": "Verified with user, legitimate travel login"
}

Security Metrics

GET /v1/security/metrics

The organization is resolved from the authenticated session.

Query Parameters

Returns aggregated security metrics for the reporting window: the total audit-event count and the total and currently active security-alert counts. The default window is the last 30 days.

Response

{
  "data": {
    "period": { "from": "2026-03-13T00:00:00Z", "to": "2026-04-12T00:00:00Z" },
    "audit_events": { "total": 1204 },
    "security_alerts": { "total": 3, "active": 2 }
  }
}

Public Endpoints

The following endpoints do not require authentication.

SBOM

GET /v1/security/sbom.json

Returns a CycloneDX Software Bill of Materials in JSON format. This provides transparency into the dependencies used by the platform.

Security Contact

GET /v1/security/security.txt

Returns the security.txt file following RFC 9116. Contains contact information, encryption keys, and vulnerability disclosure policy.

Visibility

Visibility rules control content-level visibility of individual resources to users, groups, roles, departments, and projects. This is separate from RBAC permissions. The organization is resolved from the authenticated session.

Check Visibility

POST /v1/visibility/check

Check whether a given target can see a specific resource.

Request Body

{
  "resource_type": "document",
  "resource_id": "...",
  "target_user_id": "...",
  "target_group_id": "..."
}

List Visibility Rules

GET /v1/visibility/rules

Query Parameters

Create Visibility Rule

POST /v1/visibility/rules

Request Body

{
  "resource_type": "document",
  "resource_id": "...",
  "scope": "group",
  "scope_id": "...",
  "rule_type": "allow"
}

scope_id is required for every scope except global. The organization and the rule’s creator are taken from the authenticated session. System-assigned fields (id, created_at) are never supplied in the request body; they are assigned by the platform.

Response

Returns the full created visibility rule on success.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "resource_type": "document",
    "resource_id": "...",
    "scope": "group",
    "target_id": "...",
    "created_by_user_id": "...",
    "created_at": "2026-04-13T10:00:00Z"
  }
}

Response Codes

Delete Visibility Rule

DELETE /v1/visibility/rules/:id