Organizations & Users

Bootstrap session context

Returns, in a single response, the first-paint data slices needed to render the authenticated user's application shell: profile, organizations, projects, settings, and any other areas gated for the caller's entitlements. The payload is assembled by a single stored procedure in one database round-trip. Each slice is gated independently — a missing feature or permission never fails the overall response. The response carries `ETag` (weak hash) and `Cache-Control: private, max-age=15, stale-while-revalidate=60` headers. Clients should send `If-None-Match` with the stored ETag on subsequent calls; an unchanged payload returns `304 Not Modified` with no body.

Auth Session JWT (Bearer)

Parameters

Responses

CCPA: data categories collected

Returns the categories of personal information Backbuild has collected about the authenticated consumer in the preceding 12 months, including the categories of sources, the business or commercial purposes for collection, and the categories of third parties with whom the information has been shared. Satisfies CCPA §1798.110 (right to know categories collected) and §1798.115 (right to know categories sold or shared) in the read-only, machine-readable form contemplated by §1798.130(a)(5). The `since` parameter is informational — the enumerated categories are not window-dependent — but is recorded in the response for audit purposes.

Auth Session JWT (Bearer)

Parameters

Responses

CCPA opt-out: do not sell or share

Records that the authenticated consumer has exercised their CCPA/CPRA §1798.120 right to opt out of the sale or sharing of their personal information. The operation is idempotent — re-invocation by an already-opted-out consumer succeeds without advancing the original opt-out timestamp (the original instant anchors the §1798.135(c) 12-month wait-before-re-soliciting clock). This endpoint is intentionally frictionless per CCPA §1798.135(a)(3): no MFA step-up is required. A valid authenticated session is required so the opt-out is bound to a verified consumer identity per §1798.130(a)(2) record-keeping obligations. The request body may be omitted or sent as an empty JSON object `{}`. Any unknown keys are rejected with `400 VALIDATION_ERROR`.

Auth Session JWT (Bearer)

Request Body

Empty request body (strict object — no fields accepted).

{}

Responses

List signed legal agreements

Returns all signed legal agreement acceptance records for the caller's organization, with optional filtering by template slug or status, and offset pagination. Gated by the `iam` system feature flag.

Auth Session JWT (Bearer)

Parameters

Responses

Get a signed legal agreement

Returns a single legal agreement acceptance record by id. The acceptance must belong to the caller's organization. Gated by the `iam` system feature flag.

Auth Session JWT (Bearer)

Parameters

Responses

Download signed agreement PDF

Downloads the signed PDF for a legal agreement acceptance. The PDF is served directly from durable object storage with `Content-Type: application/pdf` and `Content-Disposition: attachment`. The response carries `Cache-Control: private, no-store` to prevent caching of sensitive contract documents in shared or transparent caches. Gated by the `iam` system feature flag.

Auth Session JWT (Bearer)

Parameters

Responses

Sign a legal agreement

Signs a legal agreement template on behalf of the caller's organization. The signing flow: 1. Fetches the template and verifies its content hash for integrity. 2. Computes an HMAC-SHA256 signature over a canonical signing payload. 3. Records the acceptance in the database. 4. Generates a signed PDF and stores it durably. 5. Sends the signed PDF to the signer's email and any verified CC recipients. PDF generation and durable storage are required for legal validity — if either step fails the acceptance record is rolled back and `500 INTERNAL_ERROR` is returned. CC recipients must be active members of the signing organization; non-member addresses are rejected with `403 FORBIDDEN`. Maximum 5 CC recipients. Gated by the `iam` system feature flag.

Auth Session JWT (Bearer)

Request Body

{
  "template_id": "019d0000-0000-7000-8000-000000000001",
  "signer_name": "Jane Smith",
  "signer_title": "Chief Legal Officer",
  "signer_email": "jane@acme.com",
  "signer_company": "Acme Corp"
}

Responses

List active legal agreement templates

Returns the set of active legal agreement templates available for signing by the caller's organization (e.g. DPA, BAA, CCPA Addendum). Gated by the `iam` system feature flag.

Auth Session JWT (Bearer)

Responses

Get a legal agreement template

Returns a single legal agreement template by slug, including its full markdown content. The slug is a short lowercase alphanumeric-with-hyphens identifier (e.g. `dpa`, `baa`). Gated by the `iam` system feature flag.

Auth Session JWT (Bearer)

Parameters

Responses

List org custom domains

