Admin & Security

List alert rules for the authenticated user's organization

Returns all alert rules associated with the authenticated user's active organization. Standard bearer-token authentication.

Auth Session JWT (Bearer)

Responses

Create an alert rule

Creates a new alert rule in the authenticated user's active organization. Standard bearer-token authentication.

Auth Session JWT (Bearer)

Request Body

Responses

Update an alert rule (not yet implemented)

This endpoint is not yet implemented and always returns `501 NOT_IMPLEMENTED`.

Auth Session JWT (Bearer)

Parameters

Request Body

JSON object.

Responses

Delete an alert rule (not yet implemented)

This endpoint is not yet implemented and always returns `501 NOT_IMPLEMENTED`.

Auth Session JWT (Bearer)

Parameters

Responses

MCP JSON-RPC 2.0 dispatch

Single endpoint that handles all MCP (Model Context Protocol) JSON-RPC 2.0 method calls. Every request body must be a valid JSON-RPC 2.0 object. Supported methods: `initialize`, `tools/list` (with optional `params.full=true`), `tools/call`, `resources/list`, `resources/read`, `ping`. Always returns HTTP `200` for well-formed JSON-RPC requests (including JSON-RPC-level errors per JSON-RPC 2.0 spec). Returns HTTP `401` for missing/invalid API keys, `429` for rate limit exceeded (fail-closed, returns 503 if the rate-limiter service itself is unavailable). OAuth-issued API keys with explicit scopes are supported; direct-mint (legacy) keys without explicit scopes receive a deprecation header in the response. API key format: `bb_live_<8-char-prefix>_<32-or-64-char-secret>` (hex or base64url).

Auth API key (Bearer bb_live_…)

Request Body

Responses

List task/spec categories for a project

Returns the list of category definitions for a project. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Create a category for a project

Creates a new category. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List project phases

Returns the ordered list of phase definitions for a project. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Create a phase for a project

Creates a new phase definition. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List specs for a project

Returns all specification documents for the given project. Requires `project.view` permission on the project.

Auth Session JWT (Bearer)

Parameters

Responses

Create a spec in a project

Creates a new specification document within a project. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List task statuses for a project

Returns the ordered list of task status definitions for a project. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Create a task status for a project

Creates a new task status definition. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List tasks for a project

Returns tasks for the given project, with optional filters. Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Create a task in a project

Creates a new task in the project. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List departments

Lists departments in the organization. Departments are logical groupings of members and projects for RBAC/policy assignment.

Auth Session JWT (Bearer)

Parameters

Responses

Create a department

Creates a new department in the organization. The body uses `.strict()` validation.

Auth Session JWT (Bearer)

Request Body

Responses

Update a department

Updates an existing department's name or description. The body uses `.strict()` validation.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a department

Permanently deletes a department by UUID. Members and projects are unlinked from the department.

Auth Session JWT (Bearer)

Parameters

Responses

Get effective permissions

Returns the resolved permission set for the target user in the caller's organization, optionally scoped to a specific project. By default queries the authenticated caller's own permissions. Only organization owners, admins, and super-admins may query another user's permissions (returns `403 FORBIDDEN` otherwise).

Auth Session JWT (Bearer)

Parameters

Responses

List groups

Lists groups in the organization. Groups are sets of members for policy assignment.

Auth Session JWT (Bearer)

Parameters

Responses

Create a group

Creates a new group in the organization. The body uses `.strict()` validation.

Auth Session JWT (Bearer)

Request Body

Responses

Update a group

Updates an existing group's name or description. The body uses `.strict()` validation.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a group

Permanently deletes a group by UUID.

Auth Session JWT (Bearer)

Parameters

Responses

List permissions

Returns the permission catalog for the organization. Permissions are referenced by dot-notation slug (e.g. `project.view`, `org.manage_roles`). The response payload is `{ permissions: [...], total_count: N }`.

Auth Session JWT (Bearer)

Parameters

Responses

Create a permission

Creates a custom permission in the organization's permission catalog. `resource` and `action` define the access dimension. The body is strict (`.strict()`): any unknown field returns `400 VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Request Body

Responses

Delete a permission

Deletes a permission from the organization's permission catalog by UUID. Roles that reference this permission will have it removed.

Auth Session JWT (Bearer)

Parameters

Responses

List RBAC policies

Returns RBAC access policies for the organization with limit/offset pagination. Supports filtering by resource type, search string, and active/inactive status.

Auth Session JWT (Bearer)

Parameters

Responses

Create an RBAC policy

Records a new RBAC policy for the organization. Policies are recorded and audited; policy enforcement is a per-organization setting, so a policy takes effect only for organizations that have it enabled. Either `policy_name` or `name` must be supplied. Either `resource_type` or `resource_pattern` must be supplied. Either `operation` or `action_pattern` must be supplied. The body is strict (`additionalProperties: false`).

Auth Session JWT (Bearer)

Request Body

Responses

Get a policy

Returns a single RBAC policy by UUID.