Returns all custom domains registered for the caller's organization, with optional status filter and offset pagination. Requires the `custom_domain.view` permission (held by owner/admin by default).

Auth Session JWT (Bearer)

Parameters

Responses

Register an org custom domain

Registers a new custom domain for the organization. The domain enters `pending_verification` state; call `POST /v1/org/domains/{domainId}/verify` to run DNS TXT verification. Requires `custom_domain.create` permission. The `api_base_url` must be an HTTPS URL (max 2048 chars); defaults to the environment's Backbuild API endpoint when omitted.

Auth Session JWT (Bearer)

Request Body

{
  "domain": "app.acme.com",
  "domain_type": "primary",
  "environment": "production"
}

Responses

Get an org custom domain

Returns a single custom domain record by id. A domain not visible to the caller (wrong org or not found) is reported as `404 NOT_FOUND`. Requires `custom_domain.view` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Delete an org custom domain

Soft-deletes a custom domain. The domain is set to `deleted` status and removed from active routing. Requires `custom_domain.delete` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Verify an org custom domain

Triggers a real-time DNS-over-HTTPS TXT lookup for `_backbuild-verify.<domain>` and hands the observed token to the platform. If the TXT record matches the stored `dns_verification_token`, the domain transitions to `active`. DNS propagation delays are the caller's responsibility — if the record has not propagated yet, re-invoke after propagation. Requires `custom_domain.update` permission.

Auth Session JWT (Bearer)

Parameters

Responses

Get an org setting

Returns the current value for a single org-level configuration key. Readable by any active member of the organization. The key is a short slug (≤200 chars) identifying the setting; unknown keys return `404 NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Responses

Upsert an org setting

Creates or replaces a single org-level configuration key. Requires admin or owner role (enforced by the stored procedure). The value is stored verbatim as text; the stored procedure normalises boolean-shaped strings. Only allowlisted keys can be written — unknown keys are rejected with `NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "value": "true"
}

Responses

List organizations for the authenticated user

Returns all organizations the authenticated user is a member of, along with their active-organization context and roles. The list is RLS-scoped to the caller's account — the caller cannot enumerate organizations they do not belong to.

Auth Session JWT (Bearer)

Responses

Create an organization

Creates a new organization. The authenticated user becomes the owner. Requires the `org.update` permission on the current session. A URL-safe `slug` is auto-generated from the name when omitted; if a slug is supplied it must conform to the canonical grammar (lowercase alphanumeric groups separated by single hyphens, 3–63 chars, not UUID-shaped, not a reserved word). Returns the platform-assigned organization `id`.

Auth Session JWT (Bearer)

Request Body

{
  "name": "Acme Corp",
  "plan_tier": "starter"
}

Responses

Get an organization by UUID

Returns the full organization record for the given UUID. The caller must belong to the target organization; cross-tenant access returns `403 TENANT_ACCESS_DENIED`. A non-existent organization returns `404 ORG_NOT_FOUND`.

Auth Session JWT (Bearer)

Parameters

Responses

Update an organization

Updates organization fields. Requires the `org.update` permission. At least one field must be present. Top-level shorthand fields (`description`, `website`, `billing_email`, `org_type`) are merged into the `settings.profile` sub-object. Passing `slug: null` clears the optional slug; passing a slug string sets it (must satisfy the canonical grammar). A reserved or syntactically-invalid slug is rejected as `400 VALIDATION_ERROR`. A slug collision returns `409 CONFLICT`.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

List organization members

Returns the members of an organization with optional filtering by role or status, and offset pagination. The caller must belong to the target organization.

Auth Session JWT (Bearer)

Parameters

Responses

Add or update an organization member

Adds a user to the organization or updates an existing member's role and/or status. Requires the `org.manage_members` permission. Role escalation is subject to a role-hierarchy gate in the stored procedure — a caller cannot grant a role higher than their own. Self-modification and demotion of the sole owner are rejected as `409 CONFLICT`. The `email` field is optional; when the target user is visible to the caller via RLS, the platform resolves it automatically.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "user_id": "019b0000-0000-7000-8000-000000000000",
  "role": "member"
}

Responses

Remove an organization member

Removes a user from the organization. Requires the `org.manage_members` permission. A caller cannot remove themselves — the route rejects this with `400 VALIDATION_ERROR` before reaching the stored procedure. Removing the sole owner is rejected by the stored procedure as `409 CONFLICT`. Cross-organization access returns `403 TENANT_ACCESS_DENIED`.

Auth Session JWT (Bearer)

Parameters

Responses

Get org control policies

Returns the current control policies for the specified organization: session idle timeout, container concurrency cap, container daily-hours cap, AI daily spend cap, and any extra policy fields. Readable by any active member of the organization. The `orgId` path parameter must match the caller's active organization (super-admins may access any org).

Auth Session JWT (Bearer)

Parameters

Responses

Update org control policies

Partially updates control policies for the specified organization. At least one field must be present. Passing `null` for a numeric field clears the organization-specific override and reverts to the platform default. Requires the `org.manage_settings` permission. The update stored procedure also mirrors the effective idle timeout into the session layer. The `orgId` must match the caller's active organization (super-admins may update any org).

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "session_inactivity_timeout_minutes": 60,
  "max_concurrent_containers": 10
}

Responses

Get organization auth policy

Returns the effective authentication settings for the organization (platform defaults merged with any per-organization overrides). Any authenticated member of the organization may call this endpoint; it does not require elevated permissions. Used by the login flow and UI to render policy-dependent controls.

Auth Session JWT (Bearer)

Parameters

Responses

Update organization auth policy

Updates the organization's authentication policy. Requires the `org.update_auth_settings` permission (narrower than the general `org.update` — auth-policy changes have their own audit grant). At least one field must be provided. Disabling all authentication methods is rejected as `400 VALIDATION_ERROR`. Cross-tenant writes are rejected both at the route layer and inside the stored procedure.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Get an organization by slug or UUID

Accepts either a canonical slug or a raw UUID as a path segment, resolves it to the organization, enforces that the resolved organization matches the caller's JWT-pinned organization (super-admins exempt), and returns the full organization record. Cross-organization access and missing resources both return `404` (anti-enumeration).

Auth Session JWT (Bearer)

Parameters

Responses

Resolve an organization slug or UUID to its canonical record

Resolves a slug (or a UUID passed as `?slug=`) to the canonical organization UUID and metadata. The resolved organization must match the caller's JWT-pinned organization; cross-organization slug lookups return `404` to prevent enumeration. UUID-form input receives `Sunset`, `Deprecation`, and `Link: rel="alternate"` headers pointing to the canonical slug URL. The response is `private, max-age=0` — never cached in intermediaries.

Auth Session JWT (Bearer)

Parameters

Responses

List AI skills (settings panel)

Returns the AI skills configured for the active organization, for display in the Settings → AI Skills panel. The `/v1/settings/skills` path is an alias for this endpoint.

Auth Session JWT (Bearer)

Responses

List alert rules (settings panel)

Returns alert rules configured for the active organization, for display in the Settings → Alert Rules panel.

Auth Session JWT (Bearer)

Responses

List API keys (settings panel)

Returns the organization API keys visible to the authenticated user, for display in the Settings → API Keys panel. This is a convenience wrapper over the API-keys data for use by the settings UI.

Auth Session JWT (Bearer)

Responses

List automation rules (settings panel)

Returns automation rules configured for the active organization, for display in the Settings → Automation panel.

Auth Session JWT (Bearer)

Responses

Get billing overview (settings panel)

Returns the billing overview for the active organization, for display in the Settings → Billing panel.

Auth Session JWT (Bearer)

Responses

List integrations (settings panel)

Returns integrations configured for the authenticated user and active organization, for display in the Settings → Integrations panel.

Auth Session JWT (Bearer)

Responses

Get notifications (settings panel)

Returns the user's notifications for display in the Settings → Notifications panel. Returns up to 50 records.

Auth Session JWT (Bearer)

Responses

Get all organization settings

Returns the full organization settings object for the authenticated user's active organization. The response is the raw settings blob stored for the organization.

Auth Session JWT (Bearer)

Responses

Update organization settings (batch)

Replaces or merges the organization settings object. Requires the `org.manage_settings` permission (enforced both in this route and inside the stored procedure as defense-in-depth). Emits a real-time `org_settings` change notification to connected collaborators. Returns the resulting settings object.

Auth Session JWT (Bearer)

Request Body

Responses

Get a specific organization setting by key

Returns a single organization setting value looked up by its string key. Returns `404 NOT_FOUND` when the key does not exist in the organization's settings.

Auth Session JWT (Bearer)

Parameters

Responses

Get personalization settings