Auth Session JWT (Bearer)

Parameters

Responses

Update a policy

Updates fields on an existing RBAC policy. Policies are recorded and audited; policy enforcement is a per-organization setting, so a policy takes effect only for organizations that have it enabled. All fields are optional; the body is strict (`additionalProperties: false`).

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a policy

Permanently deletes an RBAC policy.

Auth Session JWT (Bearer)

Parameters

Responses

List RBAC roles

Returns the system and custom roles available within the caller's organization, suitable for display in the IAM Roles UI. System catalog roles (`is_system=true`) are platform-defined and read-only. Custom roles are org-specific. The response payload is `{ roles: [...], total_count: N }`.

Auth Session JWT (Bearer)

Parameters

Responses

Create a custom role

Creates a new custom role in the caller's organization with an optional set of permission slugs. The role's `is_system` flag is always `false`; clients cannot create system roles. Permission slugs are validated against the platform's system-permission catalog: unknown slugs are rejected. The body uses `.strict()` validation: any unrecognized field (e.g. `is_super_admin`) returns `400 VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Request Body

Responses

Get a role

Returns a single role by its slug key. Both system roles (e.g. `owner`, `admin`) and custom roles (lowercase slug) are addressed by their text slug, not a UUID.

Auth Session JWT (Bearer)

Parameters

Responses

Update a custom role

Updates a custom role's name, description, permission set, or metadata. System roles (`is_system=true`) cannot be updated via this endpoint. The body uses `.strict()` validation: unknown fields including `is_super_admin` and `is_system` return `400 VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a custom role

Deletes a custom role by slug. System roles cannot be deleted. Any members currently assigned only this role will lose that assignment.

Auth Session JWT (Bearer)

Parameters

Responses

Sync RBAC state

Triggers a server-side reconciliation of the organization's RBAC state against the platform's system role-and-permission catalog. Requires organization admin privileges. Use this when role/permission drift is detected.

Auth Session JWT (Bearer)

Request Body

JSON object.

Responses

Security overview dashboard

Returns the security posture dashboard for the caller's organization including alert counts, authentication metrics, violation stats, and an overall health score. Optionally includes platform-generated recommendations when `include_recommendations=true`.

Auth Session JWT (Bearer)

Parameters

Responses

List security alerts

Returns security alerts for the organization. Supports filtering by alert type, severity, status, and time range. Limit is 1 to 100 (default 25).

Auth Session JWT (Bearer)

Parameters

Responses

Create a security alert

Creates a new security alert for the organization. Alerts can reference threat indicators, affected resources, and recommended response actions. Requires the Create Security Alert permission (`security_alert.create`), held by organization owners and administrators and assignable to a custom role.

Auth Session JWT (Bearer)

Request Body

Responses

Update a security alert

Updates a security alert's status, resolution notes, or metadata. Status transitions: `active → acknowledged → resolved` (or `→ false_positive`). Returns `404` if not found.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List audit events

Returns the organization's audit events, newest first, with limit/offset pagination; `total_count` counts every matching event. Filters combine: event type, user, session, severity and time range (both bounds inclusive). Limit is 1 to 1000 (default 50).

Auth Session JWT (Bearer)

Parameters

Responses

Record an application-reported audit event

Records an event reported by one of your own applications in the organization's audit trail, so actions that happen outside Backbuild sit beside the ones Backbuild records. Requires the Write Audit Events permission (`audit.write`), held by organization owners and administrators and assignable to a custom role. Reported events are always labelled as reported: `event_type` and `resource_type` use the `custom.` namespace, which Backbuild's own events never use; `details.origin` is `caller_reported`; your classification and payload are stored under `details.reported`; the address, user agent and session you send are stored under `details.claimed`. The event's own `ip_address`, `user_agent` and `session_id` are those Backbuild observed for the request that reported it, and the acting user and organization come from the session. Sign-in events (`login`, `logout`) are recorded by Backbuild only and cannot be reported.

Auth Session JWT (Bearer)

Request Body

Responses

Record cookie consent decision

Records the authenticated user's cookie consent decision (GDPR Art. 6-7, ePrivacy Directive). Accepted categories: `necessary`, `analytics`, `marketing`, `preferences`. Body is strict.

Auth Session JWT (Bearer)

Request Body

Responses

Record marketing tracking consent

Records whether the user consents to having conversion data shared with external ad platforms (Meta, Google, Reddit, Bing). For EEA/UK/CH users this consent is required before any PII transfer to US-based platforms occurs (GDPR Art. 49).

Auth Session JWT (Bearer)

Request Body

Responses

Get current consent status

Returns the most recent consent records for the authenticated user by consent type.

Auth Session JWT (Bearer)

Responses

Receive a Content Security Policy report

Receives browser-generated CSP violation reports. Unauthenticated endpoint. Rate-limited to 100 requests per minute per IP address. Request body is capped at 16 KB (returns `413 PAYLOAD_TOO_LARGE` on oversize). Accepts `application/csp-report`, `application/reports+json`, and `application/json` content types. Returns `204 No Content` on success.

Public Public: no authentication

Request Body

JSON object.

Responses

List DSAR requests

Returns DSAR requests for the organization. Requires a **fresh MFA step-up**. Supports filtering by status and limit/offset pagination (limit 1 to 1000, default 50).

Auth Session JWT (Bearer)

Parameters

Responses

Create a Data Subject Access Request

Opens a Data Subject Access Request (DSAR) for an identified data subject. Covers all GDPR Art. 15-20 right types. Requires a **fresh MFA step-up** (within the last 5 minutes) via `requireMfaStepUp()`. API-key sessions cannot call this endpoint. The body is strict: any unrecognized field returns `400`.

Auth Session JWT (Bearer)

Request Body

Responses

Get a DSAR request

Returns a specific DSAR request by UUID. Requires a fresh MFA step-up.

Auth Session JWT (Bearer)

Parameters

Responses

Export data for a DSAR request

Exports all personal data associated with the DSAR request in machine-readable format (GDPR Art. 20: right to data portability). Requires a fresh MFA step-up.

Auth Session JWT (Bearer)

Parameters

Responses

Register a GDPR Art. 21 processing objection

Records the authenticated data subject's objection to processing under a specific scope (or all scopes). Per-scope flags are stored on the user account; downstream handlers consult them and skip the processing. Requires a fresh MFA step-up. Compliance admins acting on behalf of third-party subjects must use the standard `POST /v1/security/dsar` workflow with `request_type='objection'`. Body is strict.

Auth Session JWT (Bearer)

Request Body

Responses

Activate GDPR Art. 18 processing restriction

Pauses mutation of the authenticated caller's personal data (GDPR Art. 18: right to restriction of processing). Storage and Art. 15 read access remain permitted. Downstream write stored procedures will reject with `PROCESSING_RESTRICTED` until the flag is lifted. Requires a fresh MFA step-up. The body is strict: unknown fields return `400`.

Auth Session JWT (Bearer)

Request Body

Responses

Lift GDPR Art. 18 processing restriction

Lifts the processing restriction for the caller themselves (self-path, omit `user_id`) or for another user (admin-path, supply `user_id` with `compliance.manage` permission). Per GDPR Art. 18(3), the data subject must be notified before lifting: this obligation is operational; the audit trail records `lifted_by_self`/`lifted_by_admin` for verification. Requires a fresh MFA step-up. Body is strict.

Auth Session JWT (Bearer)

Request Body

Responses

Invoke break-glass emergency access

Grants time-limited emergency access to a specific resource (HIPAA 164.312(a)(2)(ii); SOC 2 CC6.1). A mandatory reason of at least 10 characters must be supplied. Creates an immutable critical-severity audit event. The grant is automatically revoked after `duration_minutes` (default 60, max 480). The body is strict: unknown fields are rejected.

Auth Session JWT (Bearer)

Request Body

Responses

Get security metrics summary

Returns aggregated security metrics (authentication success/failure rates, anomaly counts, policy violation counts) for the organization within the specified time window.

Auth Session JWT (Bearer)

Parameters

Responses

Record parental consent (COPPA)

Records parental consent for a child user account (COPPA 16 CFR Part 312). Accepted verification methods: `email_verification`, `credit_card`, `phone_call`, `video_conference`, `government_id`.

Auth Session JWT (Bearer)

Request Body

Responses

Get Software Bill of Materials

In production, returns a `302 Found` redirect to the canonical SBOM hosted at `trust.backbuild.ai`. In non-production environments, returns `202 Accepted` with a `Retry-After: 86400` header and `x-placeholder: true` indicating the artifact is not yet available.

Public Public: no authentication

Responses

RFC 9116 security.txt

Returns the `security.txt` file as per RFC 9116. Response content type is `text/plain; charset=utf-8`. Cached with `Cache-Control: public, max-age=3600`.

Public Public: no authentication

Responses

Get a spec

Returns a single specification document. Requires `project.view` permission on the parent project.

Auth Session JWT (Bearer)

Parameters

Responses

Update a spec

Updates a specification document. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a spec

Permanently deletes a specification document and all its tasks. Requires `project.delete` permission.

Auth Session JWT (Bearer)

Parameters

Responses

List tasks in a spec

Returns all tasks belonging to a specification. Requires `project.view` permission on the parent project.

Auth Session JWT (Bearer)

Parameters

Responses

Get a task

Returns a single task record. Requires `project.view` permission on the parent project.

Auth Session JWT (Bearer)

Parameters

Responses

Update a task

Updates a task's fields. Requires `project.update` permission.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a task

Permanently deletes a task and its activity log. Requires `project.delete` permission.

Auth Session JWT (Bearer)

Parameters

Responses

List task activity log

Returns the ordered activity log for a task (status changes, assignments, comments). Requires `project.view` permission.

Auth Session JWT (Bearer)

Parameters

Responses