Returns the authenticated user's personalization preferences in a normalized shape (`themeMode`, `language`, `stayLoggedInHours`, `notifications`). This is a read-only normalized view over the raw preferences; the raw preferences are available at `GET /v1/settings/preferences`.

Auth Session JWT (Bearer)

Responses

Update personalization settings

Accepts a flat personalization object and persists it as user preferences. All fields are required. The `stayLoggedInHours` value must be one of the discrete allowed choices (`1`, `8`, `24`, `168`, `720`); arbitrary integers are rejected. Returns the resulting normalized personalization.

Auth Session JWT (Bearer)

Request Body

Responses

Get user preferences

Returns the raw user preferences object for the authenticated user within their active organization context. See also `GET /v1/settings/personalization` for a normalized view.

Auth Session JWT (Bearer)

Responses

Update user preferences (batch)

Replaces or merges the user's preference object within the active organization context. Accepts a bounded JSONB preferences object. Returns the resulting preferences.

Auth Session JWT (Bearer)

Request Body

Responses

Get a specific user preference by key

Returns a single preference value for the authenticated user, looked up by its string key.

Auth Session JWT (Bearer)

Parameters

Responses

Get user profile (settings panel)

Returns the authenticated user's profile data for display in the Settings → Profile panel. Retrieves the full user profile from the stored procedure when available; falls back to the session's auth context (userId, email, orgId) if the stored procedure is not yet available.

Auth Session JWT (Bearer)

Responses

Get security settings (settings panel)

Returns the security settings for the active organization, for display in the Settings → Security panel.

Auth Session JWT (Bearer)

Responses

List AI skills — alias

Alias for `GET /v1/settings/ai-skills`. Provided because the web app SkillsPanel calls this path. Returns the same data.

Auth Session JWT (Bearer)

Responses

Get sync configuration

Returns the synchronization configuration for the authenticated user's active organization. Used by clients to initialize their offline/sync layer.

Auth Session JWT (Bearer)

Responses

List views (settings panel)

Returns saved views for the authenticated user and active organization, for display in the Settings → Views panel. Returns up to 100 records.

Auth Session JWT (Bearer)

Responses

Check slug availability

Advisory check for whether a proposed slug is available for a given resource kind (`org`, `project`, or `package`). Returns `{ available, reason }` — the response NEVER identifies the current owner (anti-enumeration). This endpoint is rate-limited per authenticated user (60 requests/minute per user) and should be called from a debounced editor field. The result is advisory; DB uniqueness enforcement remains authoritative on the write path.

Auth Session JWT (Bearer)

Parameters

Responses

Export user data (GDPR Data Subject Access Request)

Returns a machine-readable JSON bundle of all personal data the platform holds for the given user, fulfilling the data subject access right (GDPR Art. 15) and data portability right (GDPR Art. 20). The caller must be either the data subject themselves or a super-admin. Requires a fresh MFA step-up (within the last 5 minutes) and a valid Cloudflare Turnstile proof-of-human token. Rate limited to one export per target user per hour. The response is served with `Content-Disposition: attachment` and `Cache-Control: no-store`. If the audit log was truncated at the 50 000-row platform cap, the response carries `X-Export-Truncated: true` and a top-level `truncated: true` field.

Auth Session JWT (Bearer)

Parameters

Responses

Check resource visibility

Evaluates whether the target principal (user or group) can see a given resource, based on the caller's organization's visibility rules. Returns a structured verdict from the stored procedure. Requires an authenticated session; the caller's organization and user id scope the rule evaluation.

Auth Session JWT (Bearer)

Request Body

{
  "resource_type": "project",
  "resource_id": "019d0000-0000-7000-8000-000000000000"
}

Responses

List visibility rules

Returns visibility rules for the caller's organization, with optional filtering by resource type, resource id, rule type, or scope. Results are offset-paginated.

Auth Session JWT (Bearer)

Parameters

Responses

Create a visibility rule

Creates a new visibility rule for a resource within the caller's organization. For scopes other than `global`, a `scope_id` (the target user, role, group, or project id) is required. The stored procedure enforces authorization; the caller must have sufficient permissions to manage visibility for the target resource.

Auth Session JWT (Bearer)

Request Body

{
  "resource_type": "project",
  "resource_id": "019d0000-0000-7000-8000-000000000000",
  "scope": "org",
  "rule_type": "allow"
}

Responses

Delete a visibility rule

Deletes a visibility rule by id. The caller must have permission to manage visibility for the resource covered by the rule.

Auth Session JWT (Bearer)

Parameters

Responses