# AGENTS Source: https://docs.superblocks.com/AGENTS # docs-v2 Superblocks external documentation site, powered by Mintlify. Published at `https://docs.superblocks.com`. ## Commands ```bash theme={null} mintlify dev # Local preview at http://localhost:3000 mintlify build # Production build (usually handled by Mintlify deploy pipeline) ``` ## Structure * `getting-started/` - Onboarding and quickstart guides * `integrations/` - Integration-specific documentation * `applications/` - Application building guides (pages, components, queries, workflows) * `admin/` - Admin and organization settings * `enterprise/` - Enterprise features (on-premise, SSO, audit logs) * `components/` - UI component reference * `scripts/` - Client-side JS (dropdown, TOC helpers) * `docs.json` - Mintlify configuration (navigation, theme, redirects, SEO) ## Content Guidelines * All content is Markdown with Mintlify extensions (callouts, tabs, cards, accordions) * Navigation structure is defined in `docs.json` under the `navigation` key * Redirects are defined in `docs.json` under `redirects` * Images go in the appropriate content directory alongside their page * Auto-deploys on merge to `main` ## Org-Wide Standards For cross-repo architecture, security practices, observability, and prompt standards, see the org-level AGENTS.md in `superblocksteam/workspace` at `repos/AGENTS.md`. # Self-serve plans Source: https://docs.superblocks.com/admin/ai-credits Learn how Superblocks Governed Agent Units (GAUs) work, what's included in each plan, and how to purchase additional GAUs ## How GAUs work [Governed Agent Units (GAUs)](/admin/billing-overview#what-is-a-governed-agent-unit) are used across Clark (Superblocks' AI agent) and other governance and AI features. Each AI interaction consumes GAUs based on the complexity of the request. Here are some example prompts and their cost: | User prompt | Work done | GAUs used | | - | - | - | | Add a header section with title and subtitle | Creates a reusable header component and applies existing page typography styles | 1 | | Change the top navigation background to black | Updates navigation styles and verifies contrast on existing text/icons | 2 | | Connect Salesforce opportunities and show a table + column chart | Explores the data with sample queries in ![](https://upload.wikimedia.org/wikipedia/commons/thumb/f/f9/Salesforce.com_logo.svg/1280px-Salesforce.com_logo.svg.png)Salesforce, identifies the right object and fields with the user, then implements both a table and chart | 4 | | Build a full sales dashboard from this schema | Generates a step-by-step plan, builds layout/components, connects data, and validates the final app | 8 | ## Included GAUs Teams plans use an **organization-level GAU pool** shared by all builders. You are not charged per builder seat. Additional org-level GAU packs are available for purchase. All GAUs reset monthly. ## GAU packs **Org-level top-ups:** Purchase GAUs that can be shared across all users in your organization | GAUs | Cost per month (Annual plan) | Cost per month (Monthly plan) | | - | - | - | | 100 GAUs | **\$100** /month | **\$125** /month | | 250 GAUs | **\$250** /month | **\$313** /month | | 500 GAUs | **\$500** /month | **\$625** /month | | 1,000 GAUs | **\$1000** /month | **\$1250** /month | | 2,500 GAUs | **\$2500** /month | **\$3125** /month | | Custom volume | [Contact Sales →](mailto:pricing@superblockshq.com) | [Contact Sales →](mailto:pricing@superblockshq.com) | GAU packs are billed in-line with your billing schedule. [Contact sales](mailto:pricing@superblockshq.com) for higher volumes. ## Usage tracking Monitor your organization's GAU usage directly in the Superblocks admin console. You can view: * Current GAU balance and usage trends * Per-user GAU consumption * Per-application GAU consumption * Historical usage patterns * Alerts when approaching GAU limits ### Per-application usage Usage is tracked per-application, giving you granular insight into where GAUs are spent across your organization. This helps you: * Identify which applications consume the most GAUs * Allocate resources and budget effectively across projects * Make informed decisions about optimizing high-usage applications # Audit logs Source: https://docs.superblocks.com/admin/audit-logs Search and filter organization audit events in Superblocks **Audit logs** provide a searchable record of activity in your Superblocks organization. With audit logs, admins get visibility into: * **Builder activity** (edits, deploys, permission changes) * **End-user activity** in your apps * **Integration and platform changes** (credentials, configuration, and other administrative updates) All of this audit data is also available **programmatically** through the [Superblocks MCP server](/admin/mcp-server)—use the Audit capabilities to query the same events from agents, scripts, and other tooling. ## Searching for logs In the [**Audit logs**](https://app.superblocks.com/audit) page, filter by time range, event type, resource, actor, status, and severity. | Control | Purpose | | - | - | | **Search** | Text search over audit events | | **Date range** | Start and end date-time for the events to include | | **Event type** | Limit to one [event type](#event-types), or **All** | | **Status** | Limit by outcome (e.g., Success or Failure), or **All** | | **Severity** | Limit by severity level (e.g., Low+, Medium+, High+), or **All** | | **Resource** | Limit to one or more [resource kinds](#resources), or **All** | | **Actor** | Limit to actions by a specific user, or **Anyone** | You can then view any matching events, and click into an event to see the raw event details. ![Audit logs](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/audit_logs.png) ![Audit event details](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/audit_event_details.png) ## Event types You can filter by the following **Event type** values: * **Account Change** * **Authentication** * **Entity Management** * **User Access** * **App Lifecycle** ## Resources You can filter by **Resource** to focus on events that target a given kind of object. Available values include: * **Agent** * **Application** * **Credential** * **Folder** * **Group** * **Integration** * **Knowledge** * **Organization** * **Permission** * **Repository** * **Role** * **Session** * **Token** * **User** # Billing overview Source: https://docs.superblocks.com/admin/billing-overview How Enterprise dollar-commit billing works: Governed Agent Units, committed spend, and published applications Enterprise organizations on the standard **dollar-commit** contract pay against a committed dollar amount for the contract period. Usage shows up in dollars on [Plan & Usage](/admin/plan-and-usage), so you can see how Clark work and published apps draw down that commit. This is the experience for customers with a dollar commit with Superblocks. If your organization has a special contract, usage is shown in GAUs instead of dollars in the commitment summary, the usage chart, the usage table (including checkpoint rows), and the published applications view. This page covers the concepts. For a walkthrough of the Plan & Usage UI, see [Plan & Usage](/admin/plan-and-usage). To set limits and alerts, see [Spend management](/admin/spend-management). ## What is a Governed Agent Unit? A **Governed Agent Unit (GAU)** measures the amount of secure orchestration, governance, cost optimization, and reliability work Superblocks performs around AI model inference. On a dollar-commit contract, GAU consumption is priced into dollars and counted against your commit and any overage. | Deployment | What's included in the GAU rate | | - | - | | **Superblocks Cloud Prem** | You pay AWS directly for inference, so the GAU rate reflects platform orchestration and governance work only. Model costs are separate and billed by AWS. | | **Superblocks Cloud** | Pricing includes inference, so one rate covers both the model inference and platform work to govern it. | ### Platform work included in each GAU Each GAU covers Superblocks platform work across the following areas: #### Security and governance * **Prompt-injection protection:** Superblocks scans prompts and model interactions for malicious instructions designed to manipulate Clark or gain unauthorized access to company systems and data. * **Isolated sandbox orchestration:** Superblocks runs agent work inside isolated execution environments and manages the lifecycle of each sandbox, including creation, pausing, resuming, and termination. * **Integration authentication and authorization:** Whenever Clark accesses an integration, Superblocks authenticates the connection and verifies that the user and agent are authorized to perform the requested action. * **Application security scanning:** Before deployment, Superblocks performs static and runtime security checks on generated applications to identify vulnerabilities and unsafe behavior. * **Package and supply-chain security:** When packages are installed, Superblocks checks them against vulnerability and malware intelligence to reduce the risk of compromised or malicious dependencies. * **Security agents:** Specialized agents inspect applications for security risks that traditional code scanning may miss, including authorization flaws, unsafe data access, and business-logic vulnerabilities. * **Audit logging:** Superblocks records prompts, agent actions, integration calls, policy decisions, and results to provide traceability across the application lifecycle. #### Cost optimization * **Prompt and token caching:** Superblocks reuses eligible prompt and context data to avoid unnecessary model processing and reduce inference costs. * **Context management:** Superblocks determines which information should be retained, summarized, retrieved, or removed so models receive the context they need without repeatedly processing the entire session history. * **Model routing:** Superblocks routes work across frontier and open-source models based on the complexity of the task, balancing output quality, latency, and cost. #### Infrastructure automation and reliability * **Inference failover and retries:** Superblocks detects failed or degraded model requests and manages retries, fallback models, and recovery workflows to keep agent execution moving. * **Execution monitoring:** Superblocks tracks agent progress, errors, tool calls, and intermediate results so long-running tasks can be observed and recovered. * **Database provisioning and migration:** Superblocks provisions application databases inside the customer’s AWS private cloud and manages schema migration across development and production environments. * **Application deployment:** Superblocks packages and deploys applications while applying the required security, infrastructure, and organizational controls. ## Dollar-commit contracts With a dollar-commit Enterprise contract: * Your organization has a **committed dollar amount** for the contract period * **Clark / GAU usage** and **published application charges** both count toward that commit and any overage * Plan & Usage shows spend in **dollars**, including a commitment / usage bar for the main contract type * Billing type on usage rows can show **Committed** vs **Overage** when your contract distinguishes them For Teams (self-serve) packs and refills, see [Self-serve plans](/admin/self-serve-plan). ## Enterprise platform license The enterprise platform license provides unlimited platform access, enterprise identity and governance controls, spend management, support, and hands-on onboarding for builders and administrators. * **Unlimited builders and end users:** Create and use unlimited applications without per-seat builder or end-user fees. * **SSO and SCIM:** Connect your identity provider to centralize authentication and automatically provision and deprovision users and groups. * **Bring Your Own Key inference — Cloud-Prem:** Use model inference through your own cloud accounts and credentials, keeping model usage and spend within your cloud environment. * **Application RBAC:** Control who can access each application and what actions they can perform based on assigned roles. * **Platform audit logging:** Maintain a centralized record of administrative activity, access changes, application events, and platform actions. * **Platform Admin MCP:** Allow authorized AI agents and administrative tools to securely manage the Superblocks platform through governed interfaces. * **Spend management:** Set budgets, usage limits, and policies to monitor and control AI and platform consumption across teams. * **Enterprise Support SLA:** Receive priority support with contracted response times and escalation paths for business-critical issues. * **Shared Slack or Microsoft Teams channel:** Collaborate directly with the Superblocks team through a dedicated shared support and coordination channel. * **Forward Deployed Engineer:** Receive part-time hands-on support for platform administration, implementation guidance, builder onboarding, and training. ## Published applications Each published application is charged every month it stays published. On Plan & Usage, the **Published apps** view shows which apps are billed for which months, including **Pending** charges for the current month before the period closes. Superblocks manages deployments, infrastructure, scaling, infrastructure security, incident recovery, and uptime for published applications. This SKU was previously named **Deployed apps**. ## Fully managed AWS Cloud Prem Superblocks can provision, operate, monitor, upgrade, and support the platform inside your AWS account with an enterprise uptime SLA, so you do not need to dedicate internal DevOps resources to managing it. # How findings work Source: https://docs.superblocks.com/admin/code-security/how-findings-work Severity, scan modes, remediation, run errors, and the audit trail shared by every publish-time policy Every policy that runs at publish time behaves the same way once it produces a finding. This page covers that shared behavior: how severity is assigned, what a scan mode does, how remediation clears a gate, what happens when a run fails, and what lands in the audit log. It applies to [static analysis](/admin/code-security/static-analysis), the [Security Agent](/admin/code-security/security-agent), and publish-time [CVE detection](/admin/code-security/supply-chain/cve-detection). Two CVE detection moments work differently and are documented on that page. At install time, the check runs long before anyone publishes, so there is no scan mode to apply: Clark either installs the package, swaps it for a safe version, or blocks it. Continuous monitoring uses the same severities, but it reports to [Security Center](/admin/code-security/supply-chain/cve-detection#continuous-monitoring) rather than gating a publish. ## Severity Every finding carries a severity that reflects how serious the issue is and how likely it is to be exploited: | Severity | Rationale | | - | - | | **Critical** | Directly exploitable with serious impact, such as a live credential in the shipped bundle | | **High** | A real vulnerability reachable from user input, such as an injection sink on an unsanitized parameter | | **Medium** | Worth reviewing, but exploitation depends on conditions that may not hold in your app | | **Low** | Hardening and hygiene, with no path to impact on its own | | **Info** | Context for the reviewer, not a defect | **Critical** and **High** findings are the only ones that can block a publish. Whether they do depends on the scan mode your admins set. Everything below High is always reported and never blocks. Severity reflects exploitability in context, not just pattern match. A mitigation such as input validation, output escaping, or platform-level access control lowers the severity of a finding rather than leaving it at its theoretical worst case. ## Scan modes The mode decides what happens when a policy produces a critical or high finding. It is set per policy, not per organization, so static analysis and the Security Agent each carry their own. | Mode | Critical and high findings | How a publish still goes out | | - | - | - | | **Advisory** | Reported. Publish is not blocked. | The builder publishes as usual. | | **Blocking with exceptions** | The checklist guides the builder to a fix. | The builder can click **Publish anyway**. | | **Blocking** | Publish is blocked. | It does not. Every critical and high finding must be fixed. | New policies default to **Advisory**. ### Advisory The policy runs and reports what it found. Critical and high findings do not stop the publish. Use this mode to measure finding volume before you enforce a policy. ### Blocking with exceptions The publish checklist surfaces critical and high findings and points the builder at a fix, usually **Fix with Clark**. If the builder still wants to ship, they click **Publish anyway**. Anyone with deploy access on the application can do this, and it is the path for a false positive or an accepted risk. This is the right mode for most teams. It makes findings hard to miss and still leaves an escape hatch. ### Blocking Same guidance as Blocking with exceptions, with **Publish anyway** removed. Critical and high findings stop the publish until they are gone. There is no override. Use it where a critical or high finding must never reach production. ## Scope Some policies apply to every app. Others can be limited to a subset. | Scope | What it means | | - | - | | **All apps** | The policy's mode applies to every application in the organization | | **Limited** | The policy's mode applies only to the apps you select. Other apps skip this policy | Use a limited scope when one app needs a stricter mode than the rest of the fleet. For example, keep the Security Agent on Advisory for most apps, and set it to Blocking on the apps that handle sensitive data. ## Configure a mode and scope 1. Open **Policy Agents** in the dashboard 2. Select the policy and click **Edit** 3. Set **Mode** 4. Set **Scope** to **All apps**, or **Limited** and pick the apps 5. Save The new settings apply to the next run. They do not re-evaluate publishes that already completed. ## What builders see Every publish-time policy reports into **Pre-Publish Policies** on the publish detail, so builders get one view of what passed, what is running, and what is blocking the deploy. ![Pre-Publish Policies on a publish, showing an advisory run with one info finding](https://mintcdn.com/superblocks/oGCsa1vIICDA_eX7/images/administration/code-security/publish-readiness-advisory.png?fit=max\&auto=format\&n=oGCsa1vIICDA_eX7\&q=85\&s=8de07897c5a0543b7fe0568fec92cec7) Each policy is its own row with its own result. Above, the Security Agent reported one info finding and the security scan passed, so the publish completed. The banner at the top of the section states the mode in effect, which is why this run is marked **Advisory**: findings are reported and nothing blocks. Expand a finding to see: * **What was found**: a clear description of the issue * **Where**: the file path and location in the application * **Severity**: critical, high, medium, low, or info * **Evidence**: the code that triggered the finding, with secrets redacted * **Fix with Clark**: one-click remediation for eligible findings ## Remediation 1. The builder selects the finding they want to fix, and then clicks **Fix with Clark** 2. Clark edits the application to resolve it, for example by removing a hardcoded secret and referencing an environment variable instead 3. A fresh run evaluates the updated application 4. If the finding is resolved, the publish unblocks **Fix with Clark** never marks a policy as passed on its own. A remediation attempt does not clear a blocking gate, because only a fresh run against the new application state can confirm the fix. Policies evaluate and report; Clark makes the changes. Some findings cannot be fixed by Clark and are marked as such. Credential rotation, external account changes, infrastructure work, and human policy decisions all fall outside what Clark can edit. When Clark cannot fix a finding, the outcome depends on the mode: **Publish anyway** under Blocking with exceptions, or a required fix under Blocking. ## Run states and errors Every publish-time run is listed on the **Security runs** tab in Security Center. Filter by app, policy, status, who triggered it, and date. ![Security Center Security runs tab listing publish-time policy runs](https://mintcdn.com/superblocks/oGCsa1vIICDA_eX7/images/administration/code-security/security-runs.png?fit=max\&auto=format\&n=oGCsa1vIICDA_eX7\&q=85\&s=8acc5ca57ac83390e09f1b49e9812256) **Run status** is what the policy produced. **Decision** is what happened to the publish. In the example above, the security scan passed with no findings, and the Security Agent produced one finding that did not block, so both decisions are allowed. A run moves through these states: | State | Meaning | | - | - | | **Queued** | The run is scheduled and waiting to start | | **Running** | The policy is evaluating the application snapshot | | **Passed** | The run finished with no findings | | **Findings** | The run produced findings that do not block | | **Blocked** | The run produced critical or high findings under a blocking mode | | **Errored** | The run failed before it reached a verdict | | **Timed out** | The run exceeded its time limit | | **Canceled** | The run was stopped before it finished | | **Stale** | The application changed, so the result no longer describes what would ship | An **errored** or **timed out** run is not a pass. Because the policy never reached a verdict, a blocking policy holds the publish rather than letting an unreviewed app through. Retry the publish to start a fresh run. A **stale** result appears when the application changes after a run completes. The next publish re-runs the policy against the new snapshot. ## Audit trail Every run, finding, remediation attempt, escalation, and **Publish anyway** is recorded as an [audit log](/admin/audit-logs) event. Admins can see what was scanned and when, what findings were produced, what action was taken, and which apps have outstanding advisory findings. The same data is available programmatically through the [Superblocks MCP server](/admin/mcp-server), so you can query findings from agents, scripts, or dashboards. ## Permissions | Action | Permission | | - | - | | View policies, modes, and scope | `policies:view` | | Change a policy's mode or scope | `policies:manage` | | Fix with Clark | Deploy access on the application | | Publish anyway | Deploy access on the application | Admin and Owner get both `policies` actions by default. Developers and end users get neither. ## Related * [Code Security overview](/admin/code-security/index) * [Static analysis](/admin/code-security/static-analysis) * [Security Agent](/admin/code-security/security-agent) * [CVE detection](/admin/code-security/supply-chain/cve-detection) # Code Security Source: https://docs.superblocks.com/admin/code-security/index Superblocks-managed policies that check the code and dependencies in your apps at install, publish, and in production **Code Security** is a set of Superblocks-managed policies that check the code and dependencies shipping in your applications. They let builders move fast on AI-generated code without leaving the Superblocks editor. Superblocks writes and maintains these policies, so there is nothing to author. What separates them from each other is **when they run** and **what they look for**. ## When each policy runs The **Policy Agents** page in the dashboard lists every Superblocks-managed policy, grouped by when it runs. ![Policy Agents page listing Superblocks-managed policies for development, publish, and production](https://mintcdn.com/superblocks/oGCsa1vIICDA_eX7/images/administration/code-security/policy-agents.png?fit=max\&auto=format\&n=oGCsa1vIICDA_eX7\&q=85\&s=4400e07f6a0f7a857671ecb84d392f54) | Moment | Dashboard name | What it does | Where the result appears | | - | - | - | - | | **Development** | Superblocks Package Install Gate | [CVE detection](/admin/code-security/supply-chain/cve-detection) before Clark adds a package, including malware advisories and a 7-day cooldown on brand-new npm releases | Clark chat, when the package is requested | | **Publish** | Superblocks Security Scan | [Static analysis](/admin/code-security/static-analysis) of source and built artifacts, plus [CVE detection](/admin/code-security/supply-chain/cve-detection) on the snapshot being published | **Pre-Publish Policies** on the publish detail | | **Publish** | Superblocks Security Agent | The [Security Agent](/admin/code-security/security-agent) reviews the application the way a security engineer would | **Pre-Publish Policies** on the publish detail | | **Production** | Superblocks Vulnerability Detection | [CVE detection](/admin/code-security/supply-chain/cve-detection) re-runs against published apps as new advisories appear | [Security Center](/admin/code-security/supply-chain/cve-detection#continuous-monitoring) and [notifications](/admin/code-security/supply-chain/cve-notifications) | Pre-publish policy agents are currently skipped for apps [connected to Git](/development-lifecycle/version-control/connect-to-git). For Git-connected apps, run equivalent security checks in your CI pipeline. The Policy Agents page shows this limit. CVE detection is one policy evaluated at three moments. At development time it is the Package Install Gate in Clark chat, with malware checks and the cooldown on top of the CVE lookup. At publish time it is part of the Security Scan. In production it is Vulnerability Detection, against apps already live. ## What each policy looks for > [card] [Static analysis](/admin/code-security/static-analysis) > > Deterministic scanning for hardcoded secrets and insecure code patterns > [card] [Security Agent](/admin/code-security/security-agent) > > An AI reviewer that reasons about your application the way a security engineer would > [card] [CVE detection](/admin/code-security/supply-chain/cve-detection) > > Known advisories against the npm packages your app depends on Static analysis and the Security Agent are complementary. Static analysis matches known-bad patterns and is deterministic, so the same code always produces the same findings. The Security Agent reasons about application logic and catches issues pattern matching misses, such as a missing authorization check or PII returned in an API response. ## Shared behavior Once a publish-time policy produces a finding, the rest is the same no matter which policy found it: severity, scan mode, remediation with **Fix with Clark**, run errors, and the audit trail. That is covered once in [How findings work](/admin/code-security/how-findings-work). The short version: **only** **critical** and **high** findings can block a publish, and whether they do depends on the [scan mode](/admin/code-security/how-findings-work#scan-modes) an admin sets per policy. CVE detection applies whether you use the default public registry or configure an optional [private registry](/admin/code-security/supply-chain/private-registries). ## Packages Beyond the policies themselves, Superblocks gives you visibility and control over the packages your apps depend on: * **[CVE notifications](/admin/code-security/supply-chain/cve-notifications)**: alert admins and app creators when a newly disclosed critical or high CVE lands on a published app * **[CVE exceptions](/admin/code-security/supply-chain/cve-exceptions)**: template packages Superblocks excludes because the advisory is not exploitable and cannot be upgraded today * **[SBOM](/admin/code-security/supply-chain/sbom)**: view and export an application's package inventory as a CycloneDX document * **[Private registries](/admin/code-security/supply-chain/private-registries)**: route every `npm install` through a registry your security team already trusts, such as CodeArtifact, Artifactory, or Nexus ## Permissions **`policies:manage`** configures policies, modes, and scope. **`policies:view`** reads policies and sees every application in Security Center. Without `policies:view`, a builder still opens Security Center for the applications they can edit. Deploy access gates **Fix with Clark**, **Unpublish**, and **Publish anyway**. ## Related * [How findings work](/admin/code-security/how-findings-work): severity, scan modes, remediation, and audit * [Knowledge](/building-with-clark/knowledge/index): guide Clark while it writes code, so fewer findings appear at publish time # Security Agent Source: https://docs.superblocks.com/admin/code-security/security-agent An AI security reviewer that reads your application end to end and reports exploitable findings before publish The **Security Agent** is a Superblocks-managed [Code Security](/admin/code-security/index) policy that reads your application the way a security engineer would. Where [static analysis](/admin/code-security/static-analysis) matches known-bad patterns, the agent follows data across pages, APIs, and integrations to reason about whether an issue is actually exploitable in context. It runs on Claude and follows the approach of Anthropic's open-source [Claude Code security review](https://github.com/anthropics/claude-code-security-review), with a Superblocks-specific policy and application context layered on top so platform-enforced protections are not reported as findings. ## What it looks for By default the agent performs a comprehensive security review covering: * Hardcoded secrets, API keys, tokens, and passwords in source code * SQL, code, command, SSRF, and template injection * Cross-site scripting from user-controlled data rendered as raw HTML * Missing or broken authentication and authorization checks * Sensitive data (PII, credentials) logged, leaked in responses, or stored insecurely * Weak or deprecated cryptography * Insecure network configuration: wildcard CORS, disabled TLS verification, open redirects * Insecure deserialization and unrestricted file uploads * API endpoints that return excessive data or expose internal details The agent also reports security concerns that do not fit these categories. It is read-only: it evaluates and reports, and never modifies the application. ## When it runs The Security Agent runs at **publish time**, against a frozen snapshot of the application. It runs in parallel with static analysis and publish-time CVE detection, and appears as its own item under **Pre-Publish Policies**. The agent is currently skipped for apps [connected to Git](/development-lifecycle/version-control/connect-to-git). For Git-connected apps, run equivalent security checks in your CI pipeline. ## Superblocks-aware analysis The agent receives context about the Superblocks execution model along with the application, which keeps findings grounded: * **Platform authentication and access control.** Users must be authenticated to open a Superblocks app, and each app has its own access control list. The agent does not flag an API for "missing authentication" simply because the API code has no explicit check. It flags authorization issues when an API takes a sensitive identifier from client input instead of reading the authenticated user from server-side context. * **Bindings are not eval.** `{{ }}` bindings are evaluated in a controlled sandbox and are not treated as injection. * **Integrations.** Integration configuration is inspected for leaked credentials and insecure settings. * **Severity reflects exploitability.** Mitigations such as input validation, escaping, or platform-level access control lower severity. Developer comments explaining a deliberate trade-off are acknowledged rather than re-flagged. Raw secret values are never echoed in findings. They are redacted. ## Configuration Admins set **Mode** and **Scope** from **Policy Agents** in the dashboard. Name, prompt, and enablement are Superblocks-managed and cannot be edited. | Setting | Description | | - | - | | **Mode** | The [scan mode](/admin/code-security/how-findings-work#scan-modes) applied to critical and high findings | | **Scope** | **All apps**, or **Limited** to the apps you select. See [How findings work](/admin/code-security/how-findings-work#scope) | ## What its findings include On top of the fields every policy reports, an agent finding adds: | Field | Description | | - | - | | **Category** | The class of issue, such as a leaked secret or an injection risk | | **Evidence** | The specific code that triggered the finding, with secrets redacted | | **Suggested fix** | How to resolve the issue | Findings that require credential rotation, external account changes, infrastructure work, or a human policy decision are marked as not remediable by Clark. ## Findings and enforcement Severity, scan modes, remediation with **Fix with Clark**, run errors, and the audit trail are the same for every publish-time policy. See [How findings work](/admin/code-security/how-findings-work). ## Billing The Security Agent consumes GAUs from your organization's shared pool, the same as other Clark AI interactions. Usage appears in your [billing dashboard](/admin/self-serve-plan) under *Superblocks Security Agent*. ## Related * [How findings work](/admin/code-security/how-findings-work) * [Static analysis](/admin/code-security/static-analysis) * [CVE detection](/admin/code-security/supply-chain/cve-detection) # Static analysis Source: https://docs.superblocks.com/admin/code-security/static-analysis Detect hardcoded secrets and insecure code patterns in AI-generated code before they reach production **Static analysis** is a Superblocks-managed [Code Security](/admin/code-security/index) policy that inspects your application source and built artifacts before publish. It runs Semgrep against the snapshot being published. It is deterministic: the same code always produces the same findings. There is no configuration beyond enabling it and choosing a [scan mode](/admin/code-security/how-findings-work#scan-modes). Superblocks maintains the rules and normalizes results into findings. ## What it scans Findings fall into these categories. Superblocks maintains the Semgrep rule packs behind them and adds to them over time. | Category | What it checks | Example findings | | - | - | - | | **Leaked secrets** | Source and built artifacts for hardcoded credentials of any kind | API key hardcoded in a backend query, private key committed to source, database connection string in a config file | | **Injection** | Untrusted input reaching an interpreter, query, or shell | SQL injection from an unsanitized parameter, command injection in a shell call, unsafe deserialization | | **Frontend** | Client-side and React code that renders or handles untrusted data | Cross-site scripting through `dangerouslySetInnerHTML`, an unsafe `href` built from user input, a token written to `localStorage` | | **Backend** | Server-side handlers and integration code | Path traversal on a file read, server-side request forgery from a user-supplied URL, disabled TLS certificate verification | | **API surface** | How endpoints are exposed and configured | Wildcard CORS on a credentialed endpoint, credentials embedded in an outbound request URL, error responses that return stack traces | | **Crypto and configuration** | Algorithms, key handling, and framework settings | MD5 or SHA-1 used for password hashing, a hardcoded salt or initialization vector, cookies set without `Secure` or `HttpOnly` | Built-asset scanning is the authoritative gate for secrets. It checks the final bundle that would ship to production, not just the source, so a secret is caught regardless of how it reached the build output. It is also what decides blocking: a finding in the built assets can block a publish, while a finding in source alone is reported without blocking. Static analysis reports what it can see in the code itself. Issues that depend on application logic, such as an endpoint that skips an authorization check or returns another user's data, are the [Security Agent](/admin/code-security/security-agent)'s job. ## When it runs Static analysis runs at **publish time**, after the application is built and before it deploys. It evaluates the exact artifact that would ship, so there is no gap between what was checked and what was deployed. Builders do not trigger scans manually. The scan runs in the background and results appear under **Pre-Publish Policies** on the publish detail. ## How it compares | | Static analysis | [Security Agent](/admin/code-security/security-agent) | | - | - | - | | **Method** | Pattern matching with Semgrep | AI reasoning over application logic | | **Result** | Deterministic and repeatable | Varies with context and evidence | | **Catches** | Known-bad patterns and exposed secrets | Exploitable issues that span pages, APIs, and integrations | The two are complementary and run in parallel. For dependency and package advisories, see [CVE detection](/admin/code-security/supply-chain/cve-detection). ## Findings and enforcement Severity, scan modes, remediation with **Fix with Clark**, run errors, and the audit trail are the same for every publish-time policy. See [How findings work](/admin/code-security/how-findings-work). ## Related * [How findings work](/admin/code-security/how-findings-work) * [Security Agent](/admin/code-security/security-agent) * [CVE detection](/admin/code-security/supply-chain/cve-detection) * [Private registries](/admin/code-security/supply-chain/private-registries) # CVE detection Source: https://docs.superblocks.com/admin/code-security/supply-chain/cve-detection Check npm packages against known advisories at install time, at publish time, and continuously in production **CVE detection** is a Superblocks-managed [Code Security](/admin/code-security/index) policy that checks the npm packages your apps depend on against known vulnerability and malware advisories. It is the only policy that runs at all three moments in the app lifecycle: | Moment | What it does | Where the result appears | | - | - | - | | **Install time** | Checks the requested package before Clark adds it, including a 7-day cooldown on brand-new releases | Clark chat | | **Publish time** | Re-checks dependencies on the snapshot being published | Publish readiness checklist | | **Production** | Re-evaluates published apps as new advisories appear, with no app change required | Security Center and notifications | All three use the same vulnerability index, sourced from [osv.dev](https://osv.dev) for the npm ecosystem and refreshed hourly. Superblocks also maintains a [CVE exceptions](/admin/code-security/supply-chain/cve-exceptions) list for packages that ship in Superblocks templates. Those packages have known advisories that Superblocks has reviewed as not exploitable in this platform, and that Superblocks cannot upgrade today, or that have no upgrade available. [Private registries](/admin/code-security/supply-chain/private-registries) control where packages come from. CVE detection decides which versions are safe to install and stay in production. ## Install time When [Clark](/building-with-clark/index) installs an npm package, Superblocks checks the requested package and version against the vulnerability index before the install runs. | Outcome | What happens | | - | - | | **Safe version** | The package installs. If a safer version of the same package exists, Clark installs that version instead | | **Malware advisory** | The install is blocked. Clark picks a different reputable package that serves the same purpose | | **CVE with no safe version** | The install is blocked. Clark tries a different package, or builds the capability another way | If you named the package in chat and a CVE blocks it, Clark warns you. You can proceed with a short reason, which Superblocks records in the audit log. Malware blocks have no proceed path. This is a gate, not a finding. It resolves before the package is ever installed, so there is no scan mode to configure and nothing to remediate later. ### 7-day cooldown Brand-new npm releases are held back for **7 days** before Superblocks installs them. If Clark requests a version published inside that window, Superblocks prefers the newest version outside it, when one exists. This reduces exposure to compromised or malicious fresh publishes without asking builders to track package age themselves. ## Publish time At publish time, CVE detection re-checks the dependencies on the snapshot being published and contributes findings to the publish readiness checklist, alongside [static analysis](/admin/code-security/static-analysis) and the [Security Agent](/admin/code-security/security-agent). This catches what the install-time gate cannot: an advisory disclosed after the package was installed, and a transitive dependency pulled in later. Because these are findings on a publish, they follow the shared rules for severity, scan mode, and remediation described in [How findings work](/admin/code-security/how-findings-work). ## Continuous monitoring Superblocks keeps evaluating **published** apps after they ship, so a newly disclosed CVE surfaces even when the application has not changed. Results land in **Security Center**. ### Security Center Security Center lives under **Security** in the dashboard. What you see depends on your permissions: | You have | You see | | - | - | | **`policies:view`** | Every application in the organization | | **Edit access on an app**, without `policies:view` | Only the applications you can edit | | Neither | Security Center is hidden | Findings are grouped by app, prioritized by severity, and refreshed as new advisories appear. You do not have to check it manually. Superblocks alerts you when a new critical or high CVE lands on a published app. See [CVE notifications](/admin/code-security/supply-chain/cve-notifications). ![Security Center with summary, dependency scans, and expanded advisories](https://mintcdn.com/superblocks/FKdVPsG09Yh8_1SI/images/administration/policy-agents/security-center-overview.png?fit=max\&auto=format\&n=FKdVPsG09Yh8_1SI\&q=85\&s=ea750dbcea5d7cc0b21c75b727e8c89d) | Surface | Purpose | | - | - | | **Summary** | How many published apps have vulnerabilities, plus counts by severity | | **Applications** | One row per app, with vulnerability count, creator, and status | | **Advisories** | Expand a row for each finding: severity, advisory ID (OSV), package, and detector | The **Applications** tab lists every application in the organization, so a row with no vulnerabilities means that app is clean. Only published apps are scanned. Click **View details** on a row to open its package inventory, described in [SBOM](/admin/code-security/supply-chain/sbom). An app with open package vulnerabilities is **Unresolved**. Use **Fix with Clark** or **Unpublish**, described below. Search by app name, package, or advisory ID. Filter by severity. ### What is scanned * **Scope:** published applications with a deployed commit * **Packages:** dependencies from the deployed commit (`package.json` plus lockfile-resolved versions when available) * **Ecosystem:** npm * **Advisory source:** [osv.dev](https://osv.dev) npm feed * **Detector:** Superblocks Package Scanner Scans evaluate the **deployed** package set, which is what is live, not an uncommitted local workspace. Findings stay current within the hourly index refresh window. ### Fix or unpublish From Security Center, click **Fix with Clark** on an app or an individual advisory: 1. The app opens in the editor with a pre-built remediation prompt 2. Clark upgrades vulnerable packages to safe versions and keeps the app building 3. Publish or redeploy so the deployed package index updates 4. Security Center reflects the remediated packages on the next scan Admins can also **Unpublish** a vulnerable app, which immediately takes it offline for all end users. Republish after the fix to restore access. Both actions require deploy access on the target application. ## Permissions | Action | Permission | | - | - | | View scans and advisories for every app in the org | `policies:view` | | View scans and advisories for one app | Edit access on that application | | List distinct packages across the org (`list_distinct_packages_in_org`) | `policies:manage` | | Fix with Clark / Unpublish from Security Center | Deploy access on the target application | `policies:view` is included for the Admin and Owner roles by default. A builder with no `policies:view` and no editable application cannot open Security Center at all. An admin with `policies:view` can see every vulnerable app but can only fix or unpublish the ones they can deploy. ## Related * [How findings work](/admin/code-security/how-findings-work) * [CVE notifications](/admin/code-security/supply-chain/cve-notifications) * [CVE exceptions](/admin/code-security/supply-chain/cve-exceptions) * [SBOM](/admin/code-security/supply-chain/sbom) * [Private registries](/admin/code-security/supply-chain/private-registries) * [Audit logs](/admin/audit-logs) # CVE exceptions Source: https://docs.superblocks.com/admin/code-security/supply-chain/cve-exceptions Template packages Superblocks excludes from CVE detection because the advisory is not exploitable and cannot be upgraded today Superblocks has a predefined list of exceptions for a small set of packages that are included in new apps. These packages are not exploitable, so this exceptions list avoids false positives for CVEs that cannot be addressed. An excluded package does not block an install, does not produce a publish finding, and does not appear in Security Center. Superblocks maintains the list, and it applies to every organization. Each exception is scoped to one package and one advisory. ## Why a package is excluded Both of these must be true: | Condition | What it means | | - | - | | **Not exploitable** | Superblocks reviewed the advisory against how the template uses the package, and determined an attacker cannot exploit it in a Superblocks app | | **Cannot upgrade** | Superblocks cannot move the template off the affected version today, or no patched version exists | The list is not a place to hide every noisy CVE. It exists so template packages that fail those two tests do not block every new app. ## When an exception is removed An exception is not permanent. Superblocks removes it when either condition no longer holds, most often when a patched version ships and Superblocks can upgrade the template. Once an exception is removed, the advisory behaves like any other finding. It blocks new installs of affected versions, appears at publish time under the policy's [scan mode](/admin/code-security/how-findings-work#scan-modes), and surfaces in Security Center for published apps already on an affected version. If it is critical or high, it also triggers [CVE notifications](/admin/code-security/supply-chain/cve-notifications). ## Requesting a change Exceptions are managed by Superblocks and cannot be edited per organization. There is no way to add your own exception, and no way to opt out of one. If you believe a template package should be excluded, or that an exclusion no longer applies, contact Superblocks support with the advisory ID and the affected package. To accept the risk of a specific finding on a specific app instead, publish under **Blocking with exceptions** and use **Publish anyway**, which records the decision in the audit log. See [How findings work](/admin/code-security/how-findings-work#scan-modes). ## Related * [CVE detection](/admin/code-security/supply-chain/cve-detection) * [CVE notifications](/admin/code-security/supply-chain/cve-notifications) * [How findings work](/admin/code-security/how-findings-work) * [SBOM](/admin/code-security/supply-chain/sbom) # CVE notifications Source: https://docs.superblocks.com/admin/code-security/supply-chain/cve-notifications Alerts sent to admins and app creators when a new CVE affects a published Superblocks application Security Center watches published applications for newly disclosed CVEs. When one lands on a package your organization already ships, Superblocks tells the people who can act on it instead of waiting for someone to open the dashboard. Notifications reach two audiences over two channels: | | In-app (Inbox) | Email (daily digest) | | - | - | - | | **Security admins** | Immediately, per advisory | Once a day, one email for the whole organization | | **App creators** | Immediately, per application | Once a day, one email covering all of their apps | For where the findings come from and how to fix them, see [CVE detection](/admin/code-security/supply-chain/cve-detection). ## Who receives them **Security admins** are everyone holding **`policies:view`**, the same permission that opens the org-wide Security Center. The Admin and Owner roles include it by default. They see every affected application in the organization. **App creators** are the single user who created the application. A creator is notified about their own applications only, and is notified whether or not they hold `policies:view`. Deactivated users are excluded from both audiences. If you hold `policies:view` and you also created an affected app, you get both. That is two Inbox items for the same CVE, and two digest emails that day: one org-wide, grouped by package and advisory, and one covering only your apps, grouped by application. ## When they send Only **critical** and **high** findings send an alert. Everything else still shows in Security Center. Inbox updates as new critical and high CVEs land on published apps. The email is one digest per day. It covers new findings since the last digest, not a repeat of yesterday. ## What is included ### In-app: security admins One notification per package and advisory, listing every application currently affected. | Field | Example | | - | - | | Title | New CVE present in 3 apps: `lodash` | | Advisory | The OSV or CVE identifier, linked to [osv.dev](https://osv.dev) | | Severity | Critical or High | | Summary | The advisory description, with **See more** linking to the full record | | Affected versions | Every installed version across the affected apps | | Affected applications | Each app name and its creator | | Actions | **Fix with Clark** per application, and **View in Security Center** filtered to this advisory | ### In-app: app creators One notification per application, listing the findings detected on that application in this pass. | Field | Example | | - | - | | Title | 2 vulnerabilities detected in Expense Tracker | | Per finding | Advisory ID, severity, `package@version`, summary, and **See more** | | Actions | **Fix with Clark** per finding, and **View in Security Center** | ## Permissions | Action | Permission | | - | - | | Receive the admin in-app notification and admin digest | `policies:view` | | Receive the creator in-app notification and creator digest | Be the creator of the application | | Open **View in Security Center** from a notification | `policies:view`, or edit access on the affected application | | Use **Fix with Clark** from a notification | Deploy access on the target application | ## Related * [CVE detection](/admin/code-security/supply-chain/cve-detection) * [SBOM](/admin/code-security/supply-chain/sbom) * [How findings work](/admin/code-security/how-findings-work) * [Audit logs](/admin/audit-logs) # Private registries Source: https://docs.superblocks.com/admin/code-security/supply-chain/private-registries Keep app dependencies secure and compliant by routing package installs through your own trusted npm registries **Who can use this feature?**\\ Organization Admins and Owners can configure package registries. Only Owners can change the [install policy](#install-policy). Point Superblocks at the npm registries your organization already trusts. Instead of resolving packages from public npm, your builders and [Clark AI](/building-with-clark/index) install from a registry you control. Configure a private registry to: * **Control what gets installed** by resolving dependencies from an allowlist-gated or scanned registry (e.g. Artifactory, Nexus, Verdaccio) instead of the open ecosystem * **Reuse your own packages**, such as a shared design system, component library, or internal utilities published under your own npm scope (e.g. `@mycompany`) * **Fit your network model** in egress-restricted environments where package traffic must flow through an internal registry Once configured, installs resolve through your registries in both Edit mode and production builds. ## How registries are matched Superblocks lets you configure two kinds of registry, mirroring how npm resolves packages through an `.npmrc` file: * A **default registry** (unscoped): the fallback for every package that isn't matched by a scoped registry. * Any number of **scoped registries**, each pinned to a single npm [scope](https://docs.npmjs.com/cli/using-npm/scope) (e.g. `@mycompany`). Packages under that scope resolve from the scoped registry; everything else falls through to the default. For example, if a default registry is configured, plus a `@mycompany` scoped registry, `@mycompany/design-system` will resolve from `https://npm.internal.mycompany.com/`, while an unscoped package like `lodash` (or a public-scope package) resolves from the default registry. If no default registry is configured, packages with no matching scoped registry resolve from the public npm registry (registry.npmjs.org). Scoped registries are optional. If you only need a single registry for all packages, configure the default registry and skip the scoped rows. ## Configure the default registry The **Package Registry** page has three parts: the [install policy](#install-policy) at the top, the default registry row, and any [scoped registries](#add-a-scoped-registry) you add below it. ![Package Registry settings page showing the Install policy card and an unconfigured default registry row](https://mintcdn.com/superblocks/oGCsa1vIICDA_eX7/images/administration/code-security/package-registry-settings.png?fit=max\&auto=format\&n=oGCsa1vIICDA_eX7\&q=85\&s=6a7519ce2aefc28ad9802b743266fff3) 1. Navigate to **Organization Settings > Package Registry** 2. In the **Default** row under **Package Registries**, enter your **Registry URL**, the full URL of your npm-compatible registry (e.g. `https://artifactory.example.com/api/npm/npm-virtual/`) 3. Optionally enter an **Auth token**, a bearer token with read access to your registry (see [Manage auth tokens](#manage-auth-tokens)). The token is encrypted at rest and never exposed in the UI after saving 4. Click **Test connection**. **Save** stays disabled until the probe succeeds (see [Verify a registry](#verify-a-registry)) 5. Click **Save** | Field | Description | | - | - | | **Registry URL** | The full URL of your npm-compatible registry. Must use HTTPS | | **Auth token** | An optional bearer token for the registry. Basic-auth credentials are not supported. Stored encrypted; redacted after saving | The registry URL must use `https://` and must not embed credentials (e.g. `https://user:pass@host/`); use the **Auth token** field instead. HTTP URLs and inline credentials are rejected to prevent secrets from being sent in cleartext. Before creating your first app, ensure your registry (or registries) serve the [core required packages](#core-required-packages) and their transitive dependencies. The editor will not start if any are missing. ## Add a scoped registry Scoped registries route packages under a specific npm scope to a dedicated registry, while all other packages continue to use the [default registry](#configure-the-default-registry). 1. On the **Package Registry** page, click **Add scoped registry** 2. Enter the **Scope** the registry serves, e.g. `@mycompany` (see [Scope format](#scope-format)) 3. Enter the **Registry URL** and, optionally, an **Auth token**, using the same rules as the default registry 4. Click **Test connection** to verify the registry 5. Click **Save** Saved scoped registries appear as collapsible rows under the default registry, each showing its scope, URL, and connection status. Click a row to expand and edit it. ### Scope format A scope must: * Start with `@` * Use only lowercase letters, digits, `.`, `_`, and `-`, beginning with a letter or digit after the `@` (e.g. `@my-company`, `@team.internal`) * Be unique within your organization; you can configure at most one registry per scope Scopes are normalized to lowercase, matching how npm itself treats them. Uppercase input (e.g. `@MyCompany`) is lowercased automatically. A scope is **fixed once the scoped registry is saved**. To reassign a registry to a different scope, delete the row and add a new one. ## Supported registries Superblocks works with any npm-compatible registry. The tabs below show how to get the **auth token** and **registry URL** for the most common ones, assuming your registry already exists and serves the packages you need. Not every registry can be your **default**. A default registry has to resolve every package a Superblocks app needs, including the [core required packages](#core-required-packages) and all of their transitive dependencies, so it must proxy or mirror public npm. Registries that only host your organization's own packages must be added as **scoped** registries instead. > [tab] Verdaccio > > Verdaccio can be used as a **default or scoped registry**: as the default when its `**` package group proxies an npm uplink, or as a scoped registry when it only hosts your internal packages. > > Verdaccio issues npm tokens through the npm CLI. Log in as a user with read access to the packages Superblocks will install, then mint a read-only token: > > ```bash theme={null} > npm login --registry https://npm.example.com/ > npm token create --read-only --registry https://npm.example.com/ > ``` > > Copy the token value from the command output. If your Verdaccio config grants `access: $all`, reads are anonymous and you can leave **Auth token** blank. > > Verdaccio's htpasswd setup produces a base64 `_auth` value. That is a basic-auth credential, so it does not work here (see [Manage auth tokens](#manage-auth-tokens)). Always supply a token minted by `npm token create`. > > **Registry URL:** your Verdaccio base URL, e.g. `https://npm.example.com/` > > Verdaccio doesn't always expose `/-/whoami`, so **Test connection** may report **Reachable, token not verified**. The URL is good, but the token is only exercised on a real install. > [tab] JFrog Artifactory > > Artifactory can be used as a **default or scoped registry**: point the default at a **virtual** repository that includes a remote (proxy) repository, or use a **local** repository, which serves only packages you publish, as a scoped registry. > > Use an **identity token** belonging to a service user with read permission on the repository: > > 1. Log in to Artifactory as the service user > 2. Go to **User menu > Edit Profile > Generate an Identity Token** > 3. Copy the token, which is shown only once > > A scoped **access token** with read permission works as well. Don't use the user's password, and don't embed credentials in the URL. > > **Registry URL:** the npm API path for your virtual repository, e.g. `https://mycompany.jfrog.io/artifactory/api/npm/npm-virtual/` (self-hosted: `https://artifactory.example.com/artifactory/api/npm/npm-virtual/`) > > Identity and access tokens can expire. If installs start failing because the registry rejects the token, [rotate it](#manage-auth-tokens). > [tab] Sonatype Nexus > > Nexus can be used as a **default or scoped registry**: point the default at a **group** repository that includes an npm proxy, or use a **hosted** repository, which serves only packages you publish, as a scoped registry. > > To get a token: > > 1. Enable the **npm Bearer Token Realm** under **Administration > Security > Realms**. Without it, Nexus ignores the `_authToken` Superblocks sends > 2. As a service account with read access (`nx-repository-view-npm-*-read`), log in through npm and copy the generated token out of your `.npmrc`: > > ```bash theme={null} > npm login --registry https://nexus.example.com/repository/npm-all/ > grep _authToken ~/.npmrc > ``` > > If anonymous read access is enabled on the repository, leave **Auth token** blank. > > **Registry URL:** your repository URL, e.g. `https://nexus.example.com/repository/npm-all/` > > If the bearer token realm is disabled, **Test connection** can still report **Reachable** via anonymous access while authenticated installs fail later. Enable the realm before saving a token. > [tab] AWS CodeArtifact > > CodeArtifact can be used as a **default or scoped registry**: as the default when the repository has a `public:npmjs` external connection (directly or through an upstream), or as a scoped registry when it serves only packages you publish. > > CodeArtifact tokens come from the AWS CLI. Use an IAM user or role (not the root user) with `codeartifact:GetAuthorizationToken`, `codeartifact:ReadFromRepository`, `codeartifact:GetRepositoryEndpoint`, and `sts:GetServiceBearerToken`: > > ```bash theme={null} > aws codeartifact get-authorization-token \ > --domain mycompany --duration-seconds 43200 \ > --query authorizationToken --output text > ``` > > Get the matching registry URL with: > > ```bash theme={null} > aws codeartifact get-repository-endpoint \ > --domain mycompany --repository superblocks --format npm > ``` > > **Registry URL:** e.g. `https://mycompany-111122223333.d.codeartifact.us-east-1.amazonaws.com/npm/superblocks/` > > **CodeArtifact tokens expire within 12 hours** (43200 seconds is the maximum), and Superblocks stores the token you paste as a static value, so it can't refresh it for you. When the token expires, the registry rejects it and every install fails. Set up [automated token rotation](#rotate-tokens-with-the-api) before builders depend on the registry. > [tab] GitHub Package Registry > > GitHub Packages can only be used as a **scoped registry**. It serves only packages named `@OWNER/package` and never proxies public npm, so it can't resolve the [core required packages](#core-required-packages), and using it as the default registry prevents the editor from starting. Set the **Scope** to the GitHub account name, lowercased (e.g. `@mycompany`), and keep a proxying registry (or public npm) as the default. > > Create a **personal access token (classic)** with the `read:packages` scope, owned by a machine user that has read access to the packages. That token value is the `_authToken`. > > `GITHUB_TOKEN` and fine-grained tokens don't work here: the former is scoped to a single workflow run, and the latter doesn't cover the npm registry. > > **Registry URL:** `https://npm.pkg.github.com` > [tab] GitLab Package Registry > > The GitLab package registry can only be used as a **scoped registry**, matching your GitLab namespace scope (e.g. `@mycompany`). It serves only packages scoped to its own namespaces and isn't a public npm mirror: request forwarding to npmjs.com is an admin-toggleable Premium/Ultimate self-managed setting, not a substitute for a proxy. Keep a proxying registry as the default. > > Create a **deploy token** with the `read_package_registry` scope. A group-level deploy token is the most durable option, since it isn't tied to a user. A personal access token with the `api` scope also works. Use the token value as the `_authToken`. > > **Registry URL:** whichever endpoint matches how your packages are organized: > > | Endpoint | URL | > | - | - | > | Instance | `https://gitlab.example.com/api/v4/packages/npm/` | > | Group | `https://gitlab.example.com/api/v4/groups//-/packages/npm/` | > | Project | `https://gitlab.example.com/api/v4/projects//packages/npm/` | > > GitLab.com uses the same paths under `https://gitlab.com`. ## Verify a registry Click **Test connection** next to any Registry URL to probe the registry before (or after) saving. Superblocks resolves the host, opens a connection, and reports a status badge on the row: | Badge | Meaning | | - | - | | **Reachable** | The registry responded and, if a token was supplied, accepted it | | **Reachable, token not verified** | The registry responded but doesn't expose `/-/whoami`, so the token couldn't be validated. Install problems will only surface when Clark or a build job actually installs a package | | **Unreachable** (or a specific error) | The probe failed. See the reason below the field | Common failure reasons: | Reason | Meaning | | - | - | | Couldn't reach the registry | The host could not be resolved or connected to | | The registry returned an invalid TLS certificate | TLS/certificate validation failed | | The registry rejected your auth token | Authentication failed. Check the token | | This registry requires authentication (supply an auth token and re-test) | The registry needs a token but none was provided | | This URL doesn't look like an npm registry | The endpoint didn't respond like an npm registry | | The registry took too long to respond | The probe timed out | | A network proxy blocked the request | An outbound proxy blocked the connection | When you edit a saved registry's URL, the stored auth token is **not** reused against the new URL. For security, a stored token is only ever sent to its original host. Enter a new token (or **Clear token**) before saving a URL change. ## Manage auth tokens The **Auth token** must be a bearer token. Superblocks always sends it as the npm `_authToken`, which reaches your registry as an `Authorization: Bearer ` header. That is true on every path: the **Test connection** probe, and every install forwarded through the Superblocks proxy. Leave the field blank for registries that serve anonymous reads. Basic-auth credentials are **not supported** in any form: no `username:password` pair, no base64 `_auth` value (such as the one an htpasswd setup produces), and no credentials embedded in the registry URL. Mint a bearer token in your registry instead. The [Supported registries](#supported-registries) tabs show how for each one. Once saved, a token is write-only: * It is **encrypted at rest** and never retrievable from the dashboard; the field shows only a redacted preview. * To **rotate** it, enter a new value and save. * To **remove** it, click **Clear token** and save. ### Rotate tokens with the API Registries that issue short-lived tokens, such as [AWS CodeArtifact](#supported-registries) with its 12 hour maximum lifetime, need the stored token refreshed regularly. Rather than pasting a new value by hand, rotate it programmatically on a schedule (for example a cron job in CI, or an EventBridge-triggered Lambda) using the Superblocks npm registry API. Authenticate the calls with the **personal API key** of a user who has permission to update package registries, sent as a bearer token. Copy it from **Personal Settings > API Key** (see [Access tokens](/admin/org-administration/auth/access-tokens#personal-api-key)). Org-level access tokens don't work for these endpoints. For automation, use the key of a dedicated service user rather than an individual's, so rotation keeps working when someone's permissions or employment change. First list your registries to find the ID of the one to update: ```bash theme={null} curl --location --globoff 'https://.superblocks.com/api/v1/organizations//npm-registry' \ --header 'Authorization: Bearer ' ``` Then `PUT` the new token, passing the registry URL along with it: ```bash theme={null} curl --location --globoff --request PUT 'https://.superblocks.com/api/v1/organizations//npm-registry/' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "registryUrl": "", "token": "" }' ``` Schedule your rotation job comfortably inside the token lifetime, e.g. every 6 hours for a 12 hour token, so a single failed run doesn't leave you with an expired token. Registry IDs are stable, so you only need to look them up once. Always send `registryUrl` together with the new `token`. A stored token is only ever sent to the host it was saved against, so changing one without the other can leave the registry unauthenticated. ## Network requirements Package installs reach your registry through the Superblocks npm proxy, which runs in the Superblocks control plane. The data plane never connects to your registry. For Superblocks Cloud (SaaS) and [Hybrid](/enterprise/hybrid-architecture/overview) organizations, the control plane runs in Superblocks' cloud, so your registry must be reachable from Superblocks' infrastructure, even when your data plane runs inside your own VPC. The **Network requirements** section on the Package Registry page lists the source **egress IPs** Superblocks connects from; your registry must accept **TCP/443** from these addresses. Use **Copy** or **Copy all** to add them to your registry's or firewall's allowlist. The Network requirements section only appears for deployments where egress IPs are published. [Cloud-prem](/enterprise/cloud-prem/aws) and self-hosted deployments run their own control plane and own the network path to the registry, so no allowlist is shown. ## Install policy Separately from registry configuration, an organization **Owner** controls whether npm packages may run lifecycle scripts. The setting is organization-wide and applies to every install, whichever registry serves the package. Admins who can manage registries still see the control, but it is read-only for them. Some npm packages run lifecycle scripts during installation. For example, `sharp` and `better-sqlite3` compile native binaries. Disabling the scripts prevents arbitrary code execution at install time, but packages that depend on them fail to build. Toggle **Allow install scripts** in the **Install policy** section of the Package Registry page: | Setting | Behavior | | - | - | | **Enabled** (default) | Packages run their `preinstall`, `install`, and `postinstall` scripts normally | | **Disabled** | Installs run with `--ignore-scripts`, and the synthesized `.npmrc` carries `ignore-scripts=true`, so lifecycle scripts never execute | ## How installs work Superblocks synthesizes an `.npmrc` for every install surface: Clark, the dev server, and the build pod. It carries a top-level `registry=` line for the default registry, plus one `@scope:registry=` line per scoped registry. A package [resolves](#how-registries-are-matched) the same way whichever surface installs it. Those lines point at the Superblocks npm proxy, not at your registry URL. The install authenticates to the proxy with the machine's own Superblocks token. The proxy decrypts your stored auth token server-side and forwards the request upstream. Your registry credential never lands in an `.npmrc` on a pod or a laptop, and your registry sees the connection arrive from the Superblocks [egress IPs](#network-requirements). Before it installs a package, Clark checks the registry that would serve it. If the package is missing, Clark stops and says an admin may need to mirror it, instead of quietly substituting something else. Clark also never refactors an app away from a [core dependency](#core-required-packages) that fails to install. When an install does fail, Clark names one of three causes: the registry returned 404, the registry rejected the auth token, or the registry could not be reached. [Troubleshooting](#troubleshooting) covers each one. For [cloud-prem](/enterprise/cloud-prem/aws) customers who own their network infrastructure, pair this configuration with network-level controls (e.g. VPC egress rules, NetworkPolicy) that block traffic to `registry.npmjs.org`. ## Core required packages Every Superblocks application ships with a fixed set of npm dependencies. All of these must be resolvable from your registry, or the editor will not start. There are two tiers: * **Platform-critical**: the editor, dev server, and build pipeline require these to function. Clark will never suggest removing them; the only fix for a missing one is for an admin to mirror it into the registry. * **Template defaults**: included in new apps (e.g. Radix UI, Lucide, Recharts). Clark can refactor these away if a builder asks, but they must be available when an app is first created. ### Platform-critical packages These packages cannot be removed or replaced. If any are missing from your registry, the editor will fail to start and Clark cannot work around it. #### `@superblocksteam/*` scoped packages All packages under the `@superblocksteam` scope are platform-owned and protected. These are published to the public npm registry (`registry.npmjs.org`). They resolve through your **default** registry unless you add a scoped registry for `@superblocksteam`. If you do, that registry must serve every package below, or the editor will not start. | Package | Role | | - | - | | `@superblocksteam/library` | Core runtime library (component model, state, evaluator) | | `@superblocksteam/sdk-api` | SDK API type definitions | | `@superblocksteam/library-shared` | Shared types consumed by the library and platform | | `@superblocksteam/shared` | Platform-wide shared types and protobuf definitions | | `@superblocksteam/types` | Generated protobuf type bindings | | `@superblocksteam/sabs-types` | Build service type definitions | | `@superblocksteam/fast-deep-equal` | Deep-equality utility | | `@superblocksteam/cli` | Official Superblocks CLI (local dev, resource sync) | | `@superblocksteam/iso-currency` | Currency formatting and data | #### Unscoped platform packages | Package | Role | | - | - | | `react` | React runtime | | `react-dom` | React DOM renderer | | `react-router` | App page routing | | `react-router-dom` | Routing for apps carried over from earlier templates | | `vite` | Dev server and production build tool | | `typescript` | Type checking in the build pipeline | | `@tailwindcss/vite` | Tailwind CSS Vite plugin | | `tailwindcss` | Tailwind CSS framework | ### Direct dependencies A newly created app declares around 55 direct dependencies, plus the Superblocks CLI. npm also installs their transitive dependencies, which come to hundreds of packages. The exact set depends on your Superblocks version. > [tab] Pull-through cache (Artifactory, Nexus, Verdaccio proxy) > > If your registry is configured as a remote proxy, it will automatically fetch transitive dependencies on cache miss. Ensure the platform-critical packages listed above are reachable through your proxy, and the rest will resolve automatically. > > The first app creation may be slower than usual while the cache warms. > [tab] Curated allowlist > > If your registry requires explicit approval for every package, start from the direct dependency list. Download it and feed it to your approval pipeline: > > [Download superblocks-core-packages.json](/admin/assets/superblocks-core-packages.json) > > This JSON file lists each direct dependency and the Superblocks CLI, with the version ranges a new app requests. Your approval pipeline must also approve their transitive dependencies. To get the full set, resolve the list against public npm (for example, `npm install --package-lock-only` with these packages as dependencies) and approve every package in the resulting lockfile. > > The transitive dependencies include **platform-specific optional binaries** (`@esbuild/linux-x64`, `@rollup/rollup-darwin-arm64`, etc.). npm only installs the ones matching the target platform, but your registry must serve the binaries for every platform where Superblocks runs. Package versions and transitive dependencies may change between Superblocks releases. Use the [Superblocks MCP server](/admin/mcp-server) to query packages currently in use across your organization for the latest inventory. ## Package inventory Admins can list the distinct npm packages in use across all applications using the [Admin MCP](/admin/mcp-server) tool `list_distinct_packages_in_org`. This requires the **`policies:manage`** permission (included for Admin and Owner roles by default; assignable to other roles). * **Registry reconciliation**: compare installed packages against what your private registry serves to find gaps before they cause install failures * **Audit and compliance**: maintain visibility into your organization's npm dependency footprint * **Migration planning**: identify which apps need attention when tightening registry policies Ask your AI coding agent: ```text theme={null} What npm packages are in use across my Superblocks organization? ``` ## Troubleshooting > [accordion] The registry returned 404 for a package > > The requested package exists on public npm but has not been added to your private registry. If your registry is a **pull-through cache** (e.g. Artifactory configured as a remote proxy), the package should appear automatically on first request. If your registry uses a **curated allowlist**, your security team needs to approve and mirror the package before it can be installed. > [accordion] The registry rejected the auth token > > The auth token saved in Package Registry settings is invalid or expired. Navigate to **Organization Settings > Package Registry**, enter a fresh token, and save. Tokens from registries like Artifactory and Nexus may have expiration policies. Coordinate with your registry administrator on rotation schedules. > [accordion] The registry could not be reached > > Superblocks could not reach your registry. Common causes: > > * The registry URL is incorrect or has a typo > * The registry is behind a firewall that does not allow traffic from Superblocks infrastructure > * The registry service is temporarily down > > Verify the URL is correct and that your registry accepts connections from the Superblocks control plane, which is where package installs are proxied from. The data plane does not need access to your registry. > > * **Superblocks Cloud and [Hybrid](/enterprise/hybrid-architecture/overview):** the control plane runs in Superblocks' cloud, so your registry must allow the Superblocks egress IPs on TCP/443 (see [Network requirements](#network-requirements)). > * **[Cloud-prem](/enterprise/cloud-prem/aws):** ensure the Superblocks control plane in your cloud account has network connectivity to your registry. > [accordion] Editor fails to start after configuring a private registry > > The editor requires every [core required package](#core-required-packages) and all of their transitive dependencies to boot a new 3.0 app. If any are missing from your registry, the dev server will fail to start. Check the [core required packages](#core-required-packages) section and ensure all platform-critical packages and their transitive dependencies are available. For pull-through caches, the first app creation may be slower than usual while packages are fetched on cache miss. > [accordion] Scoped packages resolve from the wrong registry > > Package resolution is matched by npm scope. Confirm the package name's scope exactly matches a configured scoped registry (e.g. `@mycompany/utils` requires a `@mycompany` scoped registry). Packages whose scope has no dedicated registry (and all unscoped packages) resolve from the [default registry](#configure-the-default-registry). Scopes are case-insensitive and stored lowercase, so `@MyCompany` and `@mycompany` are treated as the same scope. > [accordion] Can't change a scoped registry's scope > > A scope is fixed once a scoped registry is saved. To move a registry to a different scope, delete the existing row and [add a new scoped registry](#add-a-scoped-registry) with the correct scope. > [accordion] Native packages fail to build after disabling install scripts > > Packages like `sharp`, `better-sqlite3`, and `node-canvas` require lifecycle scripts to compile native binaries. If an Owner disabled **Allow install scripts**, these packages fail to build. > > Either re-enable install scripts, or work with your security team to pre-build and publish these native packages as pre-compiled binaries in your registry. ## Related * [CVE detection](/admin/code-security/supply-chain/cve-detection) * [Code Security overview](/admin/code-security/index) # SBOM Source: https://docs.superblocks.com/admin/code-security/supply-chain/sbom View and download the software bill of materials for a Superblocks application in CycloneDX format Superblocks indexes the npm packages in every application and exposes them as a **software bill of materials (SBOM)**. Security and platform teams get the package inventory without asking builders for it, and can feed the export into their own scanners and asset inventory. Each SBOM belongs to one application at one commit. It lists the declared and resolved version of every direct and transitive dependency, and marks the ones with a known advisory. ## View an SBOM 1. Open **Security Center** under **Security** in the dashboard 2. On the **Applications** tab, find the application 3. Click **View details** 4. The **Packages** tab lists the indexed packages | Column | What it shows | | - | - | | **Package** | The npm package name, linked to its npm page | | **Declared** | The version range declared in `package.json` | | **Resolved** | The exact version the lockfile resolved to, or `-` if it could not be determined | | **Type** | **Direct** if the application declares it, **Transitive** if a dependency pulled it in | | **Vulnerabilities** | A severity badge linked to the advisory on [osv.dev](https://osv.dev), or `-` | ### Choose a commit The commit picker at the top of the table selects which snapshot you are looking at. It defaults to the **Deployed** commit, which is what is live for end users. Switch to **Latest** or any other indexed commit to see the package set at that point. Packages are indexed when a commit is created and when an application is deployed, so an application that has never been deployed shows an empty table until it is. ## Download an SBOM Click **Download SBOM** on the Packages tab. The file covers the commit currently selected in the picker. | | | | - | - | | **Format** | CycloneDX 1.5, JSON | | **File name** | `{application-name}-sbom-{commit-id}.cdx.json` | | **Scope** | One application at one commit | Each component in the document carries the package name, the resolved version, and a Package URL (`pkg:npm/...`), which is what most SBOM tooling keys on. The root component in `metadata` identifies the application, and its version is the commit ID, so two exports of the same app are directly comparable. ## Programmatic access Use the [Superblocks MCP server](/admin/mcp-server) to pull SBOMs without the dashboard. | Tool | What it returns | | - | - | | `get_app_sbom` | The CycloneDX 1.5 document for one application. Defaults to the deployed commit; pass a commit ID for a specific snapshot | | `find_apps_by_package` | Every application using a given package | | `list_distinct_packages_in_org` | The distinct package footprint across the whole organization. Requires `policies:manage` | `list_distinct_packages_in_org` is the org-wide view. The Security Center SBOM is per application, so use the MCP tool when you need one inventory across the fleet rather than an app-by-app export. ## Limits * **Ecosystem:** npm only * **Package cap:** 2,000 packages per commit are indexed * **Applications:** an application with no indexed commit has no SBOM ## Permissions An SBOM follows the same access rule as the rest of Security Center: `policies:view` reaches every application in the organization, and edit access reaches one application. | Action | Permission | | - | - | | View or download the SBOM for any app in the org | `policies:view` | | View or download the SBOM for one app | Edit access on that application | | `get_app_sbom` | `policies:view`, or edit access on that application | | `list_distinct_packages_in_org` | `policies:manage` | Admin and Owner get both `policies` actions by default. ## Related * [CVE detection](/admin/code-security/supply-chain/cve-detection) * [CVE notifications](/admin/code-security/supply-chain/cve-notifications) * [Private registries](/admin/code-security/supply-chain/private-registries) * [Superblocks MCP server](/admin/mcp-server) # Manage environments & data tags Source: https://docs.superblocks.com/admin/environments Create data tags and control which data can be accessed in each environment **Who can use this feature?**\\ Users with the `profiles:manage` permission. This permission is included in the built-in **Owner** and **Admin** roles Superblocks has three built-in **environments** that map to your development lifecycle: | Environment | Description | | - | - | | **Edit** | Where developers build your apps | | **Preview** | Where changes are reviewed before going live | | **Production** | Where your live applications run | **Data tags** let you tag different data segments — such as **Staging**, **Production**, or **us-east** — and control which environments each tag is allowed in. ![Environments page](https://mintcdn.com/superblocks/9luYYaGEgXp4pGR_/images/administration/environments/environments-page.png?fit=max\&auto=format\&n=9luYYaGEgXp4pGR_\&q=85\&s=509f50eab3f804e0963299aa0c71eb09) Once created, data tags are associated with [integration configurations](#configure-integration-credentials) and [data plane deployments](/enterprise/hybrid-architecture/plan/index), which are covered below. Your Superblocks account comes with two built-in data tags, **Development** and **Production**. For Hybrid deployments, these two tags with one data plane each are the recommended starting point; see [Plan your data planes](/enterprise/hybrid-architecture/plan/index) before adding more. ## Create a data tag Admins can create new data tags to represent different data environments, regions, or stages. To add a data tag: 1. Navigate to the **[Environments](https://app.superblocks.com/environments)** page under **Organization Settings** 2. Click **Add Data Tag** 3. Provide a unique name and key for your data tag 4. Select which environments (Edit, Preview, Production) this data tag is allowed in 5. Click **Create** ![Create a data tag](https://mintcdn.com/superblocks/9luYYaGEgXp4pGR_/images/administration/environments/create-data-tag.png?fit=max\&auto=format\&n=9luYYaGEgXp4pGR_\&q=85\&s=c1d2b02e39476c818bb09d71ea9ddb53) Each data tag has a unique alphanumeric **key**. The key can be customized when creating the data tag but cannot be changed after creation to prevent references from breaking. ### Environment assignment When creating or editing a data tag, you decide which environments it can be used in. This gives admins control over data access: * A tag allowed only in **Edit** and **Preview** keeps that data source out of production * A tag allowed only in **Production** ensures production credentials are never used during development * A tag allowed in all three environments can be used anywhere Once you've created a data tag, you can start: * [Configuring integration credentials](#configure-integration-credentials) * [Using data tags](/development-lifecycle/build/data-tags) in Applications * [Setting agent tags on a data plane](/enterprise/hybrid-architecture/deployment/multiple_environments) ## Configure integration credentials In Superblocks, integrations can have multiple configurations to connect to different database instances or API servers. Each configuration is linked to one or more data tags. When you create a new integration, Superblocks automatically generates two configurations: | Configuration | Data tags included | Description | | - | - | - | | **Non-Production** (Default) | All data tags where **none** of their allowed environments is Production | Safe for development and testing | | **Production** | All data tags where **at least one** allowed environment is Production | Isolated production credentials | You can add additional configurations as needed. To update or add configurations: 1. Navigate to [Integrations](https://app.superblocks.com/integrations) and search for your integration or create a new one 2. To add a configuration, click the ➕ icon for "Add new configuration" and select the data tag(s) 3. Fill out the configuration form with values specific to the selected data tags 4. Click **Test Connection** to verify connectivity 5. **Create** or **Save** your changes ![Default integration configurations](https://mintcdn.com/superblocks/9luYYaGEgXp4pGR_/images/administration/environments/default-config.png?fit=max\&auto=format\&n=9luYYaGEgXp4pGR_\&q=85\&s=3ad3f9665e30e1208eab45fb9de81d1c) ## Using data tags For details on how to use data tags in your Applications, see [Using data tags](/development-lifecycle/build/data-tags). Data tags were previously called **profiles**. The core concept is the same — admins now have more control over which data tags are allowed in each environment. # Admin MCP Source: https://docs.superblocks.com/admin/mcp-server Connect AI coding agents to administer your Superblocks org via the Model Context Protocol The Admin MCP server lets AI coding agents (Cursor, Claude Code, Windsurf, and others) administer your Superblocks organization directly. Agents can list applications, manage integrations, deploy apps, manage access control, and more — all through the [Model Context Protocol](https://modelcontextprotocol.io/). Looking to build, edit, and publish apps conversationally from Claude? See [Superblocks in Claude](/building-with-clark/superblocks-in-claude). The Admin MCP on this page is for administering your org from AI coding agents. ## Quickstart Connect to the hosted Superblocks MCP server — no install required. You'll need your Superblocks API token, which you can find in [Personal Settings > API Key](https://app.superblocks.com/personal-settings#apiKey). The hosted server runs at `https://{tenant}.superblocks.com/mcp`. Replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). > [tab] Cursor > > [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=superblocks\&config=eyJ1cmwiOiJodHRwczovL2FwcC5zdXBlcmJsb2Nrcy5jb20vbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfVE9LRU4ifX0%3D) > > Click the button to install, then replace `YOUR_TOKEN` with your API token in **Cursor Settings > MCP**. The button installs the Cloud US server; on Cloud EU or a Cloud-Prem instance, also change the URL to `https://{tenant}.superblocks.com/mcp`. > > Or add it manually: > > ```json theme={null} > { > "mcpServers": { > "superblocks": { > "url": "https://{tenant}.superblocks.com/mcp", > "headers": { > "Authorization": "Bearer " > } > } > } > } > ``` > [tab] Claude Code > > Run this command in your terminal: > > ```bash theme={null} > claude mcp add --transport http \ > --header "Authorization: Bearer " \ > superblocks https://{tenant}.superblocks.com/mcp > ``` > [tab] Other MCP clients > > Point your MCP client at the following URL with an `Authorization` header: > > ``` > URL: https://{tenant}.superblocks.com/mcp > Header: Authorization: Bearer > ``` ## What can the MCP server do? Once connected, AI agents can use the following capabilities through natural language: | Category | Examples | | - | - | | **Applications** | List apps, view structure, check commit history, deploy, undeploy | | **Integrations** | List, create, update, and delete integrations | | **Access control** | View and manage application, workflow, and job permissions | | **Role management** | Assign and update org-level roles for users and groups | | **Organization** | View org summary, list members, manage builder seats | | **Folders** | Create, update, and delete folders | | **Audit** | Query audit events and compute aggregated metrics | | **Chat history** | Retrieve Clark AI conversation history for any application | | **Billing** | View plan summary and usage | | **Supply chain** | Fetch an app's SBOM, find apps by package, list npm packages across the org | | **Code security** | Read fleet CVE findings, check packages before install, list accepted advisories | | **Policy agents** | List policies, read run history and findings, check publish gates | | **Knowledge** | List and view Knowledge entries | | **Superblocks Database** | Read-only view of your [Superblocks Database](/admin/superblocks-on-aws/database) estate: summarize databases, instances, and pools per data tag (`get_app_databases_overview`), list every app database with its application, state, and host (`list_app_databases`), list cluster pools and their provisioning runs (`list_app_database_pools`, `get_app_database_pool_provisioning_run`), and check whether an app's database can run on every data tag (`get_application_database_compatibility`). Requires `app_databases:manage` except for the compatibility check. Application listings and summaries also report whether each app has a database, and integration listings flag the ones a database owns | ## Alternative: Local MCP server If you prefer to run the MCP server locally, you can use the CLI-based setup instead. This requires Node.js 22+ and an API token. **1. Authenticate** Run the following command, replacing `` with your Superblocks API key. You can find your API key in [Personal Settings](https://app.superblocks.com/personal-settings#apiKey). ```bash theme={null} npx -y @superblocksteam/mcp-server@beta login --token ``` **2. Install the MCP server** Run the setup command for your IDE: > [tab] Cursor > > ```bash theme={null} > npx -y @superblocksteam/mcp-server@beta setup --client cursor > ``` > > This writes the MCP server configuration to `~/.cursor/mcp.json`. > [tab] Claude Code > > ```bash theme={null} > npx -y @superblocksteam/mcp-server@beta setup --client claude > ``` > > This writes the MCP server configuration to `~/.claude.json`. > [tab] Other MCP clients > > ```bash theme={null} > npx -y @superblocksteam/mcp-server@beta setup > ``` > > This prints the JSON configuration to stdout. Copy it into your MCP client's configuration file. **3. Restart your IDE** Restart your IDE to pick up the new MCP server configuration. You should see **superblocks** listed as a connected MCP server. If you already have the [Superblocks CLI](/building-with-clark/developing-apps-in-code) installed, you can set up the local MCP server through it instead: ```bash theme={null} superblocks login superblocks mcp setup --client cursor ``` On Cloud EU or a Cloud-Prem instance, run `superblocks config set domain {tenant}.superblocks.com` before `superblocks login`. See [Instance URLs](/enterprise/instance-urls) for your `{tenant}` value. Use `--dry-run` to preview the configuration without modifying any files: ```bash theme={null} npx -y @superblocksteam/mcp-server@beta setup --client cursor --dry-run ``` ## Troubleshooting > [accordion] Hosted server: authentication errors > > Verify your API token is correct. You can find or regenerate it in [Personal Settings > API Key](https://app.superblocks.com/personal-settings#apiKey). > > Make sure the `Authorization` header uses the `Bearer` prefix: > > ``` > Authorization: Bearer sb_xxxxxxxxxx > ``` > > If the token was recently regenerated, update it in your MCP client configuration and restart your IDE. > [accordion] Local server: not connecting > > Verify the server starts correctly by running it directly: > > ```bash theme={null} > npx -y @superblocksteam/mcp-server@beta --help > ``` > > If you see the usage text, the server is installed correctly. Restart your IDE and check that the MCP server appears in your IDE's MCP server list. > [accordion] Local server: authentication errors > > Re-run the login command to refresh your token: > > ```bash theme={null} > npx -y @superblocksteam/mcp-server@beta login --token > ``` > > Your token is stored at `~/.superblocks/auth.json`. You can verify it exists: > > ```bash theme={null} > cat ~/.superblocks/auth.json > ``` > [accordion] Local server: Node.js version requirements > > The local MCP server requires Node.js 22 or later. Check your version: > > ```bash theme={null} > node --version > ``` > > The hosted server at `{tenant}.superblocks.com/mcp` has no local requirements. # Access tokens Source: https://docs.superblocks.com/admin/org-administration/auth/access-tokens Superblocks has several integration options that require access tokens or API keys: * **[Superblocks CLI](https://www.npmjs.com/package/@superblocksteam/cli)** - [Source control](/development-lifecycle/version-control/connect-to-git) your Superblocks tools and [edit apps in code](/building-with-clark/developing-apps-in-code) with the Superblocks command line interface. * **[Import](https://github.com/superblocksteam/import-action) and [Export](https://github.com/superblocksteam/export-action) Actions** - Sync changes back to Superblocks using GitHub Actions and GitLab Pipelines. * **[SCIM API](/admin/org-administration/auth/scim)** - Manage Superblocks users and groups programmatically. * **Embed Session API** - Lets you request session tokens for embedded users to grant them access to your embedded applications. ## Personal API key The [Superblocks CLI](https://www.npmjs.com/package/@superblocksteam/cli) and CI actions require a personal API key for authorization. The operations you can perform is tied to your personal permissions within the Superblocks platform. To access your personal API key: 1. Click your avatar in the upper-left corner of the home page and click **Personal Settings** 2. On the left nav, click **API Key** 3. Click the copy icon to copy your API key ## API authentication The [SCIM](/admin/org-administration/auth/scim) and Embed Session API both require org-level access tokens. The set of operations the token can perform is based on the **Token type** set when creating the token. * **Org Admin** - used by the [SCIM API](/admin/org-administration/auth/scim) and has permission to manage org settings, users, and groups * **Embed** - create and manage authenticated session tokens for Embedded Apps users Only organization **Admins** can create and delete org-level access tokens. ### Creating an access token 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. On the left nav, click **Access Tokens** 3. Click **+Create token** 4. In the **Name** field give your token a descriptive name 5. Select an **Expiration** date, or use the default 90 day expiration. 6. Set the **Token type** that you want 7. Click **Create** Save your tokens immediately Your access token is visible one time, immediately after you create it. If you leave or refresh the page where the token is displayed, it will be obscured and no longer visible. You must copy and store new access tokens somewhere secure before you leave the creation page, or you will lose access to the token. ### Deleting an access token Deleting an access token removes it from your account. This is an irreversible action and a deleted token cannot be recovered. For this reason, we recommend creating a new access token and update anywhere you're calling Superblocks APIs, before deleting the token. 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. On the left nav, click **Access Tokens** 3. In the table of access tokens, select Remove next to the token you'd like to delete 4. Confirm in the browser alert # Entra ID SCIM setup Source: https://docs.superblocks.com/admin/org-administration/auth/scim/azure-ad Instructions for setting up SCIM provisioning using Azure Entra ID as an IdP ## Features The following provisioning features are supported when integrating with Entra ID: * Create users in Superblocks * Remove users in Superblocks when they do not require access anymore * Keep user attributes synchronized between Entra and Superblocks * Provision groups and group memberships in Superblocks ## Prerequisites The scenarios outlined in this tutorial assumed that you already have the following items: * An Entra tenant * A user account with permission to configure provisioning (for example, Application Administrator, Cloud Application administrator, Application Owner, or Global Administrator) * A Superblocks organization on the Enterprise plan * A user account in Superblocks with Admin permissions * Your instance's `{tenant}` value. See [Instance URLs](/enterprise/instance-urls) ## Setup 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/) 2. Navigate to **Identity** → **Applications** → **Enterprise applications** 3. Select your Superblocks SSO app or select **+ New application** → **+ Create your own application** 4. In the app management screen, select **Provisioning** in the left panel 5. Set the **Provisioning mode** to **Automatic** 6. Configure credentials as follows: | Field | Value | | - | - | | Tenant URL | `https://{tenant}.superblocks.com/scim/v2`. See [Instance URLs](/enterprise/instance-urls) | | Secret token | [Access token](/admin/org-administration/auth/access-tokens) with Org Admin privileges | 7. Test the connection and click **Save** 8. Optionally, [configure user attributes](#configure-user-attributes) 9. Turn the **Provisioning Status** to **On** 10. Select the **Users and groups** tab and assign the users or groups you want to sync ## Configure user attributes Certain user attributes in Entra can by synced to your Superblocks users' profiles. ### Supported user attributes The Superblocks SCIM API currently supports the following attributes: | SCIM User Attribute | Superblocks User Attribute | Description | | - | - | - | | `emails` | `Global.user.email` | Email identifier used to log in to Superblocks. | | `displayName` | `Global.user.name` | The text shown in Superblocks when referring to the user. | | `name.givenName` | `Global.user.name` | First name of the user. Concatenated with `name.familyName` if `displayName` is not provided. | | `name.familyName` | `Global.user.name` | Last name of the user. Concatenated with `name.givenName` if `displayName` is not provided. | | `groups` | `Global.user.groups` | List of groups to which the user belongs. | | `active` | N/A | Disables the user when set to `FALSE` | | `role` | N/A | The user's [**organization role**](/admin/org-administration/org-roles). Defaults to `null`. If not set, the [default role for the organization](/admin/org-administration/org-roles/using-org-roles#setting-default-role) will be used. | ### Create custom role attribute All of the supported attributes listed above except for `role` are supported by default in Entra ID. You can manage a user's [**organization role**](/admin/org-administration/org-roles) via SCIM by configuring a custom attribute in Entra. To do so: 1. Go to your app's **Provisioning** page 2. Expand the **Mapping** section 3. Click on the **User** mapping 4. Scroll to the bottom of the page and click **Show advanced options** 5. Click **Edit attribute list for customappsso** 6. Add the following new attribute to the list | Field | Value | | - | - | | Name | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:role` | | Type | String | 7. Click **Save** 8. Back on the User mapping page, click **Add New Mapping** 9. Create a mapping with the **Target mapping** set to the role attribute just configured 10. Click **Save** Now when users are provisioned or attributes updated, their [organization role](/admin/org-administration/org-roles) in Superblocks will be set based on the role assigned in Entra. Group roles don't sync from Entra ID The custom attribute above sets an individual user's [organization role](/admin/org-administration/org-roles). Entra ID can provision groups and their members, but it doesn't send a role for a group. A group provisioned through SCIM has no role until you [assign one in Superblocks](/admin/org-administration/groups/managing-group-permissions). Later syncs from Entra leave that role in place. # Manage users and groups with SCIM Source: https://docs.superblocks.com/admin/org-administration/auth/scim/index Automatically manage users and groups from an external user directory using the System for Cross-domain Identity Management (SCIM) standard in Superblocks SCIM provisioning lets Organization Admins manage team members more efficiently, including: * Invite users to your Superblocks team * Deactivate users in your organization * Update user details, including name and email * Create, rename, and delete Groups in Superblocks * Assign and unassign users from Groups With user and group management automated using your identity provider, you can be sure your team always has access to the internal tools they need in Superblocks. ## Set up provisioning Your SCIM provisioning set up will vary depending on the identity provider you use. For instructions select your provider below: * [Okta](/admin/org-administration/auth/scim/okta) * [Microsoft Entra ID](/admin/org-administration/auth/scim/azure-ad) * OneLogin (Coming soon) Setup guides show Superblocks URLs as `https://{tenant}.superblocks.com`. See [Instance URLs](/enterprise/instance-urls) to find the value for Cloud US, Cloud EU, or Cloud-Prem. # Okta SCIM setup Source: https://docs.superblocks.com/admin/org-administration/auth/scim/okta Instructions for setting up SCIM provisioning using Okta as an IdP **Notes** * If you are setting up SCIM after assigning users to a Superblocks SSO app, be sure to run a [**full import**](#import-existing-users) to link the existing assigned user to the Superblocks user * If your Superblocks SSO app uses [**OpenID Connect App**](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm), you'll need to create a separate provisioning-only app to handle SCIM. You'll assign users/groups to both of these applications. Learn more about how to [Add a provisioning only app](#add-a-provisioning-only-app) ## Features The following provisioning features are supported when integrating with Okta: * **Push New Users**: New users created through Okta will also be created in the company's Superblocks organization. * **Push User Deactivation**: Deactivating a user through Okta will deactivate the user from the company's Superblocks organization. * **Reactivate Users**: Reactivating a user through Okta will reactivate the user in Superblocks. * **Push Profile Updates**: Updates made to the user's profile through Okta will be pushed to Superblocks. * **Import New Users**: New users created in Superblocks will be downloaded and turned into new AppUser objects, for matching against existing Okta users. * **Group Push**: Groups and their members can be pushed to Superblocks. ## Setup If your SSO app uses [**OpenID Connect**](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm), you'll need to create a separate SCIM app. Follow instructions to [create a provisioning only app](#add-a-provisioning-only-app), then come back to [configure SCIM](#configure-scim). ### Configure SCIM 1. From the Okta admin console, locate your **Superblocks** SSO App 2. Go to the **General** tab, click **Edit** on the **App Settings** 3. Check the box **Enable SCIM Provisioning** and click **Save** ![Enable SCIM on Okta Application](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/scim/okta_enablescim.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=dafa240f3442431d8f7b08e892235e25) 4. Go to the newly enabled **Provisioning** tab 5. Next to **SCIM Connection** click **Edit**. Configure the connection as follows: | Field | Value | | - | - | | SCIM connector base URL | `https://{tenant}.superblocks.com/scim/v2`. See [Instance URLs](/enterprise/instance-urls) | | Unique identifier field for users | email | | Supported provisioning actions | Select all of the provisioning actions | | Authentication Mode | HTTP Header | | Authorization | [Access token](/admin/org-administration/auth/access-tokens) with Org Admin privileges | 6. Test the connection and click **Save** 7. You should see two new settings **To App** and **To Okta**. Click **To App** 8. Click **Edit** and configure your provisioning options. Note: Sync Password is not supported ![Okta SCIM configuration](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/scim/okta_toappconfig.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=596e22b243bf5ae3693fa1db6cccba07) 9. Click **Save** 10. Optionally, configure attribute mappings to [assign user roles via SCIM](#manage-user-roles-with-scim) ### Add a provisioning only app If your Superblocks SSO app in Okta uses [**OpenID Connect**](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm), you'll need to set up a separate app for SCIM. The easiest way to do this is to set up a separate [**Secure Web Authentication (SWA) App**](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_swa.htm). This app **will not** be used by your users to sign-in to Superblocks, it will just be used for provisioning/group management. To configure an SWA app: 1. From the Okta admin console, click **Applications** → **Applications** 2. Click **Create App Integration** 3. Select **SWA - Secure Web Authentication** 4. Name the app and enter `https://{tenant}.superblocks.com` as the login URL. See [Instance URLs](/enterprise/instance-urls) 5. Click **Finish**. You can now [continue to configure SCIM for Superblocks](#configure-scim) Note that users will not be able to log in through this app so you should make sure you're not showing this app to users on the Okta launch page. ## Import existing users With SCIM configured, you should run an import of existing users from your Superblocks organization to Okta so you can link your Okta users to their Superblocks account. 1. From your Superblocks SCIM app in Okta, click on the **Import** tab. 2. Click **Import Now** which will import all users from your existing Superblocks account. 3. Choose how you want Okta to import each user. Options include: * Link to **EXACT Okta user match**: links the Superblocks user to an existing user in Okta. * Link to **NEW Okta user**: creates a new user in Okta and links the Superblocks user to the new user * **IGNORE this user for now**: leave the user in Superblocks and doesn't link them to an Okta user. Superblocks users that are not linked to a user in Okta will need to be managed from Superblocks. Learn more about [Managing Users](#manage-superblocks-users) ![Okta import users](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/scim/okta/okta6.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=0f1ce37577f71912330d862d8253781d) 4. Click **Confirm Assignments** to finish the import ## Configure user attributes Certain user attributes in Okta can by synced to your Superblocks users' profiles. ### Supported user attributes The Superblocks SCIM API currently supports the following attributes: | SCIM User Attribute | Superblocks User Attribute | Description | | - | - | - | | `emails` | `Global.user.email` | Email identifier used to log in to Superblocks. | | `displayName` | `Global.user.name` | The text shown in Superblocks when referring to the user. | | `name.givenName` | `Global.user.name` | First name of the user. Concatenated with `name.familyName` if `displayName` is not provided. | | `name.familyName` | `Global.user.name` | Last name of the user. Concatenated with `name.givenName` if `displayName` is not provided. | | `groups` | `Global.user.groups` | List of groups to which the user belongs. | | `active` | N/A | Disables the user when set to `FALSE` | | `role` | N/A | The user's [**organization role**](/admin/org-administration/org-roles). Defaults to `null`. If not set, the [default role for the organization](/admin/org-administration/org-roles/using-org-roles#setting-default-role) will be used. | ### Create custom role attribute All of the supported attributes listed above except `role` are supported by default in the Okta user profile. You can manage a user's [**organization role**](/admin/org-administration/org-roles) via SCIM by configuring a custom attribute in Okta. Roles can be assigned to users, or you can scale role management by assigning roles based on the Okta group a user is in. To learn more about how Okta manages syncing attributes via SCIM, read Okta's [Attribute Mapping](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-about-attribute-mappings.htm#Okta) documentation. To create a custom attribute for your Superblocks user roles: 1. Go to your Superblocks SCIM app in Okta 2. Click on the **Provisioning** tab 3. In the **To App** settings, scroll down to the section labeled **Superblocks Attribute Mappings** 4. Click **Go to Profile Editor** 5. Click **Add Attribute** 6. Fill in the attribute configuration as follows: | Field | Value | | - | - | | Data type | string | | Display name | Superblocks Role (customizable) | | Variable name | `superblocks_role` (customizable) | | External name | `role` | | External namespace | `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` | | Enum | Checked | 7. In the **Attribute members** list include the following: | Display name | Value | | - | - | | Owner | `owner` | | Admin | `admin` | | Developer | `developer` | | End-user | `end_user` | The `value` field should correspond to the `key` of [organization role](/admin/org-administration/org-roles) you want to assign. You can find the key of any of your custom roles, by going to the [Roles & Permissions](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-about-profiles.htm#App) page in Superblocks, selecting the role, and clicking **Edit details**. 8. For **Attribute type** select either **Personal** or **Group**. To learn more about these types, see [Personal vs Group attribute types](#personal-vs-group-attribute-types) 9. Click **Save** Now that you've created the custom attribute, it will show up when you assign users or groups to the Superblocks SCIM app. [Import users from Superblocks](#import-existing-users) to sync to Okta the currently assigned role in Superblocks.\ \\ You can also [map Okta attributes to app attributes](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-map-attributes.htm) by configuring mapping rules. #### Personal vs Group attribute types When assigning roles in Okta via SCIM, you'll need to choose whether to manage roles for each user individually or in groups. Here's the difference: * **Personal**: You'll decide what role to give each user when assigning them to the Superblocks SCIM app. Alternatively, you can create [custom mapping rules](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-map-attributes.htm) to set the role based on other user attributes in Okta. * **Group**: You'll decide what role to associate with each Okta group assigned to the Superblocks SCIM app. You'll then [prioritize your groups](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-prioritize-app-group.htm). When a user is added to one or more of the assigned Okta groups, the role they receive in Superblocks will be based on the group priorities. ## Manage groups with SCIM Optionally, you can set up Okta to manage Superblocks Groups and their members. If this is not configured, new users added through Okta will not be assigned to any custom groups in Superblocks. To sync an Okta group with a Superblocks group: 1. From the Superblocks app in Okta, go to the **Push Groups** tab 2. Click **Push Groups** → **Find groups by name** 3. Enter the name of the **Okta** group you want to sync with Superblocks 4. Okta will try to automatically match the Okta group to a group in Superblocks based on the name. If there is no corresponding group in Superblocks select **Create Group**, otherwise select **Link Group** and choose the Superblocks group you want to sync with. ![Okta push groups](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/scim/okta/okta7.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=c986d3c91db5d5fa3b62949076f78655) 5. Click **Save**. This will either create a new group in Superblocks or link the group to an existing Okta group. If you choose to **Push group memberships immediately**, users who are members of the group in Okta will be added to the Superblocks group and receive access to any Applications, Workflows, or Scheduled Jobs associated with that Superblocks group. Once group push is configured, when you create a new Superblocks user from Okta, or change which groups they're in within Okta, they'll be automatically added or removed from Superblocks groups that you've synced. Note: Once group push is configured, all user membership changes should be made from Okta. Changing group membership in Superblocks can cause synchronization issues with Okta. # Entra ID SSO setup Source: https://docs.superblocks.com/admin/org-administration/auth/single-sign-on/azure-ad Superblocks single sign-on (SSO) with Entra (formerly Azure AD) lets your team seamlessly authentication and access Superblocks using their Entra credentials. This guide walks trhough how to configure single sign-on for Superblocks. ## Prerequisites To setup SSO for your organization, you'll need: * An Entra tenant * A user account with, at a minimum, [Cloud application administrator](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#cloud-application-administrator) access * A Superblocks organization on the **[Enterprise](https://www.superblocks.com/pricing)** plan * Your instance's `{tenant}` value. See [Instance URLs](/enterprise/instance-urls) ## Setup Set up single sign-on for Entra by registering an application in the Entra portal. See Microsoft's [Quickstart: Register an application with the Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) for full details. ### Register an application 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/) 2. Navigate to **Identity** → **Applications** → **Enterprise applications** 3. Click **+ New application** 4. Select **+ Create your own application** 5. Name the application ![Create Entra Application](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/scim/azure_ad.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=99f118a649b422c734202fc3a7fbb92a) 6. Set **Supported account types** to **Accounts in this organizational directory only** 7. Under **Redirect URI** select **Web** and enter `https://login.superblocks.com/login/callback` 8. Click **Register** ### Setup authentication After your app has been registered, configure authentication for the application. 1. In **App registrations** select your new application 2. Under **Manage**, select **Authentication** 3. Set the **Front-channel logout URL** to `https://{tenant}.superblocks.com/logout` 4. Under **Implicit grant and hybrid flows** check the boxes for both **Access tokens** and **ID tokens** 5. **Save** your configuration ![Entra Enterprise Application Setup](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/sso/azure-ad-setup.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=8f6d548fb4135f8c1488723a234f9a01) ### Add a client secret Superblocks uses a client secret to authenticate with Entra when requesting user access tokens. To create a client secret for your application: 1. Under **Manage**, select **Certificates & secrets** 2. On the **Client secrets** tab, click **+ New client secret** 3. Enter a description and select an expiration date for your secret 4. Click **Add** 5. Copy the secret **value** The secret value will never be shown again after you leave this page. Be sure to copy and save it to a safe place like your password manager. ### Configure IdP-initiated login (optional) To allow users to log in to Superblocks directly from Entra instead of initiating the login from Superblocks, follow the steps below to update the login URL for the Entra application. 1. Under **Manage**, select **Manifest** 2. Scroll down to the `signInURL` property and set its value to `https://{tenant}.superblocks.com?connection={MyCompanyName}-AzureAD` Replace `{MyCompanyName}` with your company's name. Remove all spaces and special characters from the name. If your company name is multiple words, capitalize the first letter of each word. For example, the company River Bank Technologies would become `RiverBankTechnologies` 3. Click **Save** ![Update signInURL for IdP-initiated login](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/sso/azure_signinurl.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=0b0d9e5317f74c10d9c3c58a5be2b194) ## Send IdP info to Superblocks Once you've configured your Entra application, send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.
Client ID The **Application (client) ID** for your Entra tenant. You can find this value on your app's **Overview** screen.
Client Secret The secret **value** you copied when you [added a client secret](#add-a-client-secret). Note: we recommend using a secure transfer mechanism such as `https://onetimesecret.com` or similar to send the secret.
Entra Tenant Domain Your Entra domain name. You can find this on your Entra tenant overview page in the Microsoft portal.
Other domains The list of domain and domain aliases your employees should be able to use when logging into Superblocks.
# Google SSO setup Source: https://docs.superblocks.com/admin/org-administration/auth/single-sign-on/google Superblocks single sign-on (SSO) with Google Workspace lets your team seamlessly authenticate and access Superblocks using their Google credentials. This guide walks through how to configure single sign-on for Superblocks. ## Prerequisites To setup SSO for your organization, you'll need: * A Google Workspace account * Google Workspace administration access * A Superblocks organization on the **[Enterprise](https://www.superblocks.com/pricing)** plan ## Setup Google Workspace Set up single sign-on for Google by creating either a **SAML** or **OIDC** application. For full details, see Google's guides for how to: * [Create a custom SAML app](https://support.google.com/a/answer/6087519) * [Set up OAuth 2.0 (OIDC)](https://support.google.com/googleapi/answer/6158849) For the fastest setup and seamless integration with the Superblocks Sign-in with Google experience, [create an OAuth2.0 app](#create-an-oauth-app). If you plan on using SCIM for user provisioning and group management, [create a SAML app](#create-a-saml-app). Learn more about [Managing users and groups with SCIM](/admin/org-administration/auth/scim/). ### Create an OAuth app 1. Log in to Google Cloud and go to the [**API Console**](https://console.developers.google.com/) 2. Select a Google Cloud project or create a new one 3. Navigate to the **APIs & services** page from the left side menu 4. On the left, click **Credentials** 5. Click **Create Credentials**, then select **OAuth client ID** 6. Select **Web application** as the **Application type** 7. Configure the following settings for your application
Name **Superblocks**, or a custom name
Authorized JavaScript origins `https://login.superblocks.com`
Authorized redirect URIs `https://login.superblocks.com/login/callback`
8. Click **Create**. A modal will open with your OAuth client information. Keep this modal open and go to the section below to determine [what info to send to Superblocks](#oauth-application). ### Create a SAML app 1. Log in to Google Workspace and go to the **Admin Console** 2. Navigate to **Apps** → **Web and mobile apps** 3. Click **Add App** → **Add custom SAML app** 4. Provide the general information for the integration and click **Continue** 5. On the **Google Identity Provider details** download the **IDP metadata** file, or copy and save the [info to send to Superblocks](#saml-application) 6. Click **Continue** 7. Enter the following information into the **Service Provider Details**
ACS URL `https://login.superblocks.com/login/callback?connection={CompanyName}-SAML`
Entity ID `urn:auth0:superblocks-prod:{CompanyName}-SAML`
Name ID format EMAIL
Name ID Basic Information > Primary email
Replace `{CompanyName}` with your company's name. Remove all spaces and special characters from the name. If your company name is multiple words, capitalize the first letter of each word. For example, the company River Bank Technologies would become `RiverBankTechnologies`. 8. Click **Continue** 9. Click **Add mapping** and configure the following user attributes | Google Directory attributes | App attributes | | - | - | | Primary email | email | | First name | givenname | | Last name | surname | 10. Click **Finish** and continue to [send your SAML app info to Superblocks](#saml-application). ## Send IDP info to Superblocks ### OAuth application Send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.
Client ID The public identifier for your client located on the **General** tab of your application.
Client Secret The **secret** value shows in the **CLIENT SECRETS** section. Note: we recommend using a secure transfer mechanism such as `https://onetimesecret.com` or similar to send the secret.
Google Workspace domain Google Workspace domain name for your organization.
Domains A list of domain and domain aliases your employees should be able to use when logging in to Superblocks.
### SAML application Send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.
Connection Name The connection name you created above and configured in the ACS URL and Entity ID.
SSO URL The **Identity Provider Single Sign-On URL** provided when you created the SAML app.
X509 Signing Certificate The certificate downloaded from the Identity Provider details
Domains A list of domain and domain aliases your employees should be able to use when logging into Superblocks.
# Single Sign-On (SSO) overview Source: https://docs.superblocks.com/admin/org-administration/auth/single-sign-on/index Set up Single Sign-On to let your team log in to Superblocks using your organization's identity provider ![Single sign-on overview](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/sso.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=84d888c76a31dc00535e944396b41b3b) SSO lets your team authenticate with Superblocks using the same identity provider (IdP) you use for your other internal and external services. Superblocks supports both SAML 2.0 and OIDC, as well as a large variety of identity providers, including Okta, Entra, Google, OneLogin and more. Use SSO to streamline member login and make it simple for your IT team to manage Superblocks access and keep your data and applications secure. ## Supported identity providers We provide support for the following identity providers: * [Okta](/admin/org-administration/auth/single-sign-on/okta) * [Google Workspace](/admin/org-administration/auth/single-sign-on/google) * [Azure Entra ID](/admin/org-administration/auth/single-sign-on/azure-ad) * OneLogin * PingFederate * ADFS * OpenID Connect * Custom SAML ## Instance URLs Setup guides show Superblocks URLs as `https://{tenant}.superblocks.com`. See [Instance URLs](/enterprise/instance-urls) to find the value for Cloud US, Cloud EU, or Cloud-Prem. # Okta SSO setup Source: https://docs.superblocks.com/admin/org-administration/auth/single-sign-on/okta Superblocks single sign-on (SSO) with Okta lets your team seamlessly authenticate and access Superblocks using their Okta credentials. Optionally, you can also let users sign in from the Superblocks tile on their Okta dashboard (IdP-initiated login). This guide walks you through how to configure single sign-on for Superblocks. ## Prerequisites To setup SSO for your organization, you'll need: * An Okta account * A user account with **[App Admin](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm)** access * A Superblocks organization on the **[Enterprise](https://www.superblocks.com/pricing)** plan * Your instance's `{tenant}` value. See [Instance URLs](/enterprise/instance-urls) ## Set up Okta Set up single sign-on for Okta by creating either a custom **SAML** or **OIDC** application. For full details, see Okta's guides for how to: * [Create SAML app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) * [Create OIDC app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) For the fastest setup, [create an OIDC integration](#create-an-oidc-integration). If you plan on using SCIM for user provisioning and group management, we recommend [creating a SAML integration](#create-a-saml-integration). Learn more about [ Managing users and groups with SCIM ](/admin/org-administration/auth/scim/). ### Create an OIDC integration 1. Log in to Okta and go to the **Admin Console** 2. Navigate to **Applications** → **Applications** 3. Click **Create App Integration** 4. Select **OIDC - OpenID Connect** as the **Sign-on method** 5. Select **Web Application** as the **Application type** and click **Next** 6. Configure the following settings for your application
Name **Superblocks**, or a custom name you want users to see on their application dashboard.
Grant type **Authorization Code** (selected by default), **Refresh Token**, and **Implicit (hybrid)**
Sign-in redirect URIs `https://login.superblocks.com/login/callback`
Sign-out redirect URIs `https://{tenant}.superblocks.com/logout`
Assignments Your desired settings for who can access Superblocks.
7. Click **Save**. You'll be brought to the **General** tab of your new application. 8. [Allow the `offline_access` scope](#allow-the-offline_access-scope) 9. **(Optional)** To enable IdP-initiated login, so users can open Superblocks from the tile on their Okta dashboard, go to the **General Settings** section, click **Edit**, and configure the following **Login** settings. Skip this step if users will only sign in from Superblocks.
Login initiated by Either Okta or App
Application visibility Display application icon to users
Login flow Redirect to app to initiate login (OIDC Compliant)
Initiate login URI `https://{tenant}.superblocks.com?connection=-OpenID`
Replace `` with your company's name. Remove all spaces and special characters from the name. If your company name is multiple words, capitalize the first letter of each word. For example, the company River Bank Technologies would become `RiverBankTechnologies` 10. If you changed the **Login** settings, click **Save**. Then continue to find out [what info to send to Superblocks](#oidc-application). #### Allow the `offline_access` scope Superblocks requests the `offline_access` scope so that Okta issues a refresh token at login. Superblocks uses it to get a new Okta token when the one from login expires, so users don't have to log out and back in. The **Refresh Token** grant type and the `offline_access` scope are required if you use the [On-Behalf-Of Token Exchange](/integrations/auth/oauth-20#on-behalf-of-token-exchange) or **IdP Token Passthrough** auth methods in any integration. How you allow `offline_access` depends on which Okta authorization server issues tokens for Superblocks. * **Org authorization server** (the default for this setup, with endpoints under `https://{yourOktaDomain}/oauth2/v1/`): `offline_access` is allowed once the **Refresh Token** grant type is enabled. No other changes are needed. * **Custom authorization server** (for example, `https://{yourOktaDomain}/oauth2/default`): 1. Go to **Security** → **API** → **Authorization Servers** and open the authorization server 2. On the **Scopes** tab, confirm the `offline_access` scope exists. It's a reserved scope that Okta creates by default, so restore it if it has been deleted. 3. On the **Access Policies** tab, open the policy assigned to your Superblocks application and edit its rule 4. Under **Scopes requested**, select **Any scopes**, or select **The following scopes** and include `offline_access` along with `openid`, `profile`, and `email` 5. Click **Update rule** ### Create a SAML integration 1. Log in to Okta and go to the **Admin Console** 2. Navigate to **Applications** → **Applications** 3. Click **Create App Integration** 4. Select **SAML 2.0** as the **Sign-on method** 5. Provide the general information for the integration. **(Optional)** To enable IdP-initiated login, so users can open Superblocks from the tile on their Okta dashboard, leave **Do not display application icon to users** unchecked. Click **Next** 6. Enter the following information into **SAML Settings** → **General**
Single sign-on URL [https://login.superblocks.com/login/callback?connection=](https://login.superblocks.com/login/callback?connection=)`-SAML`
Audience URI `urn:auth0:superblocks-prod:-SAML`
Name ID format EmailAddress
Application username Email
Replace `` with your company's name. Remove all spaces and special characters from the name. If your company name is multiple words, capitalize the first letter of each word. For example, the company River Bank Technologies would become `RiverBankTechnologies` 7. Configure the follow attributes in **SAML Settings** → **Attribute Statements** | Name | Name format | Value | | - | - | - | | email | Unspecified | user.email | | givenname | Unspecified | user.firstName | | surname | Unspecified | user.lastName | 8. Click **Next** and fill out the Okta feedback form, then click **Finish**. 9. You'll be brought to the **Sign on** tab of your new application. Click **View Setup Instructions** and continue to the next section to learn [what info to send to Superblocks](#saml-application). ## Send IDP info to Superblocks ### OIDC application Send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.
Client ID The public identifier for your client located on the **General** tab of your application.
Client Secret The **secret** value shows in the **CLIENT SECRETS** section.\ \ Note: we recommend using a secure transfer mechanism such as [https://onetimesecret.com](https://onetimesecret.com) or similar to send the secret.
Okta domain Your company's Okta domain. You can find this by clicking your username in the upper-right corner of the Admin Console. Learn more about how to [Find your Okta domain](https://developer.okta.com/docs/guides/find-your-domain/main/).
Domains A list of domain and domain aliases your employees should be able to use when logging into Superblocks.
### SAML application Send the following information to [support@superblocks.com](mailto:support@superblocks.com). On Cloud-Prem, send it to your Superblocks deployment team instead.
Sign In URL The **Identity Provider Single Sign-On URL** in the Okta setup instructions.
X509 Signing Certificate The certificate downloaded from the setup instructions.
IdP-initiated login (optional) Only if you want users to open Superblocks from the tile on their Okta dashboard: let us know, and Superblocks enables IdP-initiated login for your connection so the tile signs users in to your Superblocks instance.
Metadata URL (optional) Optionally, send us the **Metadata URL** shown on the **Sign on** tab of your application.
Domains A list of domain and domain aliases your employees should be able to use when logging into Superblocks.
# About user groups Source: https://docs.superblocks.com/admin/org-administration/groups Organize users into groups to streamline the management of permissions and access across your organization With user groups, you can easily: * Grant users different levels of access to Superblocks by assigning organization roles to groups. * Manage resource access at scale by assigning resource-level permissions to groups. * Customize your app's user experience and security by creating in-app authorization checks on pages, APIs, and components. # Managing group permissions Source: https://docs.superblocks.com/admin/org-administration/groups/managing-group-permissions **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `groups:manage` permission To grant a group of users permissions in Superblocks, you can either assign them an [organization role](/admin/org-administration/org-roles) that defines the Superblocks feature/admin permissions they receive, or a [resource role](/admin/org-administration/resource-roles) that grant them access to an Application, Integration, Workflow, or Scheduled Job. To learn more about the types of roles and access they grant, see [Permissions in Superblocks](/admin/org-administration/rbac) ## Assigning org role to a group To assign an organization role to a group: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Groups**](https://app.superblocks.com/groups) 3. Find the name of the group 4. Click into the **Role** selector and choose the role you want to assign to the group ![Assign custom role to user group](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/assign-role-to-group.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=1a63457dfcfdea01898b16499355c5e1) ## Removing org role from a group To remove an organization role from a group: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Groups**](https://app.superblocks.com/groups) 3. Find the name of the group 4. Click the × icon next to the role name ## Managing a group's access to a resource Groups can be granted access to individual resources as well by assigning the group a [resource role](/admin/org-administration/resource-roles). To share a resource with a group: 1. Navigate to the resource (Application, Workflow, Integration, etc) you want to grant access to 2. Click into the editor or configuration page for that resource 3. Find and click on the **Share** button in the upper right-hand corner of the page 4. In the dialog box that appears, search for the group you want to share the resource with 5. Select the **Resource role** you want to assign to the group 6. Click **Share** ![UI showing user assigning QA permissions to Product Teams for an Application](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/assign-resource-role.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=d5e689e55e756a74124dd88094819e59) ## How group roles interact with individual member roles Roles and permissions are additive. If a person is given different levels of access through different avenues, such as a group membership and their individually assigned role, the user has the **sum of all access grants**. For example, let's say an organization owner assigns a user the [built-in role](/admin/org-administration/org-roles#built-in-organization-roles) of End-User. They're then added to a group that has a [custom role](/admin/org-administration/org-roles/custom-roles) with all Integrations permission. This member will have management access to all Integrations, but won't be able to create Apps, Workflows, or Jobs, because of the permissions granted through the combination of their individually assigned role and the custom role. If a member belongs to multiple groups, the members permissions will include the permissions associated with the role individually assigned to them, plus the permissions granted to each of their groups. # Managing user groups Source: https://docs.superblocks.com/admin/org-administration/groups/managing-groups **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `groups:manage` or `groups.members:manage` permission ## Overview User groups enable large organizations to efficiently manage members and their access in Superblocks. By organizing users into groups, new tools can be quickly shared with different parts of the organization. [Custom roles](/admin/org-administration/org-roles/custom-roles) can also be assigned to grant group members access beyond the permissions granted to users through their individually assigned role. Learn more about [Managing group permissions](/admin/org-administration/groups/managing-group-permissions) Superblocks also supports syncing groups and group memberships with SCIM. Learn more about managing groups with [SCIM](/admin/org-administration/auth/scim). ## Creating a group To create a new user group: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Groups**](https://app.superblocks.com/groups) 3. Click **+ Add group** 4. Create a name for your group 5. Select the members you want to add to the group 6. Click **Create** ![Create a new user group](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/create-group.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=56bb81626756630e9ccc4c55320b0e72) Once you've created a group you can assign a [custom organization roles](/admin/org-administration/org-roles/custom-roles) to the group to grant members additional permissions. Learn more about in [Managing group permissions](/admin/org-administration/groups/managing-group-permissions) ## Add members to a group To add members to a group: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Groups**](https://app.superblocks.com/groups) 3. Click on the name of a group to navigate to that group's page 4. On the **Members** tab click **+ Add member** 5. Select the members to add to the team 6. Click **Add members** ## Remove members from a group To remove a member from a group: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Groups**](https://app.superblocks.com/groups) 3. Click on the name of a group to navigate to that group's page 4. Find the member in the list of team members 5. Select the dropdown menu (⋯) at the right of the row of the member you want to remove 6. Select **Remove from group** 7. Click **Remove** in the confirmation dialog ## Deleting a group You can delete groups from the Groups page. To delete a group: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Groups**](https://app.superblocks.com/groups) 3. Select the dropdown menu (⋯) at the right of the row of the group you want to delete 4. Click **Remove group** 5. Click **Remove** in the confirmation dialog # Organization knowledge Source: https://docs.superblocks.com/admin/org-administration/knowledge Define org-wide standards and conventions that Clark follows by default Organization knowledge applies to every Clark conversation across your entire org. Use it to encode information that all builders should benefit from, so Clark builds consistently with your team's standards — things like design systems, coding conventions, domain terminology, and team-wide patterns. ## Adding org knowledge Navigate to the **Knowledge** page and chat with Clark to describe what you want it to remember. Clark will create the right knowledge entry at the right scope for you, then present it for your review before saving. We recommend using Clark to write entries because it optimizes them for LLM retrieval — producing focused, well-structured instructions that Clark can look up effectively at build time. ![Clark Knowledge page](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/knowledge-page.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=2e98dea282f92b7d27724630de7910be) For example, you might tell Clark: * "Our design system uses primary (#0099FF), secondary (#6B7280), and danger (#EF4444). Never hardcode other colors for interactive elements." * "All API error responses must be caught and displayed with a toast notification. Never silently swallow errors." * "When referring to customers, use 'account' not 'client' or 'customer'. Our data model uses `account_id` as the primary identifier." Clark will draft the entry, set the scope to **Organization**, and present it for your review before saving. ![Clark creating an org knowledge entry](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/org-knowledge.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=2eebdeda34ef0ae15c470f589c527123) You can also ask Clark to **explore your existing knowledge**, refine entries, or identify duplicates — for example, "Review my org knowledge and flag any entries that overlap or contradict each other." ## Permissions Creating, updating, and deleting org knowledge requires Owner or Admin permissions. Once entries are saved, they are available to all builders in the org — you cannot restrict who benefits from org knowledge, because it's designed to apply everywhere. ![Organization knowledge permissions](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/org-knowledge-permissions.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=8d3e8cd183f560f438367d0833b47574) Individual entries can be enabled or disabled from the Knowledge page. Enabling too many knowledge entries at once can reduce Clark's effectiveness. Keep entries focused and disable any that aren't actively needed. ## Related Organization knowledge is part of Clark's broader [Knowledge](/building-with-clark/knowledge) system. You can also define knowledge at the [integration](/integrations/knowledge), [user](/building-with-clark/knowledge/user-knowledge), and [app](/building-with-clark/knowledge/app-knowledge) levels. # About organization members Source: https://docs.superblocks.com/admin/org-administration/members Everything you build in Superblocks is built in and belongs to a Superblocks organization. Organizations are the central place where you'll collaborate with your team when building tools, and where your teammates will access and use the tools you've built. To collaborate with others and share non-public tools, you'll need to add others to your organization as members. Organization members are people who work at your organization or anyone who needs access your organization's internal tools, such as contractors, part-time employees, etc. You can view the members of your organization on the [Users](https://app.superblocks.com/users) page on Superblocks. Learn more about inviting and managing your organization members in this section. # Permanently delete a user from Superblocks Source: https://docs.superblocks.com/admin/org-administration/members/delete-user The **Owner** of a Superblocks organization can request that users be permanently deleted from Superblocks. ## Background * The **Owner** of a Superblocks organization controls all data for their organization. This includes anything built by members of their org and member profiles. * When members leave a Superblocks org, they may have the right to request their profile be deleted. As the data controller, the **Owner** is responsible for determining whether information requires deletion. * Users can only be deleted once a member's account is [deactivated](/admin/org-administration/members/remove-user). Once the user's account is deleted, it can't be recovered. ## What information is deleted? Deleting a user from Superblocks will remove the following user information: * Display name * Email address * Profile picture * Custom user attributes Content that isn't considered profile information won't be removed from Superblocks. This includes: * Resources the user has created (Applications, Integrations, etc) * Commits created by the user * Deployments triggered by the user * Audit log records associated with the user's activity Commits, deployments, and audit log records will show as having been done by "Deleted user" ## Submit a request to delete a user If you are the **Owner** of your Superblocks org, you can request that users be deleted by sending the following information to [support@superblocks.com](mailto:support@superblocks.com): * Your organization name * The **email address** of all of the users you want to delete Please make sure all users are [deactivated](/admin/org-administration/members/remove-user) before filing the request. # Manage organization members Source: https://docs.superblocks.com/admin/org-administration/members/invite-users Invite users to become members of your Superblocks organization **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `org.users:manage` permission Superblocks also supports user management with OAuth and SAML based Single Sign on, and SCIM. Learn more about [enabling single sign-on](/admin/org-administration/auth/single-sign-on) and [SCIM](/admin/org-administration/auth/scim) ## About invitations To add someone to your Superblocks organization, you'll need to [invite them to join](#invite-users-to-join) the org. When you invite someone to your Superblocks organization, they'll receive an email with an invitation link. To join the organization, the invitee just needs to click the invitation link in the email. People will only become full members of your organization once they've accepted their invitation. You can implement SCIM to add, manage, and remove organization members' access to Superblocks through an identity provider (IdP). Users added to organization via SCIM do not receive invitation emails. Learn more about [SCIM](/admin/org-administration/auth/scim). ## Member emails When inviting users to your organization, you'll need to provide an email address. Superblocks users can only be a member of a single organization at a time. If someone has already been invited or joined a different Superblocks org, you won't be able to invite them using the same email address. To keep things simple and secure, we recommend inviting users with email addresses that are tied to your organization's domain. It's best to avoid personal email addresses or emails from outside your organization. If you try to invite a user with an email that's already in another Superblocks org, you'll get an error. If this user need access to multiple organizations, it's recommended to use different email addresses, or email aliases. ## Invite users to join 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Users**](https://app.superblocks.com/users) 3. Click **+ Invite user** 4. Enter one or more email addresses. If you are inviting multiple members, separate emails with a comma. 5. Choose an initial [built-in or custom role](/admin/org-administration/org-roles) from the **Organization role** dropdown 6. (Optional) Select groups to add these members to 7. Click **Invite users** ![Invite users to Superblocks](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/invite.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=4ec7690294ea3338a46b9dcac9fb35e6) 1. The invited people will receive emails inviting them to the organization. They will need to accept the invitation before becoming a member of the organization. You can edit or cancel an invitation any time before the user accepts. ## Cancel an invitation Invitations never expire. If you no longer want a user to join your organization, you can cancel their invitation. To cancel an invitation: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Users**](https://app.superblocks.com/users) 3. Find the invited user by entering their name or email into the search box, or filter the list to invited users ![Filter user list to invited users](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/filter-invited-users.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=dc5d23b207c3d4958ff7d2c1ebdb6e39) 1. Next to the user, select the dropdown menu (⋯), then click **Remove invite** ![Cancel user invite](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/cancel-invite.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=27339ad7fb416de439ff2251f77a76b6) 1. To confirm, click **Remove** # Removing a member from your organization Source: https://docs.superblocks.com/admin/org-administration/members/remove-user Remove members from your organization by deactivating their account **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `org.users:manage` permission Superblocks also supports user management with OAuth, SAML, and SCIM. Learn more about [enabling single sign-on](/admin/org-administration/auth/single-sign-on) and [SCIM](/admin/org-administration/auth/scim). ## Deactivate a user's account 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Users**](https://app.superblocks.com/users) 3. Find the user by entering their name or email into the search box 4. Next to the user, select the dropdown menu (⋯), then click **Deactivate** 5. To confirm, click **Deactivate** Removing a member from your organization has the following consequences: * They are removed from any user groups they were added to * The roles assigned to them for any resource are removed * Their personal access token is deactivated * They're signed out and will not be able to log back in They aren't notified that their account was deactivated, nor are any resources they've created deleted. If you change your mind, you can reach out to our [support team](/enterprise/support/help) to reactivate the account. Deactivating a member's account does not delete profile information, like the user's name and email. The user will still appear in the Users list in case you want to reactivate them at a future point. **Owners** can request to [permanently delete user accounts](/admin/org-administration/members/delete-user). # About organization roles Source: https://docs.superblocks.com/admin/org-administration/org-roles Use organization roles to determine the actions a user can perform within the Superblocks platform Roles are used to define a set of permissions that you can assign to individuals or groups. Organization-level roles control the Superblocks features members can access, the administrative actions they can perform, and the level of access users have to all current and future resources created in the org. Note, organization-level roles differ from resource-level roles that give users access to specific Applications, Integrations, Workflows, etc. For more information, see [About resource roles](/admin/org-administration/resource-roles).## Built-in organization rolesEach Superblocks organization, by default comes out of the box with the following built-in roles. These roles are non-editable and are based on common patterns of permissions organizations usually need.- **Owner**: Each Superblocks organization has a primary Owner. This person is considered the controller of all org data. Only they can request to [delete users](/admin/org-administration/members/delete-user), delete the organization, or request plan and billing changes. - **Admin**: Admins help manage their organization, including members, groups, and settings. Admins can also access all of the organization's resources to help manage access to these resources. - **Developer**: The default non-administrative role is Developer. Developers build and maintain your company's tooling. They can't change org settings, but otherwise have read-only access to most of your org's settings. - **End-User**: End-Users have the lowest level of access in Superblocks. They have read-only access to the platform, can't view most org settings, and can only access resources they've been given access to.For more granular control of permissions, you can create custom organization roles. For more information, see [Custom organization roles](/admin/org-administration/org-roles/custom-roles)For more information using roles, see [Using organization roles](/admin/org-administration/org-roles/using-org-roles)## Permissions for built-in organization rolesThe built-in organization roles have the following permissions. For a full list of permissions that can be assigned with organization roles, see the [permissions reference](/admin/org-administration/org-roles/permissions) \ \ \
ResourcePermission
# About custom organization roles Source: https://docs.superblocks.com/admin/org-administration/org-roles/custom-roles **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `roles:manage` permission You can granularly control user permissions with custom organization roles. Organization roles control the Superblocks features members can access, the administrative actions they can perform, and the level of access users have to all current and future resources created in the org. For example, you can use custom roles to grant a set of users permission to manage self-hosting the Superblocks data plane, without granting permission to invite and manage org members. Or let users create Apps, Workflows, and Jobs without granting permission to add Integrations. Each custom roles includes a set of permissions. Permissions either let users: * Do certain types of development. See [development permissions](/admin/org-administration/org-roles/permissions#development) * Gain access to **all current and future resources** in the org. See [resource access permissions](/admin/org-administration/org-roles/permissions#resource-level-access) * Manage certain org settings and features. See [governance permissions](/admin/org-administration/org-roles/permissions#governance) This guide walks through how to create and manage custom organization roles. To learn more about assigning roles see [Using organization roles](/admin/org-administration/org-roles/using-org-roles) ## Creating a custom role Organizations can create up to 10 custom organization roles. To create an organization role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/organization-roles) 3. On the **Organization roles** tab, click **+ Add role** 4. Type a name and description for the custom role 5. Click **Create** 6. Add permissions to your custom role by selecting permissions in the permission table. For a full reference to assignable permissions see the [Permissions reference](/admin/org-administration/org-roles/permissions) 7. Once you've selected all the permissions you want assigned to the role, click **Save** ## Editing a custom role's details To edit the name or description of a custom role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/organization-roles) 3. Next to the role you want to edit, select the dropdown menu (⋯), then click **Edit details** 4. Change the role as required, then click **Save** ## Editing a role's permissions To edit the permissions associated with a custom role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/organization-roles) 3. Check/uncheck the boxes associated with permissions you want to add/remove from the role. Alternatively, if you want to grant all permissions associated with a type of Superblocks resource, check the box at the top of the resource group. 4. Once you've made all your permission selections, click the **Save** button at the bottom of the page ![Manage permissions of custom organization role](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/custom-role-permissions.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=7a91bc4f321549815ea03361016ff20e) For a full reference of permissions and the access they grant, see [Permissions reference](/admin/org-administration/org-roles/permissions) ## Deleting a custom role 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/organization-roles) 3. Next to the role you want to delete, select the dropdown menu (⋯), then click **Delete** 4. In the confirmation dialog, choose a new role to assign to users who are currently assigned the role being deleted 5. Click **Reassign & delete** # Organization role permission reference Source: https://docs.superblocks.com/admin/org-administration/org-roles/permissions Full reference to permissions assignable to users with organization roles Organization-level roles control the Superblocks features members can access, the administrative actions they can perform, and the level of access users have to all current and future resources created in the org.## Governance \ \ \
PermissionDescriptionMore info
## Development \ \ \
PermissionDescriptionMore info
## Resource-level accessCustom organization roles can also be used to grant the following access to **all current and future resources** in the organization. # Using organization roles Source: https://docs.superblocks.com/admin/org-administration/org-roles/using-org-roles **Who can use this feature?** Organization **Owners**, **Admins**, and users with `org.users:manage` or `groups:manage` permission Each member of a Superblocks organization has an organization role. These roles control the Superblocks features that members can access, the administrative actions they can perform, and the level of access they have to all current and future resources created in the org. Users can be assigned a [built-in role](/admin/org-administration/org-roles#builtin-organization-roles), or you can create up to 10 custom roles. For more information, see [About custom organization roles](/admin/org-administration/org-roles/custom-roles) This guide walks through how to manage the organization roles assigned to individuals and groups in Superblocks. Superblocks also supports managing roles with SCIM. Learn more about [SCIM](/admin/org-administration/auth/scim) ## Viewing role permissions To view the permissions associated with an organization role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/organization-roles) 3. Expand/collapse resources in the table to view the permissions associated with each role ![Organization role permissions](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/org-roles.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=6c51c5ba8246778fa0ae150a0073eff0) Permissions listed grant access to manage the organization and permissions to **all current and future resources** in the organization. Learn more about [organization role permissions](/admin/org-administration/org-roles/permissions) ## Setting default role Each member of your organization must have an organization role. When users are [invited](/admin/org-administration/members/invite-users) to your org, you must select the role that will be assigned. If your organization lets users join your team based on their email domain, they will be assigned the **default role** set for your organization. To update your org's default role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/settings) and go to the **Settings** tab 3. Update the **New user default role** ![Set role to assign to new users](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/default-org-role.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=265e32ed564341477ab3cea2f1b18a73) Now, when users join your team, they will automatically be assigned this role. ## Assign organization roles ### Assign to individual user To change the role of an individual member: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Users**](https://app.superblocks.com/users) 3. Find the user by entering their name or email into the search bar 4. Click into the **Role** selector and choose the new role you want to assign ### Assign to multiple users To update the role assigned to multiple organization members: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Users**](https://app.superblocks.com/users) 3. Select the checkbox to the left of the members' name to select that member 4. Select all members that you want to update. Alternatively, if you wish to select all the members, click the checkbox next to the Name column in the table. 5. Next to the Invite user button, another button will appear for bulk **Actions** 6. Click the **Actions** button and then select **Change user roles** 7. Select a new role for all of the selected users and click **Save** ### Assign roles to groups Assigning roles to groups is optional but can be beneficial for efficiently managing permissions across users who share similar responsibilities. For full details on how group roles interact with user roles and how to manage group roles, see [Manage group permissions](/admin/org-administration/groups/managing-group-permissions) # Organization administration overview Source: https://docs.superblocks.com/admin/org-administration/overview Govern, manage, and scale access to all of your tools with Superblocks. * Securely manage user identities for developers and end-users with Single Sign-on * Simply manage access to your data and applications with permissions * Scale up access management at any size with Groups and SCIM * Customize application UIs and manage in-app permissions in code ## Start here ## All administration docs [Manage members](/admin/org-administration/members)
  • [Invite users to join](/admin/org-administration/members/invite-users)
  • [Remove a member](/admin/org-administration/members/remove-user)
  • [Permanently delete user](/admin/org-administration/members/delete-user)
[Organize members into groups](/admin/org-administration/groups)
  • [Managing user groups](/admin/org-administration/groups/managing-groups)
  • [Managing group permissions](/admin/org-administration/groups/managing-group-permissions)
[Superblocks RBAC](/admin/org-administration/rbac) [Manage organization roles](/admin/org-administration/org-roles)
  • [Using organization roles](/admin/org-administration/org-roles/using-org-roles)
  • [Custom organization roles](/admin/org-administration/org-roles/custom-roles)
  • [Permissions reference](/admin/org-administration/org-roles/permissions)
[Manage resource access](/admin/org-administration/resource-roles)
  • [Manage access to resources](/admin/org-administration/resource-roles/manage-access)
  • [Custom resource roles](/admin/org-administration/resource-roles/custom-roles)
  • [Resource base permissions](/admin/org-administration/resource-roles/base-permissions)
  • [Manage creators roles](/admin/org-administration/resource-roles/creator-roles)
Authentication & security
  • [Single Sign-On (SSO)](/admin/org-administration/auth/single-sign-on/index)
  • [SCIM](/admin/org-administration/auth/scim/index)
  • [Access tokens](/admin/org-administration/auth/access-tokens)
# Superblocks RBAC Source: https://docs.superblocks.com/admin/org-administration/rbac Use role-based access control (RBAC) to control the level of access users have to your organization and resources in Superblocks ## About permissions To perform any action in Superblocks, such as creating an Application, connecting to a Repository, or adding a user to a group, a person must have sufficient access to do so. This access is controlled by permissions where permissions are the ability to perform a specific action. For example, the ability to build with an integration is a permission. Users get permissions based on the roles they are assigned, or based on the roles assigned to groups they are a member of. ## Types of roles There are two types of roles that can be assigned to users and groups in Superblocks: **Organization roles:** Organization roles control the Superblocks features members can access and the permissions a user has to help administer the org. They can also be used to grant users access to all current and future Apps, Integrations, Workflows, and Scheduled Jobs that belong to the org. **Resource roles:** Resource roles grant a user permissions for a specific resource, for example, a specific Application, Integration, etc. ## Further reading For more info about roles, the permission they grant, and how to assign them, see: # About resource roles Source: https://docs.superblocks.com/admin/org-administration/resource-roles Use resource roles to define permissions on specific Applications, Integrations, Workflows, and Schedued Jobs You can give organization members and groups different levels of access to specific Applications, Integrations, Workflows, and Scheduled Jobs. Just choose the role that best fits each person or groups's function without giving them more access than they need. Each permissionable resource comes with a set up [built-in roles](#resources-with-roles). You can also create custom resource roles to customize levels of access. For more information, see [Custom resource roles](/admin/org-administration/resource-roles/custom-roles) Organization admins can also set base permissions that all members will receive for newly created resources. For more information, see [Setting base permissions for resources](/admin/org-administration/resource-roles/base-permissions) ## Resources with roles Not all resources support resource roles. Resources that support roles are those which let a user share an instance of a resource with users and groups. For example, applications support resource roles because users can independently share **Application A** and **Application B** with different sets of users. Data plane instances don't support resource roles since they are set up at the platform level and not individually shared with users. The following resources currently support resource-role assignments: * [Applications](#applications) * [Integrations](#integrations) * [Scheduled Jobs](#scheduled-jobs) * [Workflows](#workflows) ## Permissions for roles Each resource has a unique set of built-in roles based on the common patterns of permissions that organizations generally use. The following built-in roles are available in every organization for the following resources: ## Further reading # Resource base permissions Source: https://docs.superblocks.com/admin/org-administration/resource-roles/base-permissions Manage the resource access users receive on newly created resources with base permissions **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `roles:manage` permission ## About base permissions The base permissions of a resource define the set of permissions all members of your organization receive on newly created resources. For example, if the base permission for Integrations is set to Developer, when a new Integration is created, all members of the organization will be granted the `integration:build` permission for that Integration. ## Base permission defaults By default, members of an organization get the following permissions to the organization's resources based on the resource type: | Resource | Base permission | | - | - | | [Applications](/admin/org-administration/resource-roles#applications) | End-User | | [Integrations](/admin/org-administration/resource-roles#integrations) | No access | | [Scheduled Jobs](/admin/org-administration/resource-roles#scheduled-jobs) | No access | | [Workflows](/admin/org-administration/resource-roles#workflows) | No access | ## Setting base permissions To update the base permissions for a resource type: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/settings) 3. Click on the **Settings** tab 4. Select the base permission dropdown and choose the permissions level you want to set * Changes to base permissions only affect newly created resources. Permissions for existing resources will not be affected * Resource Admins can grant everyone within the organization different access than the base permission by changing the resource's permissions # Manage creator roles Source: https://docs.superblocks.com/admin/org-administration/resource-roles/creator-roles Change the role assigned to resource creators to limit the permissions they receive on that resource **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `roles:manage` permission ## About the creator role The creator role defines the [resource role](/admin/org-administration/resource-roles) that will be assigned to a user when they create a resource of that type. By default, creators are assigned the **Admin** role for the resource they've created. The built-in Admin roles give users all permissions to the resource they've created. To reduce the set of permissions granted to resource creators, [change the creator role](#changing-the-creator-role) for the resource type. For example, I may want to assign the [Developer](/admin/org-administration/resource-roles#applications) role to application creators so that users cannot share access to applications they create or make them public. ## Changing the creator role To update the creator role for a resource type: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/settings) 3. Click on the **Settings** tab 4. Select the creator role dropdown for the desired resource type and choose the role you want assigned when a user creates a resource Changing the creator role only affects newly created resources. Users who have created resources prior to the change will still have the built-in **Admin** role to that resource. # About custom resource roles Source: https://docs.superblocks.com/admin/org-administration/resource-roles/custom-roles Customize permissions granted on an individual resource with custom resource roles **Who can use this feature?** Organization **Owners**, **Admins**, and other users with the `roles:manage` permission Custom resource roles let you gain more control over the permissions users have to manage individual Applications, Integrations, Workflows, and Scheduled Jobs. For example, you can create custom roles like: | Custom role | Description | Resource | Permissions | | - | - | - | - | | QA | Lets the QA team review application changes using commit previews, but doesn't give them access to the live app. | Application | `apps:preview` | | Maintainer | Grants permissions to edit an integration's credentials while not letting them delete or share the integration | Integration | `integrations:update` `integrations:build` | | Contributor | Can make updates to assigned Workflows, but can't deploy their changes. | Workflow | `workflows:update` | ## Creating a custom role To create a custom resource role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/resource-roles) 3. Click on the **Resource roles** tab 4. Locate the resource you want to create a custom role for 5. On the resource roles table, click **+** icon ![Create custom resource role](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/create-custom-resource-role.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=fc2eb05d10fbcf51b0308103ead73bdd) 6. Type a name and description for the custom role 7. Click **Create** 8. Add permissions to your custom role by selecting the permissions in the permission table 9. Once you've selected all the permissions you want assigned to the role, click **Save** After you create a custom role: * Anyone with the `*:share` permission of a resource can assign the role to users or groups. See [Managing access to resources](/admin/org-administration/resource-roles/manage-access) * You can make this role what everyone receives when new resources are created. See [Resource base permissions](/admin/org-administration/resource-roles/base-permissions) * You can make the role the one assigned to resource creators. See [Manage creator roles](/admin/org-administration/resource-roles/creator-roles) ## Editing a custom role's details To edit the name or description of a custom role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/resource-roles) 3. Click on the **Resource roles** tab 4. Next to the role you want to edit, select the dropdown menu (⋯), then click **Edit details** 5. Change the role as required, then click **Save** ## Editing a role's permissions To edit the permissions associated with a custom role: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/resource-roles) 3. Click on the **Resource roles** tab 4. Locate the role you want to edit 5. Check/uncheck the boxes associated with permissions you want to add/remove from the role 6. Once you've made all your permission selections, click the **Save** button at the bottom of the page ## Deleting a custom role 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Roles & Permissions**](https://app.superblocks.com/roles-and-permissions/resource-roles) 3. Click on the **Resource roles** tab 4. Next to the role you want to delete, select the dropdown menu (⋯), then click **Delete** 5. In the confirmation dialog, choose a new role to assigned to users that currently are assigned the role being deleted, or select **Remove access** 6. Click **Reassign & delete** ## Precedence for different levels of access Role and permissions are additive. If a person is given different levels of access through different avenues the user will have the sum of all access grants. For example, if the organization Owner assigns a user the [End-user organization role](/admin/org-administration/org-roles#builtin-organization-roles), and then an app admin gives the user the [Developer](/admin/org-administration/resource-roles#applications) role on their Application, the user will be able to edit the application shard with them even though they cannot create their own Applications. # Manage access to resources Source: https://docs.superblocks.com/admin/org-administration/resource-roles/manage-access Manage individual, group, and app access to individual org resources **Who can use this feature?** Organization **Owners**, **Admins**, and others with the `*:share` access to a resource ## Who can manage access Users with the `share` permission to a resource can grant others access to that resource. This includes users with both `share` permission to an individual resource, as well as users with an organization role granting them `share` permission to all resources. For example, a user with the [Admin](/admin/org-administration/resource-roles#applications) role on the **Customer 360** application is able to manage others' access to that application. Similarly, a user with the `integrations:share` permission granted to them through an [organization role](/admin/org-administration/org-roles) can manage access to all Integrations. ## Granting users access to resources Resources in Superblocks (Apps, Integrations) can be shared with specific users or groups. When you share the resource, you can select the resource role to grant to the user or group. This role dictates the permissions the user has over the resources. To grant access to an individual resource: 1. Navigate to the resource (Application, Integration) you want to grant access to 2. Click into the editor or configuration page for that resource 3. Find and click on the **Share** button in the upper right-hand corner of the page 4. In the dialog box that appears, search for the individual or group you want to share the resource with 5. Select the **Resource role** you want to assign 6. Click **Share** ![Grant group access to an Application](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/assign-resource-role.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=d5e689e55e756a74124dd88094819e59) ## Granting specific apps access to integrations In addition to users and groups, integrations can be shared with specific **apps**. When an integration is restricted to one or more apps, users can only build with this integration from within the specific apps. An integration can be shared across all applications, or restricted to specific applications. * **All apps**: The integration is available across the organization to users who have access to it. This is the default for new and existing integrations. * **Specific apps**: The integration is only available to the apps you select. To control which apps can use an integration: 1. Navigate to the [**Integrations**](https://app.superblocks.com/integrations) page and select the integration 2. Click the **Share** button 3. In the **App availability** section, select **Specific apps** and choose the apps to grant access, or select **All apps** to make it available across the organization 4. Click **Share** to save your changes ### How app and user-level integration access combine when building App availability and a builder's own integration permission are checked independently. * App availability determines which integrations are available within an app. * A builder's integration permission determines which of those integrations he or she can build with. Within a given app, a user can only build with an integration when **both** of the following are true: * The integration is available to that app (either **All apps** or that **specific app**) * The builder has the integration's `build` permission, granted directly or through a group. This means: * Sharing an integration with an app does not give that app's builders permission to build with that integration * A builder's integration permission does not let them use the integration in an app the integration has not been shared with If an integration is already in use within an app and that app's access is removed, existing APIs using this integration will continue to execute. However, builders will not be able to build new APIs with that integration. ### Integration access in published apps (for end-users) A user does not need access to a specific integration in order to use the integration as an end-user of an application. This is intentional; the resource permissions for integrations only restrict who can build with the integration (and in which apps). Once the app is published, users can access any features in the app that are shared with them according to their [App-level RBAC](/building-with-clark/rbac). ## Auditing access changes All changes to resource permissions, including granting or revoking user, group, and app access, are recorded in [Audit logs](/admin/audit-logs). Use audit logs to review who changed access to a resource and when. To view changes to integration access, filter by **Resource: Integration**. ## Granting access to all resources Resource roles give a user access to specific resources. Organization roles differ from resource roles in that they can grant access to **all current and future resources** of a type. To learn more, see [About organization roles](/admin/org-administration/org-roles) ## Change the level of access granted Once a user or group has access to a resource, you can change the level of access they've been granted. To change the access level: 1. Navigate to the resource (Application, Workflow, Integration, etc) you want to grant access to 2. Click into the editor or configuration page for that resource 3. Find and click on the **Share** button in the upper right-hand corner of the page 4. Find the user or group you want to update 5. Select the role dropdown and select the new role you want to set ## Removing access to a resource To remove an individual or group's access to a resource: 1. Navigate to the resource (Application, Workflow, Integration, etc) you want to grant access to 2. Click into the editor or configuration page for that resource 3. Find and click on the **Share** button in the upper right-hand corner of the page 4. Find the user or group you want to remove access from 5. Select the role dropdown and select **Remove** 6. In the confirmation dialog, click **Confirm** ![Remove access to individual resource](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/administration/remove-resource-role.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=981b21ed72bdc2bdd7f98716fc0b5cad) # Plan & Usage Source: https://docs.superblocks.com/admin/plan-and-usage Walk through the Plan & Usage page: commitment bar, charts, checkpoint-level GAU spend, and published app charges **Plan & Usage** helps admins understand the ROI of Superblocks at a granular level: which builders and apps create the most value, what it costs to deliver a specific Clark outcome, and how published apps are used against your dollar commit. Open **Organization Settings → Plan & Usage** (admins with billing access). Concepts (GAUs, dollar commit, published apps) are on [Billing overview](/admin/billing-overview). Limits and alerts are on [Spend management](/admin/spend-management). This is the experience for customers with a dollar commit with Superblocks. If your organization has a special contract, usage is shown in GAUs instead of dollars in the commitment summary, the usage chart, the usage table (including checkpoint rows), and the published applications view. ![Plan & Usage overview](https://mintcdn.com/superblocks/UICUx-Uy-77ExtFv/images/administration/plan-and-usage/01-overview.png?fit=max\&auto=format\&n=UICUx-Uy-77ExtFv\&q=85\&s=3228b0ed26031891c8486b853974f544) ## Commitment and plan summary At the top of the page, the plan summary shows your contract period and how consumption tracks against your dollar commit. The **commitment / usage bar** summarizes Clark (GAU) and published app usage for the current commit cycle, so you can see how the value you are getting maps to your committed spend. ![Commitment and usage bar](https://mintcdn.com/superblocks/UICUx-Uy-77ExtFv/images/administration/plan-and-usage/02-commitment-bar.png?fit=max\&auto=format\&n=UICUx-Uy-77ExtFv\&q=85\&s=a167011fefbc62043c789e55b78f7cde) ## Filters, date range, and chart Use the filter bar to focus the chart and tables on the work that matters: * **Date range** (for example Current Month, Contract Period, or previous-month presets) * **User** and **App** filters * **Export** for CSV download of the current usage view Daily usage is aggregated in UTC. The chart shows how usage and value break down over time. You can filter by SKU (**All**, **GAUs**, **Published apps**), group (**Total**, **By user**, **By app**), and choose **Daily** or **Monthly** granularity. ![Usage chart](https://mintcdn.com/superblocks/UICUx-Uy-77ExtFv/images/administration/plan-and-usage/03-usage-chart.png?fit=max\&auto=format\&n=UICUx-Uy-77ExtFv\&q=85\&s=75e3252993f9adcf90dfc5bb4ec58aaf) ## Usage table and group by Select the **Shared GAUs** (or equivalent shared spend) resource tile to open the usage table. **Group by** lets you nest rows by **User**, **App**, and **Day** (any combination, reorderable). Use this to see which people, apps, and days deliver the highest-ROI work. ![Usage breakdown grouped by User, App, and Day](https://mintcdn.com/superblocks/UICUx-Uy-77ExtFv/images/administration/plan-and-usage/04-usage-breakdown.png?fit=max\&auto=format\&n=UICUx-Uy-77ExtFv\&q=85\&s=c55f01e189682fc5cbe5a0321066d8df) ### Checkpoint-level rollup GAU usage rolls up to the relevant **Clark checkpoint** (an accepted set of AI changes), not to each individual prompt. Expand a group to see checkpoint rows with: * Checkpoint label (or a fallback such as "User accepted AI changes") * Date and time * Cost (dollars on dollar-commit) * Billing type when shown (**Committed** or **Overage**) That is how you connect spend to a concrete outcome: what it took to ship a specific change with Clark. Usage that is not tied to an accepted checkpoint (for example work that was never accepted, or usage recorded before checkpoint tracking) can appear under a **No checkpoint** aggregate within the group. Group totals still include that usage. ## Published applications Select the **Published apps** resource tile to open the published applications statement. This SKU was previously named **Deployed apps**. Each row is one app for one month it was charged, and can include: * App name and creator * **Months billed** (current month may be marked as of today) * **Billing type**, including **Pending** for a published app that will be charged when the month closes * Views (when available) * Cost Use this view to see which published apps are in production, how they are used, and how that usage maps to your commit, including charges that are still pending for the current month. ## Related * [Billing overview](/admin/billing-overview) — GAUs, dollar commit, and published app concepts * [Spend management](/admin/spend-management) — limits, alerts, and refills controls * [Self-serve plans](/admin/self-serve-plan) — Teams packs and GAU refills # AWS Secrets Manager Source: https://docs.superblocks.com/admin/secrets-management/aws-secrets-manager **Who can use this feature?**\\ Organization **Owners**, **Admins**, and other users with the [`secrets:manage`](/admin/org-administration/org-roles/permissions) permission Connect to your AWS Secrets Manager to securely access application secrets, API keys, and sensitive data from your Superblocks integrations. This guide covers: * How to [**set up a new secret store**](#set-up) connected to AWS Secrets Manager * Configuring and managing [**caching**](#caching) for your secret store to improve API performance * [**Using secrets**](#using-secrets) throughout the Superblocks platform ### Prerequisites To set up AWS Secrets Manager as a secret store for Superblocks you'll need: * An AWS account with [**AWS Secrets Manager**](https://aws.amazon.com/secrets-manager/) configured * Permission to create new IAM policies for your AWS account ## Set up ### Create IAM policy [**Create an IAM policy**](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html) to grant Superblocks access to your secrets This policy should be associated with either an IAM user (for Access Key auth) or an IAM role (for Assume Role auth when self-hosting the data plane). Below is an example policy: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": ["arn:aws:secretsmanager:${REGION}:${ACCOUNT_ID}:secret:*"] }, { "Effect": "Allow", "Action": ["secretsmanager:ListSecrets"], "Resource": "*" } ] } ``` We recommend only granting Superblocks access to the minimum set of secret ARN's your team will use in Superblocks. For added security, create secrets that are prefixed with `superblocks/${env}/` to easily identify the secrets used in Superblocks. ### Configure secret store Configure a new secret store in Superblocks: 1. Go to the [**Secrets Management**](https://app.superblocks.com/secrets-management) page in Superblocks 2. Click the **AWS Secrets Manager** tile 3. Name your secret store integration 4. If your secrets follow [hierarchical naming conventions](https://docs.aws.amazon.com/prescriptive-guidance/latest/secure-sensitive-data-secrets-manager-terraform/naming-convention.html), specify a **Prefix** to filter secrets in this store. For example, if Superblocks secrets are all named like `superblocks/${env}/secret1`, `superblocks/${env}/secret2`, etc, then `superblocks/${env}/` will be the corresponding prefix value. 5. Specify your AWS **Region** 6. Select **Auth type** > [tab] Access Key > > Paste the **Access key ID** and **Secret access key** for the IAM user Superblocks will act on behalf of. > [tab] Assume Role > > Assume role auth is supported only when using Hybrid or Cloud-Prem achitectures where the data plane is self-hosted > > Specify the **IAM Role ARN** that the data plane will assume via an AWS account trusted entity. 7. Configure caching rules for this store 8. Optionally, add more configurations for [different environments](/development-lifecycle/build/data-tags) 9. Click **Create** Your secret store is now configured. Developers can now [reference secrets](/development-lifecycle/build/using-secrets) in their integration forms. ## Caching If enabled, Superblocks can cache your secrets, reducing calls to your secrets manager and improving API performance when using secrets. Caching can be configured for each of your secret store's configurations, letting you set different policies based on the environment. To configure caches, go to [**Secrets Management**](https://app.superblocks.com/secrets-management) and click into your secrets store. From here you can: * Update the **Cache TTL (seconds)** to your desired caching interval * **Clear the cache** if you've rotated a secrets and need Superblocks to refetch secret values ![Manage secret caching](https://superblocks-demo.s3.us-west-2.amazonaws.com/secrets-caching.png "Manage secret caching") If you're self-hosting with Hybrid or Cloud-Prem architectures, secrets are cached in-memory by the data plane. For scaled deployments, you'll need to clear each instance's cache individually when rotating secrets. To rotate secrets more easily, disable caching first. Then, after updating the secret, re-enable caching. ## Using secrets For details on how to reference secrets in integration forms, see [Using secrets](/development-lifecycle/build/using-secrets). # Google Secret Manager Source: https://docs.superblocks.com/admin/secrets-management/google-secrets-manager **Who can use this feature?**\\ Organization **Owners**, **Admins**, and other users with the [`secrets:manage`](/admin/org-administration/org-roles/permissions) permission Connect to your Google Secret Manager to securely access application secrets, API keys, and sensitive data from your Superblocks integrations. This guide covers: * How to [**set up a new secret store**](#set-up) connected to Google Secrets Manager * Configuring and managing [**caching**](#caching) for your secret store to improve API performance * [**Using secrets**](#using-secrets) throughout the Superblocks platform ### Prerequisites To set up Google Secret Manager as a secret store for Superblocks you'll need: * A Google Cloud Platform (GCP) project with the [**Secrets Manager API**](https://console.cloud.google.com/marketplace/product/google/secretmanager.googleapis.com) enabled * A GCP account with the following IAM roles for your GCP project: * **Create Service Accounts** (`roles/iam.serviceAccountCreator`) * **Secret Manager Admin** (`roles/secretmanager.admin`) ## Set up ### Create a service account Get started by [**creating a service account**](https://cloud.google.com/iam/docs/service-accounts-create#iam-service-accounts-create-console) for each GCP project you want to connected to Superblocks. Superblocks will use this service account when reading secrets from Google Secret Manager. ### Grant access to secrets Next, grant your service account permissions for the secrets you want to reference in Superblocks. To grant access, give your account the following permissions: * Secret Manager Secret Accessor * Secret Manager Secret Viewer See Google's full documentation for how to [**Manage access to secrets**](https://cloud.google.com/secret-manager/docs/manage-access-to-secrets). ### Create a service account key [**Create a service account key**](https://cloud.google.com/iam/docs/keys-create-delete#creating) using the Google Cloud console and download the JSON key file. ### Configure secret store Finally, configure a new secret store in Superblocks: 1. Go to the [**Secrets Management**](https://app.superblocks.com/secrets-management) page in Superblocks 2. Click the **Google Secrets Manager** tile 3. Name your secret store 4. Paste your Google **Project ID** and **Service account key** into the form 5. Configure caching rules for this store 6. Optionally, add more configurations for [different environments](/development-lifecycle/build/data-tags) 7. Click **Create** Your secret store is now configured. Developers can now [reference secrets](/development-lifecycle/build/using-secrets) in their integration forms. ## Caching If enabled, Superblocks can cache your secrets, reducing calls to your secrets manager and improving API performance when using secrets. Caching can be configured for each of your secret store's configurations, letting you set different policies based on the environment. To configure caches, go to [**Secrets Management**](https://app.superblocks.com/secrets-management) and click into your secrets store. From here you can: * Update the **Cache TTL (seconds)** to your desired caching interval * **Clear the cache** if you've rotated a secrets and need Superblocks to refetch secret values ![Manage secret caching](https://superblocks-demo.s3.us-west-2.amazonaws.com/secrets-caching.png "Manage secret caching") If you're self-hosting with Hybrid or Cloud-Prem architectures, secrets are cached in-memory by the data plane. For scaled deployments, you'll need to clear each instance's cache individually when rotating secrets. To rotate secrets more easily, disable caching first. Then, after updating the secret, re-enable caching. ## Using secrets For details on how to reference secrets in integration forms, see [Using secrets](/development-lifecycle/build/using-secrets). # HashiCorp Vault Source: https://docs.superblocks.com/admin/secrets-management/hashicorp-vault **Who can use this feature?**\\ Organization **Owners**, **Admins**, and other users with the [`secrets:manage`](/admin/org-administration/org-roles/permissions) permission Connect to your HashiCorp Vault to securely access application secrets, API keys, and sensitive data from your Superblocks integrations. This guide covers: * How to [**set up a new secret store**](#set-up) connected to HashiCorp Vault * Configuring and managing [**caching**](#caching) for your secret store to improve API performance * [**Using secrets**](#using-secrets) throughout the Superblocks platform ### Prerequisites To set up HashiCorp Vault as a secret store for Superblocks you'll need: * An on-premises deployment of HashiCorp OR a HashiCorp account with [**Vault**](https://www.vaultproject.io/) configured * Permission to manage HashiCorp Services, access to manage HashiCorp Vault cluster, and ability to create and configure Secrets engines ## Set up ### Create Secrets Engine with secrets key-value pair To set up a key-value secrets engine in HashiCorp Vault: 1. Navigate to your **Vault** Cluster 2. Launch the Vault **Web UI** 3. In the Vault Web UI, navigate to **Secrets Engine** 4. Proceed to create a new secrets engine 5. Choose KV Version. Opt for either version 1 or 2 of the Key-Value (KV) secrets engine, based on your requirements 6. Add your secrets as key-value pairs 7. Customize the path and configure access to your secrets as needed ### Configure secret store Finally, configure a new secret store in Superblocks: 1. Go to the [**Secrets Management**](https://app.superblocks.com/secrets-management) page in Superblocks 2. Click the **HashiCorp Vault** tile 3. Name your secret store 4. Paste or enter in the info for Address, Namespace, Path, Version, Auth Type, and Token configurations that were set in your Secrets engine
Address The Address is your cluster's public URL. It is located on the **Vault** Cluster page when you select your **Vault**.
Namespace The [Namespace](https://developer.hashicorp.com/vault/docs/enterprise/namespaces) is used for creating service accounts and managing who can access what. The default value is `admin`. It is optional and configured on the secrets engine.
Path The Path tells **Vault** which secrets engine it should route requests to. It is configured in the Key Value secrets engine.
Version The Version is which version of Key Value secrets engine to use (either v1 or v2 currently). It is configured in the Key Value secrets engine.
Auth Type The Auth Type specifies which Auth flavor to use for connecting to HashiCorp Vault. The default configuration is Token. App Role is also available which requires a `Role ID` and `Secrets ID`.
Token The Token is used to authenticate requests for secrets. It is located on the **Vault** Cluster page when you select your **Vault**.
1. Configure caching rules for this store 2. Optionally, add more configurations for [different environments](/development-lifecycle/build/data-tags) 3. Click **Create** Your secret store is now configured. Developers can now [reference secrets](/development-lifecycle/build/using-secrets) in their integration forms. ## Caching If enabled, Superblocks can cache your secrets, reducing calls to your secrets manager and improving API performance when using secrets. Caching can be configured for each of your secret store's configurations, letting you set different policies based on the environment. To configure caches, go to [**Secrets Management**](https://app.superblocks.com/secrets-management) and click into your secrets store. From here you can: * Update the **Cache TTL (seconds)** to your desired caching interval * **Clear the cache** if you've rotated a secrets and need Superblocks to refetch secret values ![Manage secret caching](https://superblocks-demo.s3.us-west-2.amazonaws.com/secrets-caching.png "Manage secret caching") If you're self-hosting with Hybrid or Cloud-Prem architectures, secrets are cached in-memory by the data plane. For scaled deployments, you'll need to clear each instance's cache individually when rotating secrets. To rotate secrets more easily, disable caching first. Then, after updating the secret, re-enable caching. ## Auth token renewal When using the **token** auth type for accessing the configured secret store, if the configured token is renewable, it will be renewed every time the secret store is accessed. For the token to be renewed it must: * Be renewable (i.e. the "renewable" attribute is true) * Have permissions to renew itself * Not be expired If the preceding conditions are met, the token will be renewed to the TTL that was set when the token was initially created (e.g. if the token was created with a TTL of 1 hour, each renewal will reset the TTL to 1 hour). The token will be renewed every time the secret store is accessed, for example when an API runs a step that uses an integration referencing the secret store. Note: If the access token has a max TTL set on it, the renewed TTL will be capped so that the token's total lifetime never exceeds the max TTL. E.g. Given a token with an initial TTL of 4 minutes and a max TTL of 5 minutes, if the token is renewed after 3 minutes (1 minute remaining), the TTL will be reset to 2 minutes (not 4 minutes) ## Using secrets For details on how to reference secrets in integration forms, see [Using secrets](/development-lifecycle/build/using-secrets). # Secrets management Source: https://docs.superblocks.com/admin/secrets-management/overview Set up and manage secret stores for your organization Access secrets securely in your integrations with **Secrets Management**. Seamlessly integrate Superblocks with secret managers like AWS Secrets Manager, Google Secret Manager, and Hashicorp Vault to gain frictionless access to your most sensitive credentials, tokens, and API keys. With Secrets Management, you get: * **Enhanced security**: Securely store secrets in trusted secret management systems. Superblocks seamlessly connects to your secret manager, ensuring the confidentiality of your credentials. * **Streamlined development**: Reference secrets from your secret store directly in integration forms. No more copy-pasting or hardcoding credentials. * **Increased performance**: Configure custom caching policies for each environment, reducing the frequency of requests to your secret manager and enhancing API performance. ## Setup quickstart Follow these guides to set up Secrets Management with Superblocks. # Self-serve plans Source: https://docs.superblocks.com/admin/self-serve-plan Learn how Teams plan GAUs work, what's included, how to buy packs, and how to set up automatic or one-time GAU refills ## How GAUs work [Governed Agent Units (GAUs)](/admin/billing-overview#what-is-a-governed-agent-unit) are used across Clark (Superblocks' AI agent) and other governance and AI features. Each AI interaction consumes GAUs based on the complexity of the request. Here are some example prompts and their cost: | User prompt | Work done | GAUs used | | - | - | - | | Add a header section with title and subtitle | Creates a reusable header component and applies existing page typography styles | 1 | | Change the top navigation background to black | Updates navigation styles and verifies contrast on existing text/icons | 2 | | Connect Salesforce opportunities and show a table + column chart | Explores the data with sample queries in ![](https://upload.wikimedia.org/wikipedia/commons/thumb/f/f9/Salesforce.com_logo.svg/1280px-Salesforce.com_logo.svg.png)Salesforce, identifies the right object and fields with the user, then implements both a table and chart | 4 | | Build a full sales dashboard from this schema | Generates a step-by-step plan, builds layout/components, connects data, and validates the final app | 8 | ## Included GAUs Teams plans use an **organization-level GAU pool** shared by all builders. You are not charged per builder seat. Additional org-level GAU packs are available for purchase. All GAUs reset monthly. ## GAU packs **Org-level top-ups:** Purchase GAUs that can be shared across all users in your organization | GAUs | Cost per month (Annual plan) | Cost per month (Monthly plan) | | - | - | - | | 100 GAUs | **\$100** /month | **\$125** /month | | 250 GAUs | **\$250** /month | **\$313** /month | | 500 GAUs | **\$500** /month | **\$625** /month | | 1,000 GAUs | **\$1000** /month | **\$1250** /month | | 2,500 GAUs | **\$2500** /month | **\$3125** /month | | Custom volume | [Contact Sales →](mailto:pricing@superblockshq.com) | [Contact Sales →](mailto:pricing@superblockshq.com) | GAU packs are billed in-line with your billing schedule. [Contact sales](mailto:pricing@superblockshq.com) for higher volumes. ## Usage tracking Monitor spend and usage on [Plan & Usage](/admin/plan-and-usage): charts, group-by User / App / Day, checkpoint-level rollup, and published app charges. Configure limits, alerts, and Teams refills on [Spend management](/admin/spend-management). ## GAU refills GAU refills are available on the **Teams** plan. Enterprise customers manage spending through [Spend management](/admin/spend-management) controls. When your shared GAU pool runs low, Superblocks can automatically purchase more GAUs, or you can buy a one-time top-up on demand. Navigate to **Organization Settings > Spend management** to configure refills. ### Automatic GAU refills Automatic refills help your team keep building when the pool runs low. When your GAU balance drops below a threshold you set, Superblocks automatically purchases additional GAUs using the payment method on file. #### Setting up automatic refills 1. Toggle **"Automatically purchase more GAUs when running low"** to enable auto-refills 2. Set a **Refill threshold**: the GAU balance at which a refill is triggered 3. Set a **Refill amount**: how many GAUs to purchase each time 4. Set a **Maximum refill amount**: a monthly cap on total automatic refill spending Refills are charged to the default payment method on file. You can pause automatic refills at any time by toggling the setting off. #### How automatic refills work When enabled, Superblocks monitors your organization's shared GAU pool. Once the balance drops to or below your configured threshold, a refill is triggered automatically: 1. The system checks your remaining GAUs against the **Refill threshold** 2. If the balance is at or below the threshold, it charges the **Refill amount** to your payment method 3. New GAUs are added to your shared pool immediately 4. Refill activity is logged in the **Refill history** table at the bottom of the page The **Maximum refill amount** acts as a monthly safety net. Even if usage spikes, automatic refills will not exceed this cap within a single billing cycle. ### One-time GAU purchases You can purchase a one-time GAU top-up from the Spend management page without enabling automatic refills. Click **"purchase a one-time refill"** in the GAU refills section to add GAUs immediately. One-time purchases appear in the Refill history table with the source marked accordingly. See [GAU packs](#gau-packs) for available pricing. ### Spend limits Teams plans also support per-user spend limits to control how GAUs are distributed across your team. See [Spend management](/admin/spend-management) for details on setting default and custom per-user limits. ### Refill history The Spend management page includes a refill history table that shows all GAU purchases, both automatic and one-time. Each entry includes: * Date and time of the refill * Number of GAUs added * Source (automatic or manual) * Payment status # Spend management Source: https://docs.superblocks.com/admin/spend-management Control GAU spending with organization-wide limits, per-user budgets, and programmatic management Superblocks gives administrators control over GAU and dollar spend. From the [**Spend Management**](https://app.superblocks.com/spending) page in organization settings, you can set organization-wide caps, assign per-user budgets, configure refill behavior (Teams), and set spend alerts. Spend Management is available on Enterprise and Teams plans. For charts, checkpoint-level usage, and published app charges, use [Plan & Usage](/admin/plan-and-usage) instead. ![Spend Management overview](https://mintcdn.com/superblocks/SDBk1P9hQxjmCvTZ/images/administration/spend-management/spend-management-overview.png?fit=max\&auto=format\&n=SDBk1P9hQxjmCvTZ\&q=85\&s=281743ad70c40653bbf2931ba24d561a) ## Spend limits Spend limits prevent unexpected charges by capping usage at both the organization and individual user level. You can set org-wide overage spending limits, which are enforced based on your plan's billing cycle (monthly or annual). You can also set monthly per-user spend limits. Both budgets reset automatically at the start of each period. ### Maximum contract overage Enterprise organizations can set an **overage cap**: the maximum additional usage your team can consume beyond your contractual commit. This is your primary guardrail against runaway spending if your team exceeds your committed usage. ![Setting a maximum overage limit](https://mintcdn.com/superblocks/SDBk1P9hQxjmCvTZ/images/administration/spend-management/spend-management-max-overage.png?fit=max\&auto=format\&n=SDBk1P9hQxjmCvTZ\&q=85\&s=4da6f58dfdccccdd72c0fbb1d01cef95) ### Default usage limit (monthly) Set a default allowance that applies to every user in your organization. This is the maximum any individual user can consume per month. Per-user limits always reset monthly, regardless of your plan's billing cycle. 1. In the **Spend limits** section, click **+** next to **Default usage limit (monthly)** 2. Enter the limit 3. The limit takes effect immediately for all users without a custom override ### Custom per-user usage limits Override the default limit for specific users who need more (or fewer) GAUs or dollars. 1. Click **+** next to **Custom per-user usage limits** 2. Select a user from the dropdown, including pending invitees who have not accepted yet 3. Set their individual limit Custom limits take precedence over the default. When a user with a pending invite accepts, their pre-configured limit applies immediately; no additional admin action is needed. ![Spend Limits with configured overage and per-user budgets](https://mintcdn.com/superblocks/SDBk1P9hQxjmCvTZ/images/administration/spend-management/spend-management-limits-configured.png?fit=max\&auto=format\&n=SDBk1P9hQxjmCvTZ\&q=85\&s=c3f97660ac1b1b37bb4deca327dff8ca) ![Adding a custom per-user limit](https://mintcdn.com/superblocks/SDBk1P9hQxjmCvTZ/images/administration/spend-management/spend-management-custom-user-limit.png?fit=max\&auto=format\&n=SDBk1P9hQxjmCvTZ\&q=85\&s=587d7c9d8fbc97d404d1fcd86c80e8fe) For Enterprise dollar-commit contracts, limits and usage displays are shown in dollar amounts instead of GAUs. ## What happens when a limit is reached When a user or organization reaches a configured spend limit: * AI-powered features (Clark and other AI interactions) are paused for the affected scope * Users see a notification explaining that their GAU limit has been reached * Administrators can increase limits or purchase additional GAUs to resume usage * Limits reset automatically at the start of each period (monthly for per-user limits; your billing cycle for the org-wide overage cap) ## Programmatic spend management via MCP You can monitor spending and configure limits programmatically using the [Superblocks MCP server](/admin/mcp-server). This is useful for automated monitoring, integrating with internal tools, or managing limits at scale. ### Available tools | Tool | Description | | - | - | | `get_billing_plan_summary` | Get current plan details including GAU allocation, usage, billing cycle dates, and published app counts | | `get_billing_usage_daily` | Get daily GAU usage for a date range — one row per day with total GAUs consumed | | `get_billing_usage_records` | Get per-user GAU usage records for a date range, including top consumers | | `list_billing_usage_limits` | View all configured spend limits — organization-wide and per-user | | `update_org_billing_usage_limit` | Set or update the organization-wide GAU overage cap | | `update_user_billing_usage_limit` | Set or update a per-user GAU limit, or configure the default limit for all users | All billing MCP tools require the `billing:manage` permission. ### Example: Check current usage Ask your AI coding agent: ``` What's our current GAU usage this billing cycle? ``` The agent will call `get_billing_plan_summary` and return your current usage, remaining GAUs, and billing cycle dates. ### Example: Set a per-user limit ``` Set a default per-user limit of 50 GAUs per month for my Superblocks org. ``` The agent will call `update_user_billing_usage_limit` with `is_default: true` and `credit_limit: 50`. ### Example: Monitor daily usage trends ``` Show me daily GAU usage for the past 30 days. ``` The agent will call `get_billing_usage_daily` with the appropriate date range and return a breakdown of daily consumption. ## Spending notifications New Spend alerts notify administrators by email when usage approaches configured thresholds, so you can take action before hitting a billing surprise. Configure alerts from the **Spend alerts** section at the bottom of the Spend Management page. Spend alerts are rolling out progressively. If you don't see the Spend alerts section on your Spend Management page, contact support to have it enabled for your organization. ### Alert types Superblocks supports four alert types. The types available to your organization depend on your plan: | Alert type | Description | TEAMS | Enterprise | | - | - | - | - | | **Organization spend** | Fires when total org usage crosses a threshold (percentage of allocation, GAUs used, or GAUs remaining) | ✓ | ✓ | | **Per-user spend** | Fires when an individual user's usage crosses a GAU threshold | ✓ | ✓ | | **Overage spend** | Fires when overage consumption crosses a specified threshold. Relevant for Enterprise plans. | — | ✓ | | **Refill spend** | Fires when cumulative GAU refill spending crosses a threshold in the current cycle. Relevant for pay-as-you-go plans (Teams). | ✓ | — | Enterprise contracts denominated in dollars (dollar commit) display all thresholds and usage in dollar amounts instead of GAUs. ### Configuring alerts 1. Navigate to **Organization Settings > Spend Management** 2. Scroll to the **Spend alerts** section 3. Click **+ Add alert** 4. Choose an alert type — only types available on your plan are shown 5. Set one or more thresholds (for example, notify at 80% and 100% of your allocation) 6. Save the alert Alerts are evaluated in real time as usage is recorded. When a threshold is crossed, an email is sent to all organization administrators. Each threshold fires at most once per billing cycle — it re-arms automatically when a new cycle begins. ### Threshold units The units available depend on the alert type: * **Organization spend:** percentage of allocation, GAUs used, or GAUs remaining * **Per-user spend:** GAUs consumed by a single user * **Overage spend:** overage GAUs consumed (or dollars, on dollar-commit plans) * **Refill spend:** GAUs or dollars spent on refills ### Delivery Spend alerts are delivered via email to all organization administrators. Per-user spend alerts also notify the individual user who triggered the threshold. # Superblocks on AWS Source: https://docs.superblocks.com/admin/superblocks-on-aws/aws How Superblocks maps to AWS services — Aurora PostgreSQL, Bedrock, S3, and more Superblocks on AWS means your builders create apps while your data, inference, and storage stay within your existing AWS security boundary. With [Cloud-Prem](/enterprise/cloud-prem/aws), the entire Superblocks platform runs in your AWS account — control plane, data plane, inference, databases, and storage. With [Hybrid](/enterprise/hybrid-architecture/overview), Superblocks manages the control plane while you run the data plane in your AWS network and integrate with your AWS services — Aurora PostgreSQL for app databases, Bedrock for App AI, S3 for file storage — so your data stays on AWS infrastructure you control. ## Platform mapping | Superblocks feature | AWS service | Description | | - | - | - | | [Database](/admin/superblocks-on-aws/database) | **Amazon Aurora PostgreSQL** | Each app gets its own managed PostgreSQL database on Aurora PostgreSQL, with automatic schema migrations on deploy. Aurora PostgreSQL is the only engine Superblocks Database provisions | | [Inference](/admin/superblocks-on-aws/inference) | **Amazon Bedrock** | Clark AI runs inference through Bedrock, burning down your existing AWS commitment and reducing Clark GAU usage | | [App AI](/integrations/app-ai) | **Amazon Bedrock** | Runtime AI features in deployed apps route through Bedrock using models and regions you control | | [File Store](/admin/superblocks-on-aws/file-store) | **Amazon S3** | Each app gets its own isolated S3 bucket for file uploads, reports, and other unstructured data | ## What this means for your organization **Burn down your AWS commitment.** Clark inference, app databases, and file storage all run on AWS resources, contributing to your existing Enterprise Discount Program (EDP) or committed spend, and reducing Clark GAU usage. Also purchasing Superblocks through [AWS Marketplace](/admin/superblocks-on-aws/aws-marketplace) draws down 100% of your Superblocks spend against your AWS commitment and earns AWS credits on top. **Data stays in your security boundary.** Whether you choose Cloud-Prem or Hybrid, your application data, AI inference, and file storage remain on AWS infrastructure inside your approved security boundary. No data leaves your network for processing. **Govern with existing policies.** Superblocks integrates with your existing IAM policies, VPC network controls, and security groups. No new governance model to adopt. ## Deployment options Superblocks offers multiple deployment models on AWS: | Model | Description | Learn more | | - | - | - | | **Hybrid** | Data plane runs in your AWS VPC; control plane managed by Superblocks | [Hybrid architecture](/enterprise/hybrid-architecture/overview) | | **Cloud-Prem** | Fully managed single-tenant deployment in your AWS account | [Cloud-Prem on AWS](/enterprise/cloud-prem/aws) | ## Get started 1. Hybrid only: [plan your data planes](/enterprise/hybrid-architecture/plan/index) and data tags, then deploy each data plane 2. Configure your [database backend](/admin/superblocks-on-aws/database) to use Amazon Aurora PostgreSQL 3. Point Clark inference at [Amazon Bedrock](/admin/superblocks-on-aws/inference) 4. Set [App AI](/integrations/app-ai) to route runtime AI through Bedrock 5. Configure [file storage](/admin/superblocks-on-aws/file-store) to use S3 # AWS Marketplace Source: https://docs.superblocks.com/admin/superblocks-on-aws/aws-marketplace Purchase Superblocks through the AWS Marketplace to earn AWS platform credits, draw down on your AWS commitment, and accelerate procurement. Superblocks is available as a Private Offer on **AWS Marketplace**. Transacting through Marketplace gives your organization three direct benefits over a standard direct purchase. ## Benefits ### 2% earned in AWS credits Receive AWS platform credits worth **2%** of the total contract value for new business and **1%** for renewals, applied directly to your AWS bill. These credits are made available through Superblocks' standing in the AWS Marketplace Private Offer Promotion Program (MPOPP), and are applied in addition to any PPA discounts or existing AWS commitments you already have in place. ### 100% drawdown on AWS commitment Purchasing Superblocks through AWS Marketplace gives you two distinct financial benefits: **100%** of your Superblocks spend, dollar-for-dollar, counts toward your Private Pricing Agreement (PPA) drawdown (up to your negotiated Marketplace retirement allowance), and the underlying infrastructure Superblocks runs on (compute, database, inference, storage) continues to receive your existing PPA discounts and counts **100%** toward your AWS consumption commitment. ### Accelerate budget approval from your CFO Skip duplicate vendor onboarding and a second procurement cycle. Once commercial terms are finalized, Superblocks issues a Private Offer through AWS Marketplace for **one-click approval** by your authorized AWS account administrator — no separate MSA or invoicing process required. # Superblocks Database Source: https://docs.superblocks.com/admin/superblocks-on-aws/database Give every app its own managed AWS Aurora PostgreSQL database on your infrastructure with automatic schema migrations on deploy ## Overview Nearly every app built with AI needs a database. The moment a builder asks Clark to "track requests," "store approvals," or "save user preferences," that app needs persistent storage. Without a native database, this creates a problem: either IT provisions and manages databases manually for every app — which does not scale when hundreds of builders are vibe coding — or builders are forced to use external storage that moves data outside your network, and manage the databases themselves. Superblocks Database solves both problems: * **Every app gets its own Aurora PostgreSQL database automatically.** Builders describe what they need, and Clark provisions an isolated database on your infrastructure. No tickets, no manual setup, no database expertise required. * **Data never leaves your network.** Databases run on **AWS Aurora PostgreSQL** inside your own VPC. Superblocks orchestrates the provisioning but your data stays on your infrastructure. * **Development and production are separated by default.** Builders who have never managed a database do not need to understand environments. Each app gets a separate database per environment, and Superblocks handles schema migrations on deploy. Test data never reaches production. * **You pay for what your apps use.** Databases run on Aurora Serverless v2, which scales compute up and down within the capacity bounds your admins configure. AWS bills for the capacity your apps actually consume, down to a small always-on floor, not the configured maximum. Each app gets its own isolated database, and those databases are hosted on shared Aurora PostgreSQL clusters that your admins size. Pooling many apps onto a cluster is what keeps the cost predictable — the default is 100 apps per cluster, and Superblocks adds another cluster as the pool fills. When a builder asks Clark for any feature that requires persistence, the platform creates that app's database automatically. ## How it works ### 1. Your admins turn it on once Enabling Superblocks Database is an infrastructure change, not a settings toggle, and it comes after your data planes and data tags are in place: each database-enabled data plane serves exact data tags, and those tags cannot be renamed once databases exist. See [Data planes and Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database). Your admins then run a Terraform module in your AWS account to create the IAM roles and the state bucket, add the database configuration to the data plane (as ECS task environment variables or Helm values), and then provision the first Aurora cluster once from the Superblocks admin panel. From then on, the admin panel shows that configuration read-only, because it reflects what the running data plane is actually configured with. Every database operation after that is triggered from your data plane, running code you control. See [Setup](/admin/superblocks-on-aws/database-setup) for the full walkthrough and the exact AWS permissions involved. ### 2. Clark provisions a development Aurora PostgreSQL database When a builder asks Clark to store data — for example, "add a database to track commission rate requests": * Clark tells your data plane to provision a database * Your data plane provisions an isolated development database for that app (via code you control) * Clark proposes the schema (tables, columns, indexes) for the database and runs these migrations through your data plane * Clark wires up the APIs to read and write data The builder never leaves the Superblocks editor. They describe the feature, and Clark handles provisioning and schema design. ### 3. Each environment gets its own database Development and production are separate databases. Superblocks creates one logical database per app and [data tag](/development-lifecycle/build/data-tags), in the [data plane that serves that tag](/enterprise/hybrid-architecture/plan/superblocks-database). This is configurable, see [Setup decisions](/admin/superblocks-on-aws/database-setup#setup-decisions-and-prerequisites). ### 4. Schema migrations run on deploy Clark keeps the schema in the application's own code as `.sql` migration files, so the schema is versioned alongside the app. When a builder publishes, Superblocks automatically: * Creates the production database if it does not already exist * Applies the app's migrations to it, producing the same schema with none of the development data * Blocks the deploy until the production database and its migrations are ready There is no manual migration step. The platform handles the full lifecycle from development through production. ## Set it up > [card] [1. Plan data planes for Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database) > > Decide which data planes serve which data tags before any database exists. > [card] [2. Set up Superblocks Database](/admin/superblocks-on-aws/database-setup) > > Run the Terraform module and provision the first cluster. Evaluating the feature for a security review? [Security model](/admin/superblocks-on-aws/database-security) explains which components talk to which, what crosses each connection, and why the control plane cannot act on your AWS account. # Superblocks Database Reference Source: https://docs.superblocks.com/admin/superblocks-on-aws/database-reference Implementation details behind Superblocks Database: AWS resources, IAM scoping, etc This page is a reference for the full lifecycle of an app database: what exists at each stage, what it is named, and which IAM role is allowed to act on it. For initial setup, start with [Setup](/admin/superblocks-on-aws/database-setup). For what the feature does for builders, see [Superblocks Database](/admin/superblocks-on-aws/database). For the trust boundaries and network paths behind these details, see [Security model](/admin/superblocks-on-aws/database-security). ## One-time setup One-time setup is a single Terraform module, `modules/app-db-prereqs`, recommended for every deployment. It creates IAM roles, policies, and an S3 bucket for storing OpenTofu state. ```hcl theme={null} module "app_db_prereqs" { source = "superblocksteam/superblocks/aws//modules/app-db-prereqs" version = ">= 1.5.3, < 2.0.0" deployment_type = "fargate" # or "eks" region = "" # One entry per data plane. The map key is the agent name. agents = { "" = { agent_tags = [""] vpc_id = "" } } } ``` Run it once per region, declaring every data plane in that region in the same `agents` map so they share one state bucket. For the walkthrough that wires its outputs into Fargate or Helm, see [Setup: Step 1](/admin/superblocks-on-aws/database-setup#step-1-run-the-terraform-module). ### Resources created | Resource | Default name | Purpose | | - | - | - | | Lifecycle worker IAM role, plus seven policies | `sb-app-db--lifecycle-worker-` | To provision and modify only the resources Superblocks tagged, in the VPC you declared. See [Raw IAM policy JSON](#raw-iam-policy-json) | | Connector IAM role, plus its policy | `superblocks-app-db-connector-` | To authenticate at query time as `sbndb___runtime`, assumable only by this data plane's lifecycle worker. See [Connecting](#connecting) | | Enhanced Monitoring IAM role | `sb-app-db-enhanced-monitoring` | To let RDS publish operating-system metrics. The worker may pass this role only, and only to `rds.amazonaws.com` | | S3 state bucket | `sb-app-db--` | To store OpenTofu state at `{key_prefix}/{tag}/{resource_key}.tfstate`, versioned and private. Superblocks reads and writes this bucket in your account; Superblocks does not retain a copy. See [S3 state bucket properties](#s3-state-bucket-properties) | ### Module options | Option | Default | Purpose | | - | - | - | | `agents` | Required | To declare one entry per data plane, keyed by [agent name](#agent-name) | | `deployment_type` | Required | To pick the lifecycle worker trust policy: `fargate` or `eks` | | `existing_monitoring_role_arn` | Module creates the role | To reuse an Enhanced Monitoring role, since IAM role names are account-global and a second region cannot create the same name | | `iam_name_prefix` | `sb-app-db` | To prefix IAM role and policy names, up to 16 characters | | `kms_key_arn` | SSE-S3 | To encrypt state with your own KMS key, and to scope the worker's KMS access to that key alone | | `region` | Required | To set the region these resources are created in | | `s3_name_prefix` | `sb-app-db` | To prefix the state bucket name, up to 16 characters | | `tags` | `{}` | To add inventory tags. `ManagedBy`, `superblocks:owned`, and `aws-apn-id` are reserved and always enforced | ### Per-data-plane options Each entry in the `agents` map takes these options. | Option | Default | Purpose | | - | - | - | | `agent_tags` | Required | To name the [data tags](#data-tag-names) this data plane serves, which derive its database and role names | | `existing_role_name` | Module creates a role | To attach the worker policies to an IAM role you already have: the ECS task role on Fargate, the IRSA role on EKS. Takes the role name, not the ARN. See "Adding to an existing Fargate data plane" under the ECS Fargate tab in [Setup: Step 1](/admin/superblocks-on-aws/database-setup#step-1-run-the-terraform-module) | | `key_prefix` | `app-db/` | To namespace this data plane's state inside the shared bucket, and to scope its S3 permissions. Must not overlap another data plane's prefix | | `namespace` | `superblocks` | To name the data plane's Kubernetes namespace, on EKS | | `oidc_provider_arn` | Required on EKS | To trust the data plane's Kubernetes service account through IRSA | | `rds_secret_kms_key_arn` | AWS-managed key | To encrypt the RDS-managed master secret with your own KMS key | | `service_account_name` | `superblocks-agent` | To name the data plane's Kubernetes service account, on EKS | | `vpc_id` | Required | To scope every IAM policy for this data plane to one [VPC](#vpc) | ### Multiple data planes in one account and region Superblocks recommends one data plane per AWS account and VPC, so most deployments never need this. When you do run more than one in the same account and region, declare them all in one `app_db_prereqs` invocation. They share the state bucket, but not IAM roles or VPCs. ```hcl theme={null} module "app_db_prereqs" { # ...same source, version, deployment_type, and region as a single data plane... agents = { "" = { agent_tags = [""] vpc_id = "" } "" = { agent_tags = [""] vpc_id = "" } } } ``` ### Additional AWS regions Each region needs its own `app_db_prereqs` invocation with an AWS provider alias, and gets its own S3 state bucket. The Enhanced Monitoring role is the exception: IAM role names are account-global, so designate the first region as the role's durable home and pass its ARN to every additional region through `existing_monitoring_role_arn`. ```hcl theme={null} provider "aws" { alias = "secondary" region = "" } module "app_db_prereqs_secondary" { source = "superblocksteam/superblocks/aws//modules/app-db-prereqs" version = ">= 1.5.3, < 2.0.0" providers = { aws = aws.secondary } deployment_type = "" region = "" existing_monitoring_role_arn = module.app_db_prereqs.enhanced_monitoring_role_arn agents = { # Configure the data planes in this region as shown above. } } ``` The example above assumes both regional module calls share one Terraform root and state. If each region uses separate state, pass the owning stack's output through `terraform_remote_state` or supply the concrete ARN (`arn:aws:iam:::role/-enhanced-monitoring`) as `existing_monitoring_role_arn`. The secondary prerequisite stack re-exports the supplied role through its own `enhanced_monitoring_role_arn` output. Use `module.app_db_prereqs_secondary.enhanced_monitoring_role_arn` as `monitoring_role_arn` in that region's Fargate `physical_module_inputs` or EKS `physicalModuleInputs`. The first region's prerequisite stack owns a cross-region dependency. Do not destroy that stack while any other region uses its Enhanced Monitoring role. Do not add `existing_monitoring_role_arn` later to the stack that created the role without first moving every consumer to another role; Terraform would destroy the role that stack currently owns. If that role was deleted or changed accidentally, first check for `-enhanced-monitoring` in IAM. Restore the original owning prerequisite stack and run `terraform apply` to recreate its trust policy and managed-policy attachment. Because the recreated role has the same ARN, existing regional consumers can resume using it. To move ownership deliberately, create a replacement role, update every regional prerequisite stack and physical database input to the replacement ARN, apply those changes, and only then remove the old role. ## Immutable setup inputs There is no automated migration path, so changing any of these values requires manual recovery. ### Agent name This is a unique value represented in the Terraform inputs as `agents = { "" = { ... } }`. The agent name must be passed as an input into Fargate or Helm. The name is used to derive these outputs: * The [IAM role and policy names](#raw-iam-policy-json), one set per data plane * The [`AgentName` tag](#how-everything-is-tagged) that every resource must carry before the lifecycle worker can change it * The [OpenTofu state prefix](#one-time-setup), default `app-db/`, which also scopes the worker's S3 permissions If the names become mismatched for any reason, you will see `AccessDenied` errors. ### Data tag names Database and role names are derived from a hash of the tag: `sbndb__` for the database, `sbndb___runtime` for its role. `` is the first 16 hex characters of `SHA-256(lowercase(tag))`; `` is a 24-hex hash of the application ID. The connector role's permissions are scoped to that pattern, so renaming a tag orphans every existing database and role under the old name. Tag names must be non-empty and unique across all agents in the module invocation. Settle your tags before any database exists; see [Plan your data planes](/enterprise/hybrid-architecture/plan/index). ### VPC Every IAM policy created for a data plane is scoped to its VPC. Changing it means none of the existing roles can act on resources in the new VPC. ### Cluster autoscaling Capacity is configured per data plane. Superblocks recommends the same always-on shape for every data tag, including edit and preview: two instances at 2-32 ACUs each. Choose it when you provision the data plane. After the data plane registers serverless scaling changes (ACU range and instance count), Superblocks automatically queues updates for existing clusters. See [Apply configuration changes to existing clusters](/admin/superblocks-on-aws/database-setup#apply-configuration-changes-to-existing-clusters). | Setting | Recommended value | | - | - | | `instance_count` | `2` | | `min_acu` (per instance) | `2` | | `max_acu` (per instance) | `32` | | Cost while idle | Two instances billed at the ACU floor (4 ACUs aggregate) | | First query after idle | Served immediately | The ACU range defines the bounds Aurora Serverless v2 scales within, not reserved compute. Aurora scales each instance up and down with demand, and AWS bills for the ACUs consumed, never less than the `min_acu` floor and never more than `max_acu`. Omitting the `deployment` block gives you this same shape: the released Aurora module defaults to two instances at 2-32 ACUs each, for an aggregate idle floor of 4 ACUs. Set the block explicitly anyway so the capacity is visible in your configuration. With a nonzero `min_acu`, the cluster never pauses. The default `min_acu` is `2`. Setting it to `0` lets an idle cluster pause, which costs less but adds a cold start to the next connection (not recommended). A cluster that has been paused for about 24 hours can take over a minute to resume. ## Provisioning the cluster pool Your data plane provisions the first Aurora cluster when an admin clicks **Provision**, and adds another whenever remaining pool capacity hits the pool settings from the data plane configuration in [Setup: Step 1](/admin/superblocks-on-aws/database-setup#step-1-run-the-terraform-module) (`max_databases` on Fargate; that cap plus `minAvailableCapacityPercent` on Helm). This usually takes 5 to 15 minutes, depending on AWS latency. It runs `tofu apply` with the configuration it already has, so nothing is re-entered in the admin panel. Each cluster added to the pool arrives with: * **Aurora PostgreSQL cluster and its instances**: named `sb-{hash}`. Physical modules enable IAM database authentication, keep the endpoint private, encrypt storage, and manage the master password in AWS Secrets Manager. The lifecycle worker reads that secret by ref, so there is no plaintext master credential in Superblocks systems. * **CloudWatch log group**: a per-cluster `/aws/rds/cluster//postgresql` group that retains exported PostgreSQL logs for 30 days * **DB cluster parameter group**: carries the logging parameters described under [Observing](#observing) * **DB subnet group**: scoped to the subnets you specified in `physical_module_inputs` * **Security group and its ingress/egress rules**: controls which sources (security groups or CIDRs) can reach the database on port 5432. The security group and each rule are separate AWS resources, and both carry the tags described under [How everything is tagged](#how-everything-is-tagged) App databases themselves are logical databases inside these clusters, each with its own PostgreSQL role. They are not separate AWS resources, so they never show up in the RDS console as their own entries. The lifecycle worker role does the creating, under the tag requirements described under [How everything is tagged](#how-everything-is-tagged). IAM policy conditions require `publicly_accessible = false`, storage encryption, and an AWS Secrets Manager master password, so a modified module cannot opt out of those. IAM database authentication is enabled by the physical modules (`iam_database_authentication_enabled = true`); there is no corresponding IAM condition. See [Raw IAM policy JSON](#raw-iam-policy-json). ### Pool options Lowering `max_databases` spreads apps across more clusters, which shrinks the blast radius of a failover or an engine patch and raises your baseline cost; raising it does the reverse. Fargate takes these under `pool`; Helm takes them under `databaseLifecycle.pool` in lowerCamelCase. | Option | Default | Purpose | | - | - | - | | `max_databases` / `maxDatabases` | `100` | To cap the logical databases one cluster holds before the next app database waits on a new cluster | | `min_available_capacity_percent` / `minAvailableCapacityPercent` | Fargate: not published. Helm: `20` | To enqueue a new cluster when remaining capacity falls to this percent of `max_databases`. Helm only. Set `0` to disable proactive enqueue | ### Physical database options Fargate takes these under `physical_module_inputs`; Helm takes the same keys under `databaseLifecycle.physicalModuleInputs`. New clusters use these settings when they are provisioned. After the data plane registers changes to supported settings, Superblocks automatically queues updates for existing clusters. See [Apply configuration changes to existing clusters](/admin/superblocks-on-aws/database-setup#apply-configuration-changes-to-existing-clusters). | Option | Default | Purpose | | - | - | - | | `allowed_cidr_blocks` | `[]` | To let CIDR ranges reach the database on port 5432. Set this or `source_security_group_ids` | | `backup_retention_period` | `7` | To retain automated backups for 1 to 35 days | | `delete_automated_backups` | `false` | To discard automated backups when a cluster is destroyed | | `deletion_protection` | `true` | To block accidental cluster deletion | | `deployment` | Two instances at 2-32 ACUs each, never pauses | To set Aurora capacity through nested `serverless_v2` or `provisioned`. See [Cluster autoscaling](#cluster-autoscaling) | | `monitoring_interval` | `60` | To set the Enhanced Monitoring interval in seconds, or `0` to turn it off | | `monitoring_role_arn` | None | To pass the shared Enhanced Monitoring role, required unless `monitoring_interval` is `0` | | `skip_final_snapshot` | `false` | To skip the final snapshot when a cluster is destroyed | | `source_security_group_ids` | `[]` | To let security groups reach the database on port 5432. Set this or `allowed_cidr_blocks`. Pass the data plane's group: the root module's `ecs_security_group_id` output on Fargate, the node or pod security group on EKS | | `subnet_ids` | Required | To become the DB subnet group. At least two, spanning at least two Availability Zones | | `tags` | `{}` | To add inventory tags to every provisioned resource. Tags are merged with `superblocks:owned`, `aws-apn-id`, `AgentName`, `ManagedBy`, and `Vpc` | | `vpc_id` | Required | To place clusters in one VPC. Must match this data plane's `agents` entry | `publicly_accessible` is not an option. It is always false, enforced by IAM rather than module default. Additional options `allocated_storage`, `instance_class`, and `multi_az` exist for alternative database configurations within AWS. ## Creating an app database A builder with database creation permission asks Clark for a feature that needs persistent data. Superblocks queues one task to create an isolated logical database on a cluster that already has capacity under your pool settings; if none does, it provisions a new cluster first. Your data plane claims the task, runs `tofu apply` in your AWS account, and reports back when the database is ready. Superblocks only queues the work. Your data plane is the only thing that calls AWS. The result is a PostgreSQL database and a matching role inside an existing cluster, named `sbndb__` and `sbndb___runtime` (see [Data tag names](#data-tag-names) for how the tokens are derived). Each app gets one database per [data tag](/development-lifecycle/build/data-tags) the data plane serves. The lifecycle worker creates both and grants the role `rds_iam`. The connector role stays out of it until the app runs a query. ## Applying schema migrations Clark writes the schema as `.sql` files in the application's own code, so it is versioned alongside the app. Once a database reports ready, Superblocks queues a migration task and your data plane applies those files to that one database. No AWS resources change. Edit-time and deploy-time databases use the same path. ## Connecting > [tab] ECS Fargate > > ```hcl theme={null} > module "app_db" { > # Wired from the prereq module so the two cannot diverge. > agent_tags = module.app_db_prereqs.agents[""].agent_tags > connector_role_arn = module.app_db_prereqs.agents[""].connector_role_arn > } > ``` > [tab] EKS (Helm) > > ```yaml theme={null} > superblocks: > # Comma-separated, each data tag prefixed with profile:. > agentTags: profile: > > postgres: > appDbConnectorRoleArn: "" > > iamAllowedRoleArnPrefixes: > - "" > ``` When an app runs a query, the data plane authenticates with the connector role. Neither that role's ARN nor the lifecycle worker's identity appears inside PostgreSQL: the database only ever sees a PostgreSQL role name and an auth token, and IAM decides whether that token is valid. The sequence for a single query is: 1. **Provisioning** creates the app's PostgreSQL role (`sbndb___runtime`) and grants it `rds_iam`. That grant makes PostgreSQL delegate authentication for this role to IAM instead of checking a stored password. No password is ever generated for it. 2. **The data plane checks the target** against the connector role ARNs in its own configuration, and refuses the connection if they disagree. 3. **The data plane assumes the connector role**, attaching an inline session policy that allows exactly one action on exactly one resource: `rds-db:connect` on this cluster, as this one PostgreSQL role. 4. **It signs an RDS IAM auth token** for that PostgreSQL role with those session credentials, and connects using the token as the password, over TLS with full certificate and hostname verification. The effective permission on any given connection is the intersection of two policies. The connector role's own policy bounds it to `sbndb__*_runtime` users for the declared data tags (see [Raw IAM policy JSON](#raw-iam-policy-json)), and the per-connection session policy narrows that to the single user for the single app being served. One app's credentials cannot reach another app's database, even though both use the same connector role. ## Deploying When a builder publishes an app, the deploy-time [data tag](/development-lifecycle/build/data-tags) gets its own database. If the app does not have one there yet, Superblocks queues a create task and then a migration task, producing the same database and role as at edit time under a different tag. The deploy does not proceed until both finish. No data is copied. The deploy-time database gets the schema and none of the development rows. ## Observing > [tab] ECS Fargate > > ```hcl theme={null} > module "app_db" { > physical_module_inputs = { > # Enhanced Monitoring. Set the interval to 0 and omit the role to opt out. > monitoring_interval = 60 > monitoring_role_arn = module.app_db_prereqs.enhanced_monitoring_role_arn > } > } > ``` > [tab] EKS (Helm) > > ```yaml theme={null} > databaseLifecycle: > physicalModuleInputs: > # Enhanced Monitoring. Set the interval to 0 and omit the role to opt out. > monitoring_interval: 60 > monitoring_role_arn: "" > > # Helm only, both on by default. Fargate cannot disable them as of v1.5.2. > # enabled_cloudwatch_logs_exports: [] > # performance_insights_enabled: false > ``` The default configuration provides the following signals in your AWS account: * Standard RDS CloudWatch metrics * Enhanced Monitoring at 60-second resolution through the account- and region-level `RDSOSMetrics` CloudWatch Logs group, with one log stream per database instance. Its retention is independent of the per-cluster PostgreSQL log group's 30-day setting * Database Insights Standard, with Performance Insights retained for 7 days * PostgreSQL logs exported to CloudWatch Logs with 30-day retention * PostgreSQL diagnostic logs for lock waits and deadlocks, temporary files larger than 64 MiB, checkpoints, and autovacuum operations running at least 5 seconds * Slow-query logging for every statement running at least 5 seconds and a 10% sample of statements running between 1 and 5 seconds. Statements under 1 second are not duration-logged. Bound parameter values are excluded, although the parameterized statement text is retained * `pg_stat_statements` tracking for top-level statements. Its storage is bounded and shared across the cluster, so older or less-used entries can be evicted; the module does not fix a universal entry limit Settings declared in the physical module inputs or supplied by its defaults, including log retention and PostgreSQL parameters, are managed through OpenTofu, so a later lifecycle apply can revert manual console changes. Superblocks does not ingest these signals or monitor your databases on your behalf. ### How everything is tagged Every App Database AWS resource carries two kinds of tags. **IAM scoping tags** (required for the lifecycle worker to mutate the resource): * `AgentName={agents-map-key}`, the [agent name](/admin/superblocks-on-aws/database-reference#agent-name) for this data plane (Terraform `agents` map key, Fargate `agent_name`, or Helm `superblocks.agentName`) * `ManagedBy=superblocks-app-database-lifecycle` * `Vpc={your-vpc-id}` The IAM policies only allow create/modify/delete on resources carrying all three. The worker stamps `AgentName` itself; physical modules merge `ManagedBy`; `Vpc` comes from your networking inputs. **Ownership and partnership tags** (required on every Superblocks-created resource, including runtime Aurora): * `superblocks:owned=true` * `aws-apn-id=pc:ctelqp437y3cvjkv5rv0z2w4f` These do **not** change who pays the bill or which AWS account owns the resources, which remains your account. `aws-apn-id` is identical in every deployment rather than per-account. `app-db-prereqs` enforces both keys on setup resources. The physical OpenTofu modules stamp them on runtime Aurora, RDS, subnet groups, and security groups, overwriting conflicting caller values. The Fargate `app-db` module also merges the same pair into runtime module inputs. On EKS, `databaseLifecycle.physicalModuleTags` is for optional inventory tags only (cost center, team, and similar). Do not set `ManagedBy`, `AgentName`, `Vpc`, `superblocks:owned`, or `aws-apn-id` there. The lifecycle worker IAM policy also denies removing any of the five keys above (`AgentName`, `ManagedBy`, `Vpc`, `superblocks:owned`, and `aws-apn-id`), including via named Deny Sids (`DenyRemoveProtectedTags` / `DenyDeleteProtectedTags` / `DenyUntagProtectedTags`) so AccessDenied is attributable. EC2 `DenyDeleteProtectedTags` is further scoped with `AgentName` / `ManagedBy` / `Vpc` ResourceTags so attaching policies via `existing_role_name` cannot Deny `DeleteTags` on unrelated security groups. A Resource Group or the CLI lists everything the feature manages: ```bash theme={null} aws resourcegroupstaggingapi get-resources \ --tag-filters Key=ManagedBy,Values=superblocks-app-database-lifecycle # Or filter on ownership: aws resourcegroupstaggingapi get-resources \ --tag-filters Key=superblocks:owned,Values=true ``` ## S3 state bucket properties The Terraform module creates the state bucket, so these properties only matter if your organization creates it by hand instead. > [accordion] Required S3 state bucket properties > > | Property | Required value | Notes | > | - | - | - | > | Versioning | Enabled | Required for state recovery | > | Block public access | All four settings enabled | `block_public_acls`, `block_public_policy`, `ignore_public_acls`, `restrict_public_buckets` | > | Server-side encryption | SSE-S3 (default) or SSE-KMS | SSE-S3 uses AWS-managed keys and incurs no KMS charges. SSE-KMS only when `kms_key_arn` is provided; use the same key ARN supplied to the module | > | S3 bucket key | Disabled | The module sets `bucket_key_enabled = false`. This is separate from `kms_key_arn`; you can use SSE-KMS with a customer-managed key and still have bucket keys off. | > | Non-current version expiration | 90 days | Keeps state recoverable without unbounded storage growth | > | Abort incomplete multipart uploads | 7 days | | > | Bucket policy | None | Access is controlled via the IAM policies in [Raw IAM policy JSON](#raw-iam-policy-json); no explicit bucket policy is required | ## Raw IAM policy JSON The Terraform module creates the following IAM resources per data plane. If your organization requires policies to be pre-approved or manually provisioned before Terraform can attach them, use the JSON below. `iam_name_prefix` prefixes the IAM role and policy names below, and `s3_name_prefix` prefixes the state bucket name. Both default to `sb-app-db`. Placeholders to substitute before use: | Placeholder | Example value | Description | | - | - | - | | `` | `us-east-1` | AWS region | | `` | `123456789012` | 12-digit AWS account ID | | `` | `vpc-0123456789abcdef0` | VPC ID declared for this data plane | | ``, ``, … | `subnet-0123456789abcdef0` | Private subnet IDs for the Aurora subnet group | | `` | `sg-0123456789abcdef0` | The data plane's security group, allowed to reach Aurora on port 5432 | | `` | `sb-app-db-us-east-1-123456789012` | S3 state bucket name | | `` | `app-db/` | OpenTofu state prefix IAM-scoped to this data plane. Equals `module.app_db_prereqs.agents[""].key_prefix` (override via `agents[].key_prefix`). See [Agent name](/admin/superblocks-on-aws/database-reference#agent-name). | | `` | No default (max 15 characters, lowercase alphanumeric, unique per AWS account) | [Agent name](/admin/superblocks-on-aws/database-reference#agent-name) for this data plane. Used in IAM role and policy names. | | `` | `arn:aws:iam::123456789012:role/sb-app-db--lifecycle-worker-` | ARN of the lifecycle worker role | | `` | `arn:aws:iam::123456789012:role/superblocks-app-db-connector-` | ARN of the connector role (fixed `superblocks-app-db-connector-` name; not affected by `iam_name_prefix`) | | `` | `arn:aws:iam::123456789012:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE` | EKS OIDC provider ARN (EKS only) | | `` | `oidc.eks.us-east-1.amazonaws.com/id/EXAMPLE` | OIDC URL (the ARN above with `arn:aws:iam:::oidc-provider/` stripped) | | `` | `arn:aws:iam::123456789012:role/sb-app-db-enhanced-monitoring` | ARN of the shared Enhanced Monitoring role | | `` | `arn:aws:kms:us-east-1:123456789012:key/mrk-example` | Customer-managed KMS key ARN. Used only when `kms_key_arn` is set on `app-db-prereqs` (SSE-KMS). Omit `StateBucketKms` entirely for the SSE-S3 default. | When creating these manually, create the lifecycle worker role first (it has no dependencies), then the connector role (its trust policy references the lifecycle worker role ARN), then create and attach all policies. > [accordion] Lifecycle worker role: trust policy (ECS Fargate) > > Allows the ECS task service principal to assume the role. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Effect": "Allow", > "Action": "sts:AssumeRole", > "Principal": { > "Service": "ecs-tasks.amazonaws.com" > } > } > ] > } > ``` > [accordion] Lifecycle worker role: trust policy (EKS with IRSA) > > Allows the data plane pod's service account to assume the role via OIDC web identity. `` is the OIDC provider URL without the ARN prefix (everything after `oidc-provider/`). The `sub` condition scopes trust to the specific Kubernetes service account. Adjust `namespace` and `service_account_name` if you deviate from the Superblocks defaults. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Effect": "Allow", > "Action": "sts:AssumeRoleWithWebIdentity", > "Principal": { > "Federated": "" > }, > "Condition": { > "StringEquals": { > ":aud": "sts.amazonaws.com" > }, > "StringLike": { > ":sub": "system:serviceaccount:superblocks:superblocks-agent" > } > } > } > ] > } > ``` > [accordion] Policy 1: Assume connector (sb-app-db-\-assume-connector) > > Allows the lifecycle worker to assume its connector role for RDS IAM authentication. Attached to the lifecycle worker role. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "AssumeAppDatabaseConnector", > "Effect": "Allow", > "Action": "sts:AssumeRole", > "Resource": [""] > } > ] > } > ``` > [accordion] Policy 2: State backend (sb-app-db-\-state-bucket-\) > > Allows the lifecycle worker to read and write OpenTofu state in the shared S3 bucket under that agent's `key_prefix` only (default `app-db/`; override via `agents[""].key_prefix`). Replace `` with the same string you wire into the data plane (see [Agent name](/admin/superblocks-on-aws/database-reference#agent-name)). > > `GetBucketLocation` / `GetBucketVersioning` live in a separate statement from `ListBucket` because those metadata APIs do not send `s3:prefix` and would fail closed if they shared the list condition. > > The default bucket uses SSE-S3. The released module emits **no** `StateBucketKms` statement in that case. Do not add a `Resource: "*"` KMS grant to match older examples; that widens decrypt for brownfield roles that already have broader S3 permissions. > > `StateBucketKms` is present only when you set `kms_key_arn` (SSE-KMS). It names that key ARN and has no `CalledVia` condition: > > ```json theme={null} > { > "Sid": "StateBucketKms", > "Effect": "Allow", > "Action": [ > "kms:Decrypt", > "kms:DescribeKey", > "kms:Encrypt", > "kms:GenerateDataKey", > "kms:ReEncryptFrom", > "kms:ReEncryptTo" > ], > "Resource": "" > } > ``` > > The default SSE-S3 policy is the three S3 statements below. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "StateBucketMetadata", > "Effect": "Allow", > "Action": [ > "s3:GetBucketLocation", > "s3:GetBucketVersioning" > ], > "Resource": "arn:aws:s3:::" > }, > { > "Sid": "StateBucketList", > "Effect": "Allow", > "Action": [ > "s3:ListBucket" > ], > "Resource": "arn:aws:s3:::", > "Condition": { > "StringLike": { > "s3:prefix": [ > "/", > "/*" > ] > } > } > }, > { > "Sid": "StateBucketObjectReadWrite", > "Effect": "Allow", > "Action": [ > "s3:AbortMultipartUpload", > "s3:DeleteObject", > "s3:GetObject", > "s3:GetObjectVersion", > "s3:PutObject" > ], > "Resource": "arn:aws:s3::://*" > } > ] > } > ``` > [accordion] Policy 3: RDS provisioning (sb-app-db-\-rds-provisioning-\) > > Allows the lifecycle worker to describe RDS and Aurora resources globally (required by AWS, because describe APIs do not support resource-level restrictions) and to create new RDS and Aurora resources scoped to the `sb-*` namespace and the declared VPC. All create actions enforce tagging at request time, `publicly_accessible = false`, and `manage_master_user_password = true`. The `RdsCreateDbInstance` and `RdsCreateAuroraClusterInstance` statements both cover `rds:CreateDBInstance` but are cleanly discriminated: standalone RDS creates pass `rds:ManageMasterUserPassword = true` and Aurora member creates do not, so each request matches exactly one statement. `iam:CreateServiceLinkedRole` is scoped to `rds.amazonaws.com`; it runs once, and only if your account does not already have the RDS service-linked role. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "RdsDescribe", > "Effect": "Allow", > "Action": [ > "rds:DescribeDBClusterParameterGroups", > "rds:DescribeDBClusterParameters", > "rds:DescribeDBClusterSnapshots", > "rds:DescribeDBClusters", > "rds:DescribeDBEngineVersions", > "rds:DescribeDBInstances", > "rds:DescribeDBParameterGroups", > "rds:DescribeDBParameters", > "rds:DescribeDBSnapshots", > "rds:DescribeDBSubnetGroups", > "rds:DescribeGlobalClusters", > "rds:DescribePendingMaintenanceActions", > "rds:ListTagsForResource" > ], > "Resource": "*" > }, > { > "Sid": "CreateRdsServiceLinkedRole", > "Effect": "Allow", > "Action": "iam:CreateServiceLinkedRole", > "Resource": "*", > "Condition": { > "StringEquals": { > "iam:AWSServiceName": "rds.amazonaws.com" > } > } > }, > { > "Sid": "RdsCreateDbInstance", > "Effect": "Allow", > "Action": "rds:CreateDBInstance", > "Resource": [ > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::subgrp:sb-*", > "arn:aws:rds:::pg:*" > ], > "Condition": { > "Bool": { > "rds:ManageMasterUserPassword": "true", > "rds:PubliclyAccessible": "false", > "rds:StorageEncrypted": "true" > }, > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "rds:DatabaseEngine": "postgres" > } > } > }, > { > "Sid": "RdsCreateAuroraCluster", > "Effect": "Allow", > "Action": "rds:CreateDBCluster", > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::cluster-pg:*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "Bool": { > "rds:ManageMasterUserPassword": "true", > "rds:StorageEncrypted": "true" > }, > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "rds:DatabaseEngine": "aurora-postgresql" > } > } > }, > { > "Sid": "RdsCreateAuroraClusterInstance", > "Effect": "Allow", > "Action": "rds:CreateDBInstance", > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::pg:*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "Bool": { > "rds:PubliclyAccessible": "false" > }, > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "rds:DatabaseEngine": "aurora-postgresql" > } > } > }, > { > "Sid": "RdsCreateParameterGroups", > "Effect": "Allow", > "Action": [ > "rds:CreateDBClusterParameterGroup", > "rds:CreateDBParameterGroup" > ], > "Resource": [ > "arn:aws:rds:::cluster-pg:sb-*", > "arn:aws:rds:::pg:sb-*" > ], > "Condition": { > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "RdsCreateDbSubnetGroup", > "Effect": "Allow", > "Action": "rds:CreateDBSubnetGroup", > "Resource": "arn:aws:rds:::subgrp:sb-*", > "Condition": { > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "RdsTagOnCreate", > "Effect": "Allow", > "Action": "rds:AddTagsToResource", > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::cluster-pg:sb-*", > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::pg:sb-*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > }, > "StringEqualsIfExists": { > "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f", > "aws:RequestTag/superblocks:owned": "true" > } > } > }, > { > "Sid": "RdsTagAppSnapshotOnCreate", > "Effect": "Allow", > "Action": "rds:AddTagsToResource", > "Resource": [ > "arn:aws:rds:::cluster-snapshot:sb-*", > "arn:aws:rds:::snapshot:sb-*" > ], > "Condition": { > "StringEqualsIfExists": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f", > "aws:RequestTag/superblocks:owned": "true" > } > } > }, > { > "Sid": "RdsEncryptedStorageKmsViaRds", > "Effect": "Allow", > "Action": [ > "kms:CreateGrant", > "kms:Decrypt", > "kms:DescribeKey", > "kms:GenerateDataKey" > ], > "Resource": "*", > "Condition": { > "ForAnyValue:StringEquals": { > "aws:CalledVia": "rds.amazonaws.com" > } > } > } > ] > } > ``` > [accordion] Policy 4: RDS mutation (sb-app-db-\-rds-mutation-\) > > Allows the lifecycle worker to modify, delete, snapshot, and retag RDS and Aurora resources it created. The target must already carry the `AgentName`, `ManagedBy`, and `Vpc` tags, so the lifecycle worker cannot modify any RDS resource it did not create. `RdsRemoveTagsExceptProtectedTags` only Allows removing non-protected tags. `DenyRemoveProtectedTags` is an explicit Deny that blocks removing `AgentName`, `ManagedBy`, `Vpc`, `superblocks:owned`, or `aws-apn-id`, so AccessDenied is attributable to that Sid. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "RdsMutate", > "Effect": "Allow", > "Action": [ > "rds:DeleteDBCluster", > "rds:DeleteDBClusterParameterGroup", > "rds:DeleteDBInstance", > "rds:DeleteDBParameterGroup", > "rds:DeleteDBSubnetGroup", > "rds:ModifyDBCluster", > "rds:ModifyDBClusterParameterGroup", > "rds:ModifyDBInstance", > "rds:ModifyDBParameterGroup", > "rds:ModifyDBSubnetGroup", > "rds:RebootDBCluster", > "rds:RebootDBInstance", > "rds:ResetDBClusterParameterGroup", > "rds:ResetDBParameterGroup" > ], > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::cluster-pg:sb-*", > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::pg:sb-*", > "arn:aws:rds:::pg:*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "BoolIfExists": { > "rds:ManageMasterUserPassword": "true" > }, > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > } > } > }, > { > "Sid": "RdsDeleteAuroraClusterFinalSnapshot", > "Effect": "Allow", > "Action": "rds:DeleteDBCluster", > "Resource": "arn:aws:rds:::cluster-snapshot:sb-*", > "Condition": { > "StringEqualsIfExists": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "RdsCreateSnapshotFromManagedCluster", > "Effect": "Allow", > "Action": "rds:CreateDBClusterSnapshot", > "Resource": "arn:aws:rds:::cluster:sb-*", > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > } > } > }, > { > "Sid": "RdsCreateAppClusterSnapshot", > "Effect": "Allow", > "Action": "rds:CreateDBClusterSnapshot", > "Resource": "arn:aws:rds:::cluster-snapshot:sb-*", > "Condition": { > "StringEqualsIfExists": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "RdsCreateSnapshotFromManagedInstance", > "Effect": "Allow", > "Action": "rds:CreateDBSnapshot", > "Resource": "arn:aws:rds:::db:sb-*", > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > } > } > }, > { > "Sid": "RdsCreateAppSnapshot", > "Effect": "Allow", > "Action": "rds:CreateDBSnapshot", > "Resource": "arn:aws:rds:::snapshot:sb-*", > "Condition": { > "StringEqualsIfExists": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "RdsAddTagsToManagedResources", > "Effect": "Allow", > "Action": "rds:AddTagsToResource", > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::cluster-pg:sb-*", > "arn:aws:rds:::cluster-snapshot:sb-*", > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::pg:sb-*", > "arn:aws:rds:::pg:*", > "arn:aws:rds:::snapshot:sb-*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > }, > "StringEqualsIfExists": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f", > "aws:RequestTag/superblocks:owned": "true" > } > } > }, > { > "Sid": "RdsRemoveTagsExceptProtectedTags", > "Effect": "Allow", > "Action": "rds:RemoveTagsFromResource", > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::cluster-pg:sb-*", > "arn:aws:rds:::cluster-snapshot:sb-*", > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::pg:sb-*", > "arn:aws:rds:::pg:*", > "arn:aws:rds:::snapshot:sb-*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > }, > "ForAllValues:StringNotEquals": { > "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"] > } > } > }, > { > "Sid": "DenyRemoveProtectedTags", > "Effect": "Deny", > "Action": "rds:RemoveTagsFromResource", > "Resource": [ > "arn:aws:rds:::cluster:sb-*", > "arn:aws:rds:::cluster-pg:sb-*", > "arn:aws:rds:::cluster-snapshot:sb-*", > "arn:aws:rds:::db:sb-*", > "arn:aws:rds:::pg:sb-*", > "arn:aws:rds:::pg:*", > "arn:aws:rds:::snapshot:sb-*", > "arn:aws:rds:::subgrp:sb-*" > ], > "Condition": { > "ForAnyValue:StringEquals": { > "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"] > } > } > } > ] > } > ``` > [accordion] Policy 5: EC2 networking (sb-app-db-\-ec2-provisioning-\) > > Allows the lifecycle worker to describe VPC and subnet topology (globally, as required by AWS) and to create and manage security groups scoped to the declared VPC. The `Ec2CreateSecurityGroupVpcScope` statement additionally restricts `CreateSecurityGroup` to the specific VPC resource via `ec2:VpcID`, so the lifecycle worker cannot create security groups in any other VPC. `Ec2CreateTagsOnCreateSecurityGroup` authorizes create-time tagging for `CreateSecurityGroup` and for `AuthorizeSecurityGroupIngress` / `AuthorizeSecurityGroupEgress`, so ownership tags can land on both the security group and its individual rules when they are created. `Ec2DeleteTagsExceptProtectedTags` only Allows removing non-protected tags from managed security groups and rules when `aws:TagKeys` is present; `DenyDeleteProtectedTags` Denies removing the scoping and ownership keys; `DenyDeleteTagsWhenTagKeysAbsent` Denies the delete-all request that omits `Tags` / `aws:TagKeys`. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "Ec2VpcDescribe", > "Effect": "Allow", > "Action": [ > "ec2:DescribeAccountAttributes", > "ec2:DescribeAvailabilityZones", > "ec2:DescribeNetworkInterfaces", > "ec2:DescribeRouteTables", > "ec2:DescribeSecurityGroupRules", > "ec2:DescribeSecurityGroups", > "ec2:DescribeSubnets", > "ec2:DescribeTags", > "ec2:DescribeVpcAttribute", > "ec2:DescribeVpcs" > ], > "Resource": "*" > }, > { > "Sid": "Ec2CreateSecurityGroupResource", > "Effect": "Allow", > "Action": ["ec2:CreateSecurityGroup"], > "Resource": "arn:aws:ec2:::security-group/*", > "Condition": { > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "Ec2CreateSecurityGroupVpcScope", > "Effect": "Allow", > "Action": ["ec2:CreateSecurityGroup"], > "Resource": "arn:aws:ec2:::vpc/", > "Condition": { > "StringEquals": { > "ec2:VpcID": "" > } > } > }, > { > "Sid": "Ec2SecurityGroupMutate", > "Effect": "Allow", > "Action": [ > "ec2:AuthorizeSecurityGroupEgress", > "ec2:AuthorizeSecurityGroupIngress", > "ec2:DeleteSecurityGroup", > "ec2:ModifySecurityGroupRules", > "ec2:RevokeSecurityGroupEgress", > "ec2:RevokeSecurityGroupIngress" > ], > "Resource": "*", > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > } > } > }, > { > "Sid": "Ec2CreateTagsOnCreateSecurityGroup", > "Effect": "Allow", > "Action": ["ec2:CreateTags"], > "Resource": [ > "arn:aws:ec2:::security-group/*", > "arn:aws:ec2:::security-group-rule/*" > ], > "Condition": { > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "ec2:CreateAction": [ > "AuthorizeSecurityGroupEgress", > "AuthorizeSecurityGroupIngress", > "CreateSecurityGroup" > ] > }, > "StringEqualsIfExists": { > "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f", > "aws:RequestTag/superblocks:owned": "true" > } > } > }, > { > "Sid": "Ec2CreateTagsOnManagedResources", > "Effect": "Allow", > "Action": ["ec2:CreateTags"], > "Resource": [ > "arn:aws:ec2:::security-group/*", > "arn:aws:ec2:::security-group-rule/*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > }, > "StringEqualsIfExists": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "", > "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f", > "aws:RequestTag/superblocks:owned": "true" > } > } > }, > { > "Sid": "Ec2DeleteTagsExceptProtectedTags", > "Effect": "Allow", > "Action": ["ec2:DeleteTags"], > "Resource": [ > "arn:aws:ec2:::security-group/*", > "arn:aws:ec2:::security-group-rule/*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > }, > "Null": { > "aws:TagKeys": "false" > }, > "ForAllValues:StringNotEquals": { > "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"] > } > } > }, > { > "Sid": "DenyDeleteProtectedTags", > "Effect": "Deny", > "Action": ["ec2:DeleteTags"], > "Resource": [ > "arn:aws:ec2:::security-group/*", > "arn:aws:ec2:::security-group-rule/*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > }, > "ForAnyValue:StringEquals": { > "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"] > } > } > }, > { > "Sid": "DenyDeleteTagsWhenTagKeysAbsent", > "Effect": "Deny", > "Action": ["ec2:DeleteTags"], > "Resource": [ > "arn:aws:ec2:::security-group/*", > "arn:aws:ec2:::security-group-rule/*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > }, > "Null": { > "aws:TagKeys": "true" > } > } > } > ] > } > ``` > [accordion] Policy 6: Secrets Manager (sb-app-db-\-secrets-\) > > Allows the lifecycle worker to read RDS-managed master secrets for databases it owns. Secret creation is only permitted via `aws:CalledVia: rds.amazonaws.com`, so the lifecycle worker cannot directly create Secrets Manager secrets; only RDS can, on its behalf. The worker reads these secrets by ref when provisioning logical databases, so there is no plaintext master credential in Superblocks systems. > > The last statement (`DecryptRdsManagedSecretKmsKey`) handles KMS decryption for the RDS-managed master secret. **Without a customer KMS key** (`rds_secret_kms_key_arn` not set), `Resource` is `"*"` and access is constrained via `kms:ViaService` and `kms:EncryptionContext` as shown below. **With a customer KMS key**, replace `"Resource": "*"` with the specific key ARN. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "CreateRdsManagedMasterSecrets", > "Effect": "Allow", > "Action": "secretsmanager:CreateSecret", > "Resource": [ > "arn:aws:secretsmanager:::secret:rds!cluster-*", > "arn:aws:secretsmanager:::secret:rds!db-*" > ], > "Condition": { > "ForAnyValue:StringEquals": { > "aws:CalledVia": "rds.amazonaws.com" > }, > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "TagRdsManagedMasterSecretsViaRds", > "Effect": "Allow", > "Action": "secretsmanager:TagResource", > "Resource": [ > "arn:aws:secretsmanager:::secret:rds!cluster-*", > "arn:aws:secretsmanager:::secret:rds!db-*" > ], > "Condition": { > "ForAnyValue:StringEquals": { > "aws:CalledVia": "rds.amazonaws.com" > }, > "StringEquals": { > "aws:RequestTag/AgentName": "", > "aws:RequestTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:RequestTag/Vpc": "" > } > } > }, > { > "Sid": "DescribeRdsManagedSecretKmsKeyViaRds", > "Effect": "Allow", > "Action": "kms:DescribeKey", > "Resource": "*", > "Condition": { > "ForAnyValue:StringEquals": { > "aws:CalledVia": "rds.amazonaws.com" > } > } > }, > { > "Sid": "ReadTaggedRdsManagedMasterSecrets", > "Effect": "Allow", > "Action": [ > "secretsmanager:DescribeSecret", > "secretsmanager:GetSecretValue" > ], > "Resource": [ > "arn:aws:secretsmanager:::secret:rds!cluster-*", > "arn:aws:secretsmanager:::secret:rds!db-*" > ], > "Condition": { > "StringEquals": { > "aws:ResourceTag/AgentName": "", > "aws:ResourceTag/ManagedBy": "superblocks-app-database-lifecycle", > "aws:ResourceTag/Vpc": "" > } > } > }, > { > "Sid": "DecryptRdsManagedSecretKmsKey", > "Effect": "Allow", > "Action": [ > "kms:Decrypt", > "kms:DescribeKey" > ], > "Resource": "*", > "Condition": { > "StringEquals": { > "kms:ViaService": "secretsmanager..amazonaws.com" > }, > "StringLike": { > "kms:EncryptionContext:SecretARN": [ > "arn:aws:secretsmanager:::secret:rds!cluster-*", > "arn:aws:secretsmanager:::secret:rds!db-*" > ] > } > } > } > ] > } > ``` > [accordion] Connector role: trust policy > > Allows only the lifecycle worker role for this data plane to assume the connector role. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "AllowOnlyTrustedOpa", > "Effect": "Allow", > "Action": "sts:AssumeRole", > "Principal": { > "AWS": [""] > } > } > ] > } > ``` > [accordion] Connector role: policy (superblocks-app-db-connector-\) > > Grants `rds-db:connect` for each declared data tag, scoped to DB users matching `sbndb__*_runtime` on both RDS instances and Aurora clusters. `` is the first 16 hex characters of `SHA-256(lowercase(tag))`, which you can compute with `printf '%s' '' | shasum -a 256 | cut -c1-16`. Add or remove statements to match your declared `agent_tags`. The example below shows two data tags (`` and ``). > > This is the outer bound, not the effective permission on a connection. See [Connecting](#connecting). > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "ConnectTag1", > "Effect": "Allow", > "Action": "rds-db:connect", > "Resource": [ > "arn:aws:rds-db:::dbuser:cluster-*/sbndb__*_runtime", > "arn:aws:rds-db:::dbuser:db-*/sbndb__*_runtime" > ] > }, > { > "Sid": "ConnectTag2", > "Effect": "Allow", > "Action": "rds-db:connect", > "Resource": [ > "arn:aws:rds-db:::dbuser:cluster-*/sbndb__*_runtime", > "arn:aws:rds-db:::dbuser:db-*/sbndb__*_runtime" > ] > } > ] > } > ``` > [accordion] Policy 7: Observability (sb-app-db-\-observability-\) > > Allows the lifecycle worker to manage CloudWatch log groups for Aurora clusters and instances it provisions, and to pass the shared Enhanced Monitoring role to RDS. > > `logs:DescribeLogGroups` must be scoped to `"Resource": "*"` because AWS does not support resource-level restrictions on describe log group APIs. > > `logs:UntagResource` is split into an Allow that excludes protected keys (`CloudWatchUntagExceptProtectedTags`) and an explicit Deny (`DenyUntagProtectedTags`), matching the RDS/EC2 protected-tag pattern. `logs:TagResource` is similarly split (`CloudWatchTagResourceWithCanonicalOwnership`) so ownership request-tag values cannot be overwritten. > > `iam:PassRole` is conditioned on `iam:PassedToService: rds.amazonaws.com`, which is the service principal that RDS uses when calling `CreateDBInstance`. It is not `monitoring.rds.amazonaws.com`, which is what the monitoring agent assumes later. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "CloudWatchLogGroupsForAppDatabases", > "Effect": "Allow", > "Action": [ > "logs:CreateLogGroup", > "logs:DeleteLogGroup", > "logs:ListTagsForResource", > "logs:PutRetentionPolicy" > ], > "Resource": [ > "arn:aws:logs:::log-group:/aws/rds/cluster/sb-*", > "arn:aws:logs:::log-group:/aws/rds/instance/sb-*" > ] > }, > { > "Sid": "CloudWatchTagResourceWithCanonicalOwnership", > "Effect": "Allow", > "Action": "logs:TagResource", > "Resource": [ > "arn:aws:logs:::log-group:/aws/rds/cluster/sb-*", > "arn:aws:logs:::log-group:/aws/rds/instance/sb-*" > ], > "Condition": { > "StringEqualsIfExists": { > "aws:RequestTag/aws-apn-id": "pc:ctelqp437y3cvjkv5rv0z2w4f", > "aws:RequestTag/superblocks:owned": "true" > } > } > }, > { > "Sid": "CloudWatchUntagExceptProtectedTags", > "Effect": "Allow", > "Action": "logs:UntagResource", > "Resource": [ > "arn:aws:logs:::log-group:/aws/rds/cluster/sb-*", > "arn:aws:logs:::log-group:/aws/rds/instance/sb-*" > ], > "Condition": { > "ForAllValues:StringNotEquals": { > "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"] > } > } > }, > { > "Sid": "DenyUntagProtectedTags", > "Effect": "Deny", > "Action": "logs:UntagResource", > "Resource": [ > "arn:aws:logs:::log-group:/aws/rds/cluster/sb-*", > "arn:aws:logs:::log-group:/aws/rds/instance/sb-*" > ], > "Condition": { > "ForAnyValue:StringEquals": { > "aws:TagKeys": ["AgentName", "ManagedBy", "Vpc", "aws-apn-id", "superblocks:owned"] > } > } > }, > { > "Sid": "DescribeLogGroupsIsNotResourceScopable", > "Effect": "Allow", > "Action": "logs:DescribeLogGroups", > "Resource": "*" > }, > { > "Sid": "PassEnhancedMonitoringRole", > "Effect": "Allow", > "Action": "iam:PassRole", > "Resource": "", > "Condition": { > "StringEquals": { > "iam:PassedToService": "rds.amazonaws.com" > } > } > } > ] > } > ``` > [accordion] Enhanced Monitoring role: trust and permissions > > `app_db_prereqs` creates one account-level role named `sb-app-db-enhanced-monitoring` (or `-enhanced-monitoring`) with the following trust policy. Additional regional prerequisite stacks reuse this same role through `existing_monitoring_role_arn`. If your organization must create IAM roles out of band, create the role with this policy and pass its ARN as `existing_monitoring_role_arn` to every prerequisite invocation. > > ```json theme={null} > { > "Version": "2012-10-17", > "Statement": [ > { > "Sid": "AllowRdsEnhancedMonitoringForAppDatabases", > "Effect": "Allow", > "Principal": { > "Service": "monitoring.rds.amazonaws.com" > }, > "Action": "sts:AssumeRole", > "Condition": { > "ArnLike": { > "aws:SourceArn": [ > "arn:aws:rds:*::cluster:sb-*", > "arn:aws:rds:*::db:sb-*" > ] > }, > "StringEquals": { > "aws:SourceAccount": "" > } > } > } > ] > } > ``` > > The module attaches the AWS-managed `arn:aws:iam::aws:policy/service-role/AmazonRDSEnhancedMonitoringRole` policy to this role. If you create the role out of band, attach the same policy. The trust policy uses `monitoring.rds.amazonaws.com`, while the lifecycle worker's `iam:PassRole` condition above intentionally uses `rds.amazonaws.com`; these principals serve different parts of the Enhanced Monitoring flow. # Superblocks Database security model Source: https://docs.superblocks.com/admin/superblocks-on-aws/database-security What the security team is granting, what it can and cannot do, and how to verify it before setup This page is for the security reviewer who has to approve [Superblocks Database](/admin/superblocks-on-aws/database) before anyone on your team runs its setup. You are being asked to run a Terraform module that creates IAM roles in your account, and to let a component in your VPC create and modify Aurora infrastructure in response to work that Superblocks queues. The evidence, including the full IAM policy JSON, is on the [Reference](/admin/superblocks-on-aws/database-reference) page; the checklist is under [How to verify](#how-to-verify). ## The short version * **Nothing connects into your network.** Your data plane opens every connection; the control plane never initiates one and is not in any cluster's security group ingress. * **The control plane holds none of the feature's credentials.** It cannot assume either IAM role, has no database credentials, and has no route to a cluster. It retains lifecycle state and connection metadata, never application data or credentials. * **IAM policies you review and own decide which resources can change.** The lifecycle worker role can create, modify, or delete only resources that carry the [tags Superblocks stamps at creation](/admin/superblocks-on-aws/database-reference#how-everything-is-tagged), inside the one VPC you declared, and you can revoke it at any time. * **No application password ever exists.** Applications connect with 15-minute RDS IAM tokens, each limited to one PostgreSQL role on one cluster. * **Clusters cannot be public or unencrypted.** IAM conditions require `publicly_accessible = false`, storage encryption, and an RDS-managed master password on every cluster, so a modified module cannot opt out. ## What runs where In a [Hybrid](/enterprise/hybrid-architecture/overview) deployment the control plane is Superblocks Cloud, outside your account. In [Cloud-Prem](/enterprise/cloud-prem/aws) it runs inside your AWS account under its own identity, operated by Superblocks. The trust boundary is the same in both: the control plane is not a principal in either role's trust policy, is not in any cluster's security group ingress, and never opens a connection to the data plane. > [tab] Hybrid > > ```mermaid theme={null} > flowchart TB > subgraph cp [Superblocks Cloud] > Server["Control plane
Records intent and lifecycle state
Holds none of the feature's credentials"] > end > > subgraph aws [Your AWS account] > subgraph vpc [Data plane VPC, private subnets] > DP["Data plane
Lifecycle worker and query executor"] > Pool[("Aurora PostgreSQL pool
Private, encrypted, IAM authentication")] > end > API["AWS service endpoints
RDS, EC2, and tagging APIs"] > S3["S3 state bucket
OpenTofu state"] > SM["Secrets Manager
Aurora master password"] > end > > cp ~~~ aws > API ~~~ S3 ~~~ SM > DP -- "Outbound HTTPS only
agent key" --> Server > DP -- "TCP 5432, TLS
RDS IAM token" --> Pool > DP -- "tofu plan and apply" --> API > DP -- "Read and write" --> S3 > DP -- "Read during create and retire" --> SM > ``` > [tab] Cloud-Prem > > ```mermaid theme={null} > flowchart TB > subgraph aws [Your AWS account] > subgraph vpc [Data plane VPC, private subnets] > DP["Data plane
Lifecycle worker and query executor"] > Pool[("Aurora PostgreSQL pool
Private, encrypted, IAM authentication")] > end > subgraph cp [Superblocks control plane, operated by Superblocks] > Server["Control plane
Own VPC and own IAM role
Holds none of the feature's credentials"] > end > API["AWS service endpoints
RDS, EC2, and tagging APIs"] > S3["S3 state bucket
OpenTofu state"] > SM["Secrets Manager
Aurora master password"] > end > > Server ~~~ S3 > API ~~~ SM > DP -- "HTTPS, opened by the data plane
agent key" --> Server > DP -- "TCP 5432, TLS
RDS IAM token" --> Pool > DP -- "tofu plan and apply" --> API > DP -- "Read and write" --> S3 > DP -- "Read during create and retire" --> SM > ``` Each arrow points from the component that opens the connection. The data plane uses the lifecycle worker role for every call to AWS APIs, S3, and Secrets Manager, and the connector role to reach a cluster as an application. | Connection | Authentication | What it carries | | - | - | - | | Data plane to control plane, outbound HTTPS from your VPC | Your organization's agent key, the same key every data plane already uses to register | Capability registration, wake-up hints, task claims, task payloads (the operation, the target database, desired settings, and the application's SQL migration files), and outcome reports. Route by route: [Superblocks Database requests](/enterprise/hybrid-architecture/manage/requests#superblocks-database-requests) | | Data plane to AWS, from your VPC: RDS, EC2, and tagging APIs, the S3 state bucket, and Secrets Manager | Lifecycle worker IAM role | `tofu plan` and `tofu apply` calls bounded by [the worker's IAM policy](/admin/superblocks-on-aws/database-reference#raw-iam-policy-json); OpenTofu state for the resources this data plane manages, which Superblocks does not retain; and, during create and retire tasks, a read of the RDS-managed master secret for a cluster the worker created | | Data plane to Aurora as the master user, TCP 5432 with TLS inside your VPC, during create and retire tasks only | The Aurora master password, read from Secrets Manager and held in memory for the task | The allowlisted module's `CREATE DATABASE` and `CREATE ROLE`, and the corresponding drops when a database is retired. This is the only connection with cluster-wide privilege, and every read of the secret is a `GetSecretValue` event in your CloudTrail | | Data plane to Aurora as an application, TCP 5432 with TLS and full certificate and hostname verification inside your VPC | The connector role, assumed with a session policy allowing `rds-db:connect` for exactly one PostgreSQL role on exactly one cluster, then a 15-minute RDS IAM token for that role | Application queries and, when a migration task runs, that application's SQL migration files, both as the application's own PostgreSQL role in its own database | Ingress to a cluster is limited to the security groups and CIDR ranges you pass in `source_security_group_ids` and `allowed_cidr_blocks`, normally your data plane's security group and nothing else. See [Physical database options](/admin/superblocks-on-aws/database-reference#physical-database-options). Each application gets its own PostgreSQL database and its own PostgreSQL role, created with `rds_iam` and no password, so the only way to log in as that role is an RDS IAM token. The connector role's policy allows `rds-db:connect` only for application runtime roles under the data tags you declared, and the per-connection session policy narrows that to the one role and one cluster being served. One application therefore cannot authenticate as another application or as the master user, even though every application on the data plane shares the same connector role. The full sequence is under [Connecting](/admin/superblocks-on-aws/database-reference#connecting). ## What you are asked to grant Setup runs one Terraform module, `app-db-prereqs`, once per region in each account. It creates the four items below and nothing else; the first Aurora cluster is created when an organization admin clicks **Provision**. From then on the worker acts without a human gate: it creates a database whenever a builder needs one, and another cluster whenever remaining pool capacity falls to the [thresholds in your data plane configuration](/admin/superblocks-on-aws/database-reference#pool-options). The number of clusters is bounded by those thresholds and your AWS quotas, not by IAM. | Created by the module | What it is for | What bounds it | | - | - | - | | Lifecycle worker IAM role | The identity your data plane uses to provision Aurora clusters, create per-application databases, and read and write OpenTofu state | Trust policy names only your data plane's ECS task or Kubernetes service account. Every create requires the scoping tags in the request, every modify and delete requires them on the existing resource, and everything is placed in the declared VPC. See [How everything is tagged](/admin/superblocks-on-aws/database-reference#how-everything-is-tagged) and [Raw IAM policy JSON](/admin/superblocks-on-aws/database-reference#raw-iam-policy-json) | | Connector IAM role | The identity applications authenticate with at query time | Trust policy names only the lifecycle worker role. Its one permission is `rds-db:connect`, limited to application runtime roles under the data tags you declared | | Enhanced Monitoring IAM role | Lets RDS publish operating-system metrics | The worker may pass this role only, and only to `rds.amazonaws.com` | | S3 state bucket | Stores OpenTofu state for the resources the worker manages | Private, versioned, encrypted. Each data plane can read and write only its own key prefix. See [S3 state bucket properties](/admin/superblocks-on-aws/database-reference#s3-state-bucket-properties) | What is not granted: * **No cross-account trust.** No trust policy names a Superblocks account, so no Superblocks system outside your account can assume either role. If Superblocks operates your data plane for you (Cloud-Prem with managed data planes), its operators act through the data plane's identity, and every role assumption is in your CloudTrail. * **No IAM administration.** The worker's only IAM permissions are `iam:PassRole` for the monitoring role and `iam:CreateServiceLinkedRole` for the RDS service-linked role. It cannot create roles, attach policies, or change its own permissions. * **No tagging escape hatch.** The tagging permissions are conditioned too, so the worker cannot bring an arbitrary resource of yours into scope by tagging it, and it is explicitly denied removing the scoping tags from anything. The exact conditions are in the [Raw IAM policy JSON](/admin/superblocks-on-aws/database-reference#raw-iam-policy-json). * **No reach outside the VPC.** Every mutating permission is conditioned on the VPC you declared. * **No long-lived credentials.** The worker role is assumed through ECS or IRSA. It can read the RDS-managed master secret for clusters it created, which RDS creates and rotates, but cannot create, write, or export secrets. The agent key it uses toward the control plane grants nothing in AWS. ## How work is dispatched Every change starts as a task the control plane queues and ends with your data plane deciding whether to carry it out. Registering the database capability rides on the same `/api/v1/agents/register` call every data plane already makes; the rest use the [database-lifecycle routes](/enterprise/hybrid-architecture/manage/requests#superblocks-database-requests). ```mermaid theme={null} sequenceDiagram autonumber participant SB as Superblocks control plane participant DP as Data plane in your AWS account participant AWS as AWS APIs and Aurora Note over DP,SB: The data plane opens every connection. Nothing connects in. DP->>SB: Register capability, engine, and capacity (agent key) DP->>SB: Subscribe for wake-ups (server-sent events) SB->>SB: A builder, a publish, or an admin queues a task SB-->>DP: Wake-up hint: work is available for your organization Note right of SB: The hint carries no task payload and no secrets DP->>SB: Claim pending tasks for this data plane (agent key) SB-->>DP: Task: operation, target, desired settings, SQL migration files DP->>DP: tofu plan, then check the plan against allowlists DP->>AWS: tofu apply, CREATE DATABASE, or apply migrations Note right of DP: IAM permits only tagged resources in this VPC DP->>SB: Report the outcome: state and connection metadata ``` The data plane also polls the claim route every 30 seconds, so the server-sent events stream only shortens the wait: if it errors or is unavailable, polling continues. Neither the hint nor the stream carries a task; the task is always fetched through the claim route. A proxy that buffers the stream adds latency, nothing more. ### What bounds a task **Enforced in your account, independent of Superblocks:** * **Direction.** The data plane pulls work over connections it opens. The control plane cannot reach the data plane, call AWS, or connect to a database. * **IAM on the AWS path.** Creates, modifies, and deletes are confined to tagged resources in the declared VPC, and public endpoints and unencrypted storage are denied by condition. A task that asks for anything else fails with `AccessDenied`. * **Identity on the database path.** Queries and migrations run as the application's own PostgreSQL role, over the connector role. Create and retire run as the master user, bounded not by IAM but by the allowlisted module, which executes the DDL for the named database and its roles and nothing else. * **Allowlists on the data plane.** The worker builds the OpenTofu configuration only from module sources on an allowlist in its own configuration, runs `tofu plan`, and rejects any plan that touches a resource type outside its allowlist. * **Network.** Clusters accept connections only from the security groups and CIDR ranges you configured. **Enforced by the control plane, as defense in depth:** * Tasks are routed only to a data plane registered for the exact data tag they belong to, and wildcard data tags are rejected at registration. * Task payloads carry intent and the application's schema files but never credentials, and outcome reports that contain credential material are rejected. ### Residual risk **If the control plane were compromised**, an attacker could queue tasks but not execute them, and nothing the data plane executes can escape the account-side bounds above. Within those bounds, the worst case is: * **Destructive changes to clusters the worker already manages**, such as deleting or resizing them. Neither the allowlists nor IAM independently block a destructive plan against an in-footprint cluster; `deletion_protection` (default `true`), automated backups, and the final snapshot on deletion are the controls that apply. * **Loss or corruption of application data across the data plane**, either through attacker-chosen migration SQL running as each application's own role in its own database, or through queued retires dropping each application's database. Backups are the recovery path. * **Unexpected spend** from queued cluster creations, up to your pool thresholds and AWS quotas. No attacker-supplied SQL runs as the master user, and nothing outside the tagged footprint or the declared VPC is reachable. Set those cluster controls in Terraform or Helm, not the console: the worker re-applies module-managed settings on later runs and would revert a console change. See [Physical database options](/admin/superblocks-on-aws/database-reference#physical-database-options). **If the agent key leaks**, an attacker could register as a data plane for your organization, claim queued tasks (seeing operations, connection metadata, and migration SQL), and post outcome reports. They could not call AWS, assume either IAM role, or connect to a cluster: none of those trust the key, and clusters accept traffic only from the security groups you configured. Rotate the key as you would for any other data plane compromise. ## How to verify ### Before setup * Read the [Raw IAM policy JSON](/admin/superblocks-on-aws/database-reference#raw-iam-policy-json) for both roles. The Terraform module attaches exactly these policies, and that section is written to be handed to an IAM approver as is. * Read the module source. `app-db-prereqs` is published in the `superblocksteam/superblocks/aws` registry module, and its `terraform plan` output lists every resource it will create before you apply it. * Read the [outbound requests](/enterprise/hybrid-architecture/manage/requests#superblocks-database-requests) the data plane makes, and confirm your egress path allows them. No inbound rule is required. * Confirm the inputs you will pass: the VPC, the private subnets, the security groups allowed to reach port 5432, and the data tags. Each becomes a condition in the policies above. ### After setup Everything the feature manages is discoverable from your account, without involving Superblocks. IAM is global, but the tagging and RDS commands below are regional; run them in every region where you deployed a data plane. ```bash theme={null} # Confirm who can assume each role: expect only your ECS task or # Kubernetes service account on the worker, and only the worker on the connector aws iam get-role --role-name sb-app-db--lifecycle-worker- \ --query Role.AssumeRolePolicyDocument aws iam get-role --role-name superblocks-app-db-connector- \ --query Role.AssumeRolePolicyDocument # Every AWS resource the feature has created in this region; # add Key=AgentName,Values= to limit it to one data plane aws resourcegroupstaggingapi get-resources --region \ --tag-filters Key=ManagedBy,Values=superblocks-app-database-lifecycle # Confirm no cluster instance is publicly reachable aws rds describe-db-instances --region \ --query "DBInstances[?starts_with(DBInstanceIdentifier, 'sb-')].[DBInstanceIdentifier, PubliclyAccessible]" ``` In CloudTrail, every AWS call the data plane makes is a session of the lifecycle worker role, every application connection starts with an `AssumeRole` on the connector role, and every master-user session starts with a `GetSecretValue` on the cluster's `rds!cluster-*` secret. Individual PostgreSQL connections and statements are in the per-cluster logs exported to CloudWatch Logs; see [Observing](/admin/superblocks-on-aws/database-reference#observing). ## Next steps > [card] [Reference](/admin/superblocks-on-aws/database-reference) > > Resource names, IAM scoping, tagging, and the full policy JSON. > [card] [Setup](/admin/superblocks-on-aws/database-setup) > > Run the Terraform module and provision the first cluster. # Set up Superblocks Database Source: https://docs.superblocks.com/admin/superblocks-on-aws/database-setup Provision Superblocks-managed AWS Aurora PostgreSQL inside your own AWS account using Terraform and your data plane For the team that owns your AWS accounts: enable [Superblocks Database](/admin/superblocks-on-aws/database) on a data plane. ## Before you begin Superblocks Database is enabled per data plane and routed by exact data tag, so it is the last step in setting up a Hybrid deployment, not the first. Complete these before you continue. **1. Decide your data plane layout and deploy each data plane** Most customers run two data planes, one for the `dev` tag and one for the `production` tag, in separate AWS accounts and VPCs. See [Plan your data planes](/enterprise/hybrid-architecture/plan/index) and [Reference architectures](/enterprise/hybrid-architecture/plan/architectures). **2. Finalize your data tags and environments** Create every data tag you will enable databases for and decide which environments allow it on the [Environments](/admin/environments#manage-environments-and-data-tags) page. Each database-enabled data plane must serve exact tags; the default `profile:*` is not allowed. **3. Check the layout against the database rules** One database-enabled data plane per data tag, a separate prerequisite stack per region, and no wildcard tags. See [Data planes and Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database). Data tag keys, agent names, and VPCs are permanent once databases exist Database names, IAM roles, and state paths are derived from these values, and there is no migration path. Renaming a data tag or agent name orphans every database created under the old one. See [Immutable setup inputs](/admin/superblocks-on-aws/database-reference#immutable-setup-inputs). ## Setup decisions and prerequisites Superblocks Database requires a [Hybrid](/enterprise/deployment-overview) or [Cloud-Prem](/enterprise/cloud-prem/aws) deployment on AWS, running on [ECS Fargate](/enterprise/hybrid-architecture/deployment/aws_ecs_fargate) or [EKS](/enterprise/hybrid-architecture/deployment/kubernetes). It is not available on Superblocks Cloud. If you are using Cloud-Prem with Superblocks-managed data planes, talk to your account manager. **Decisions you cannot change later.** Choose these per data plane before your first `terraform apply`: * **Agent name.** A permanent identifier for the data plane, for example `produsw2`, used as the prefix for its AWS resources. At most 15 lowercase alphanumeric characters, unique per AWS account. * **Data tags.** The exact tags this data plane serves. They are declared twice, as a list of bare keys in Terraform (`agent_tags = ["production"]`) and as a `profile:` string on the data plane (`profile:production`), and the two must match. Neither accepts `*`. * **VPC.** Every IAM policy for the data plane is scoped to one VPC, which needs private subnets in at least two Availability Zones. * **Capacity shape.** Two instances at 2-32 ACUs each for every data tag, including edit and preview. This is the module default, but set it explicitly. Every cluster the pool adds later inherits whatever shape is configured at the time, so decide before the first cluster is created. See [Reference: Cluster autoscaling](/admin/superblocks-on-aws/database-reference#cluster-autoscaling). **Tooling:** * **Terraform 1.6 or later.** Superblocks distributes a module that creates the IAM roles and OpenTofu state bucket. Manual setup is not recommended. * **Permission to create IAM roles, an S3 bucket, and Aurora clusters.** See [Reference: Raw IAM policy JSON](/admin/superblocks-on-aws/database-reference#raw-iam-policy-json) if your organization requires policies to be pre-approved. * **AWS quota headroom** for Aurora clusters and instances, DB subnet groups, security groups, ENIs, and free IP addresses in your database subnets. The pool grows over time. * **Data plane image v1.49.0 or later.** On Fargate, pin `superblocks_agent_image = "ghcr.io/superblocksteam/agent:v1.49.0"`. On EKS, use a chart `appVersion` that deploys agent `v1.49.0` or newer. ## One-time setup Setup runs once per data plane: create the AWS prerequisites with Terraform, provision the first Aurora cluster from the admin panel, and confirm builders can use it. After that, Superblocks grows and manages the pool without further setup. ### Values to gather Collect these values first. Replace every `` in the examples with your own values. ``, ``, and `` are the fixed values from [Setup decisions](#setup-decisions-and-prerequisites) above. | Placeholder | Description | | - | - | | `` | [Agent name](/admin/superblocks-on-aws/database-reference#agent-name) for this data plane. Source of truth is the Terraform `agents` map key; also set as Fargate `agent_name` or Helm `superblocks.agentName`, and stamped as the IAM `AgentName` tag. Max 15 characters, lowercase alphanumeric, unique per AWS account. | | `` | OpenTofu state prefix derived from the agent name (default `app-db/`). Copy from `module.app_db_prereqs.agents[""].key_prefix` into Fargate `key_prefix` or Helm `databaseLifecycle.backend.keyPrefix`. See [Agent name](/admin/superblocks-on-aws/database-reference#agent-name). | | `` | [Data tag](/development-lifecycle/build/data-tags) keys this data plane serves (for example in `agent_tags` / Helm `agentTags`) | | `` | AWS region for this data plane | | `` | 12-digit AWS account ID | | `` | VPC where Aurora clusters will be provisioned. The lifecycle worker IAM policy is scoped to this VPC. | | `` | Private subnet IDs for the Aurora subnet group (at least two Availability Zones) | | `` | EKS only: the security group your data plane pods use (the node group's, or the pod security group when [security groups for pods](https://docs.aws.amazon.com/eks/latest/userguide/security-groups-for-pods.html) is enabled). Fargate wires the root module's `ecs_security_group_id` output instead; see the ECS Fargate tab in [Step 1](#step-1-run-the-terraform-module). | | `` | Fargate only, when adding to an existing data plane: the name (not ARN) of the IAM role your ECS task already runs as. See "Adding to an existing Fargate data plane" under the ECS Fargate tab in [Step 1](#step-1-run-the-terraform-module). | ### Step 1: Run the Terraform module Superblocks publishes two submodules as part of the `superblocksteam/superblocks/aws` Terraform registry module. Use a compatible release from version `1.5.3` up to, but not including, `2.0.0` so the prerequisite stack includes the App Database modules, observability IAM resources, current resource-naming inputs, and the tagged security-group-rule permissions the current physical modules need. A `1.5.2` stack can fail provisioning with `AccessDenied` when the worker creates those rule resources: * `modules/app-db-prereqs`: run by all customers. Creates the lifecycle worker IAM roles, connector IAM roles, shared Enhanced Monitoring role, and shared S3 state bucket. * `modules/app-db`: ECS Fargate only. Takes the prereq outputs plus your database config and renders the data plane runtime configuration as `ecs_env_vars`, ready to inject into the ECS task definition. It also outputs `superblocks_agent_tags` in the form the data plane expects, so the profiles it serves come from the same place as the databases it provisions. If you are updating an existing Terraform deployment, change the constraint and run `terraform init -upgrade` followed by `terraform plan` before applying. This plan covers the prerequisite IAM and S3 resources and the rendered data plane configuration; it does not show changes to Aurora clusters, which live in the lifecycle worker's separate OpenTofu state. Review the prerequisite plan and the observability settings in `physical_module_inputs` (see [Step 1](#step-1-run-the-terraform-module) below) before restarting the data plane. After the data plane registers, Superblocks queues applies for drifted physical settings on existing clusters. Open the admin **Databases** page and confirm the queued apply succeeded; a refusal names the frozen field (a setting that cannot change on an existing pool, such as VPC or subnets). See [Apply configuration changes to existing clusters](#apply-configuration-changes-to-existing-clusters). To cancel before applying, restore the previous version constraint and lock file. Use a single Terraform state bucket for all data planes in a given account and region so subsequent runs are idempotent. For the full inventory of what this run creates, see [Reference: One-time setup](/admin/superblocks-on-aws/database-reference#one-time-setup). Pick the platform your data plane runs on — the steps differ for ECS Fargate and EKS, and you only need to follow one. > [accordion] ECS Fargate > > For Fargate deployments, both modules are run together. The `modules/app-db` outputs (`ecs_env_vars` and `superblocks_agent_tags`) are passed directly into the root `terraform_aws_superblocks` module, which wires them into the ECS task definition. You do not need to inspect the contents of `ecs_env_vars`; it is generated in the expected format. > > ```mermaid theme={null} > sequenceDiagram > autonumber > participant Admin as Your admin > participant TF as Terraform > participant AWS as Your AWS account > participant ECS as ECS > participant DP as Data plane > participant SB as Superblocks control plane > > Admin->>TF: terraform apply: app-db-prereqs plus app-db > TF->>AWS: Create lifecycle worker IAM role > TF->>AWS: Create connector IAM role > TF->>AWS: Create S3 state bucket > TF->>ECS: Update task definition: database env vars plus lifecycle worker task role > ECS->>DP: Redeploy the data plane automatically > DP->>SB: Register capability, engine, and capacity > SB-->>Admin: Admin panel shows the registered config as read-only > ``` > > **Step 1a: Add both modules to your Terraform config.** > > The snippet below sets the required inputs and the recommended database settings. Every option is catalogued on the reference page: [Module options](/admin/superblocks-on-aws/database-reference#module-options) and [Per-data-plane options](/admin/superblocks-on-aws/database-reference#per-data-plane-options) for the prerequisite stack, [Pool options](/admin/superblocks-on-aws/database-reference#pool-options) and [Physical database options](/admin/superblocks-on-aws/database-reference#physical-database-options) for the database settings. > > ```hcl theme={null} > # Step 1 of 2: IAM roles and S3 state bucket. > # Run once per region. All data planes in this region share one S3 state bucket. > module "app_db_prereqs" { > source = "superblocksteam/superblocks/aws//modules/app-db-prereqs" > version = ">= 1.5.3, < 2.0.0" > > deployment_type = "fargate" > region = "" > > # One entry per data plane in this region. The map key is . > agents = { > "" = { > agent_tags = [""] > vpc_id = "" > > # Optional: name (not ARN) of an existing ECS task role to attach policies to. > # existing_role_name = "" > } > } > > # Inventory tags only. ManagedBy, superblocks:owned, and aws-apn-id are > # reserved and always enforced. > tags = { > "" = "" > } > } > > # Step 2 of 2: data plane database config. One module call per data plane. > # Generates ecs_env_vars in the expected format. > module "app_db" { > source = "superblocksteam/superblocks/aws//modules/app-db" > version = ">= 1.5.3, < 2.0.0" > > # Must equal the agents map key above (). This is the data plane's > # stable identity for the database pool and the AgentName IAM tag. See the > # setup decisions above. > agent_name = "" > > # Wired from the agents[""] entry above, so the two cannot diverge. > agent_tags = module.app_db_prereqs.agents[""].agent_tags > connector_role_arn = module.app_db_prereqs.agents[""].connector_role_arn > > # All data planes in this region share one bucket. > state_bucket_name = module.app_db_prereqs.state_bucket_name > > region = "" > > # Namespaces this data plane's OpenTofu state within the shared S3 bucket. > # Must match the IAM-granted prefix from app_db_prereqs (default > # app-db/). Wire the output — a hand-typed value that differs > # fails every state read/write with AccessDenied. > key_prefix = module.app_db_prereqs.agents[""].key_prefix > > # Databases per cluster before another cluster joins the pool. > # Fargate default is 100, with no proactive floor. Helm also defaults to 100, > # with a 20% proactive floor; set both Helm fields explicitly in the EKS tab. > pool = { > max_databases = 100 > } > > # Recommended settings for every Aurora cluster this data plane provisions. > physical_module_inputs = { > monitoring_interval = 60 > monitoring_role_arn = module.app_db_prereqs.enhanced_monitoring_role_arn > > backup_retention_period = 7 > delete_automated_backups = false > deletion_protection = true > skip_final_snapshot = false > > # Always-on capacity, ACUs per instance. Matches the module default > # (2 instances, 2-32 ACUs), which never pauses. > deployment = { > serverless_v2 = { > instance_count = 2 > max_acu = 32 > min_acu = 2 > } > } > > # The ECS task's security group, created by the root module below. Each > # cluster admits port 5432 only from the groups listed here. > source_security_group_ids = [module.terraform_aws_superblocks.ecs_security_group_id] > > subnet_ids = [ > "", > "", > "", > ] > > tags = module.app_db_prereqs.tags > > # Must match the vpc_id declared in the agents map above. > vpc_id = "" > } > } > > module "terraform_aws_superblocks" { > source = "superblocksteam/superblocks/aws" > version = ">= 1.5.3, < 2.0.0" > > vpc_id = "" > lb_subnet_ids = ["", ""] > ecs_subnet_ids = ["", ""] > domain = "" > subdomain = "superblocks" > > superblocks_agent_key = "" > > # Pin v1.49.0. > superblocks_agent_image = "ghcr.io/superblocksteam/agent:v1.49.0" > > # Comma-separated profile: string, not a list. The app-db > # module derives it from its own agent_tags, so wire it from there rather than > # writing it out. See the warning below. > superblocks_agent_tags = module.app_db.superblocks_agent_tags > > # Run the ECS task as the lifecycle worker role. This is required and separate > # from the env vars below: environment variables cannot change the task role, > # so without this the data plane keeps its previous role and every AWS call the > # lifecycle worker makes fails with AccessDenied. > superblocks_agent_role_arn = module.app_db_prereqs.agents[""].lifecycle_worker_role_arn > > # Wire the generated database env vars into the ECS task definition. > superblocks_agent_environment_variables = module.app_db.ecs_env_vars > } > ``` > > The `deployment` block above is the recommended shape for every data tag. It matches the module default, but set it explicitly rather than relying on the default. Setting `min_acu` to `0` lets an idle cluster pause, which costs less but adds a cold start to the next connection (not recommended). See [Reference: Cluster autoscaling](/admin/superblocks-on-aws/database-reference#cluster-autoscaling). > > Each cluster the lifecycle worker provisions gets its own security group, which admits port 5432 only from `source_security_group_ids` and `allowed_cidr_blocks`. Set at least one; with both empty, provisioning succeeds and no query can connect. On Fargate the value is the ECS task's security group, which the root module creates and publishes as `ecs_security_group_id`. If you set `create_ecs_sg = false`, that output is `null`; pass the group you attach through `ecs_security_group_ids` instead. A literal ID of the same group works too, so existing deployments that pasted one need no change. > > #### Adding to an existing Fargate data plane > > Set `existing_role_name` to your current ECS task role name (not its ARN). The module attaches its policies to that role instead of creating one, and `lifecycle_worker_role_arn` resolves to it, so the wiring above does not change. > > If the module block already sets `superblocks_agent_environment_variables`, `concat` the two lists. Keep every name unique: neither Terraform nor ECS rejects a duplicate, and AWS does not define which value the container sees. Do not redefine a name that `module.app_db.ecs_env_vars` already sets. > > ```hcl theme={null} > superblocks_agent_environment_variables = concat( > module.app_db.ecs_env_vars, > [{ name = "", value = "" }], > ) > ``` > > **Step 1b: Run `terraform apply`.** The module applies three changes: it creates the prereq resources (IAM roles and S3), renders the data plane runtime config as env vars, and wires them into the ECS task definition along with the lifecycle worker task role. > > The `agent_tags` in `app_db_prereqs` and the `superblocks_agent_tags` you pass to `terraform_aws_superblocks` must name the same [data tags](/development-lifecycle/build/data-tags). The connector role's `rds-db:connect` permissions are scoped to the DB users derived from `agent_tags`, so if the two diverge, the data plane's IAM token matches no permitted DB user and queries fail. Nothing validates one against the other, which is why the example wires both from module outputs. > > **Step 1c: ECS redeploys automatically** when the task definition is updated. Your data plane starts with Superblocks Database enabled and registers its database lifecycle capability with the Superblocks control plane. > > To run more than one data plane in this account and region, see [Reference: Multiple data planes in one account and region](/admin/superblocks-on-aws/database-reference#multiple-data-planes-in-one-account-and-region). > [accordion] EKS > > For EKS deployments, the Terraform module handles IAM and S3 only. The database configuration is set separately in your Helm chart under the `databaseLifecycle` block. > > #### EKS-only prerequisite: OIDC provider ARN > > In addition to the [values to gather](#values-to-gather) above, EKS needs the cluster's **IAM** OIDC identity provider ARN (``). It is required for IRSA so the data plane pod can assume the lifecycle worker role. > > Every EKS cluster exposes an OIDC issuer URL. Separately, your AWS account must have an IAM OIDC provider for that issuer — that provider's ARN is what you pass to Terraform. Retrieve it with: > > ```bash theme={null} > CLUSTER_NAME="" > REGION="" > > ISSUER="$(aws eks describe-cluster \ > --name "${CLUSTER_NAME}" \ > --region "${REGION}" \ > --query "cluster.identity.oidc.issuer" \ > --output text)" > > if [[ -z "${ISSUER}" || "${ISSUER}" == "None" ]]; then > echo "No OIDC issuer found for cluster ${CLUSTER_NAME} in ${REGION}" >&2 > else > # Prints the matching IAM OIDC provider ARN, or nothing if none exists yet > aws iam list-open-id-connect-providers \ > --query "OpenIDConnectProviderList[].Arn" --output text \ > | tr '\t' '\n' \ > | grep -F "${ISSUER#https://}" > fi > ``` > > If that command prints nothing, create the IAM OIDC provider for the cluster before continuing (see [AWS: Create an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html)). > > You can also confirm in the console: copy the **OpenID Connect provider URL** from **EKS** → **Clusters** → your cluster → **Overview** → **Details**, strip the `https://` prefix, then search for that value under **IAM** → **Identity providers**. Open the matching provider — its ARN is at the top of the page. > > ```mermaid theme={null} > sequenceDiagram > autonumber > participant Admin as Your admin > participant TF as Terraform > participant AWS as Your AWS account > participant Helm as Helm > participant DP as Data plane > participant SB as Superblocks control plane > > Admin->>TF: terraform apply: app-db-prereqs > TF->>AWS: Create lifecycle worker IAM role > TF->>AWS: Create connector IAM role > TF->>AWS: Create S3 state bucket > TF-->>Admin: Output role ARNs and bucket name > Admin->>Helm: Add role ARNs, bucket, and db config to values.yaml > Admin->>Helm: helm upgrade > Helm->>DP: Restart the data plane with Superblocks Database enabled > DP->>SB: Register capability, engine, and capacity > SB-->>Admin: Admin panel shows the registered config as read-only > ``` > > **Step 1a: Run the prereqs module and apply.** > > The snippet below sets the required inputs, including the EKS-only `oidc_provider_arn`. Every optional input is catalogued in [Reference: Module options](/admin/superblocks-on-aws/database-reference#module-options) and [Reference: Per-data-plane options](/admin/superblocks-on-aws/database-reference#per-data-plane-options). > > ```hcl theme={null} > module "app_db_prereqs" { > source = "superblocksteam/superblocks/aws//modules/app-db-prereqs" > version = ">= 1.5.3, < 2.0.0" > > deployment_type = "eks" > region = "" > > # One entry per data plane in this region. The map key is . > agents = { > "" = { > agent_tags = [""] > vpc_id = "" > > # ARN of the EKS cluster's IAM OIDC provider, required for IRSA. See > # "EKS-only prerequisite: OIDC provider ARN" above. > oidc_provider_arn = "" > } > } > > # Inventory tags only. ManagedBy, superblocks:owned, and aws-apn-id are > # reserved and always enforced. > tags = { > "" = "" > } > } > ``` > > If your data plane pod uses a namespace or service account other than the chart defaults, or already has an IRSA-annotated role, set `namespace`, `service_account_name`, or `existing_role_name` as described in [Reference: Per-data-plane options](/admin/superblocks-on-aws/database-reference#per-data-plane-options). > > **Step 1b: Wire the outputs into your Helm values.** After `terraform apply`, add the module outputs and your database config to your Helm values. The settings span four top-level sections, not just `databaseLifecycle`. The two IAM roles in particular are wired through the sections that already own identity in the chart: > > | What | Where it goes | Why there | > | - | - | - | > | Agent name (``) | `superblocks.agentName` | Must equal the [agent name](/admin/superblocks-on-aws/database-reference#agent-name) used as the Terraform `agents` map key | > | OpenTofu state prefix (``) | `databaseLifecycle.backend.keyPrefix` | Must equal `module.app_db_prereqs.agents[""].key_prefix`, as described under [Agent name](/admin/superblocks-on-aws/database-reference#agent-name) | > | Lifecycle worker role | `serviceAccount.annotations` | EKS grants pod identity through the IRSA annotation, so the role reaches the pod the same way any other AWS role does | > | Connector role | `postgres.appDbConnectorRoleArn` | It is a query-time database credential, and `postgres` owns the data plane's PostgreSQL connection settings | > | Enhanced Monitoring role | `databaseLifecycle.physicalModuleInputs.monitoring_role_arn` | RDS requires this role to publish operating-system metrics at the configured interval | > | Data tags | `superblocks.agentTags` | Source of truth for which data tags accept database work | > | Optional inventory tags | `databaseLifecycle.physicalModuleTags` | Optional cost/team tags only. Do not set `ManagedBy`, `AgentName`, `Vpc`, `superblocks:owned`, or `aws-apn-id` - the lifecycle worker and physical modules stamp those | > | Everything else | `databaseLifecycle` | Feature-specific configuration | > > Reuse the same [agent name](/admin/superblocks-on-aws/database-reference#agent-name) you set as the `agents` map key, and copy the state prefix from the Terraform output. Helm cannot detect a mismatch, and IAM fails the work later: a different `superblocks.agentName` lets the pod assume the lifecycle worker role but fails every tagged create and mutate with `AccessDenied`, and a different `keyPrefix` fails every OpenTofu state read and write with `AccessDenied`. To use a prefix other than the default, set `agents[""].key_prefix` in `app_db_prereqs` and copy the new output — do not type a value such as `app-db/prod` only into Helm. > > ```yaml theme={null} > superblocks: > # Must equal the agents map key in app_db_prereqs. > # Also becomes the AgentName tag on every Aurora resource this data plane creates. > # Required when Superblocks Database is enabled. > agentName: > > # Comma-separated string, each data tag prefixed with profile:. > # Must cover the same data tags as agent_tags above. See the warning below. > agentTags: profile:,profile: > > serviceAccount: > annotations: > # Lifecycle worker role, assumed by the data plane pod through IRSA. > # From: module.app_db_prereqs.agents[""].lifecycle_worker_role_arn > eks.amazonaws.com/role-arn: "" > > postgres: > # Connector role, used at query time to authenticate to app databases with > # RDS IAM tokens. > # From: module.app_db_prereqs.agents[""].connector_role_arn > appDbConnectorRoleArn: "" > > # The data plane refuses to authenticate as any IAM role outside this list. > # It must cover appDbConnectorRoleArn above, or the chart rejects the upgrade. > iamAllowedRoleArnPrefixes: > - "" > > databaseLifecycle: > enabled: true > > # OpenTofu state. The bucket is shared across every data plane in this account > # and region; keyPrefix namespaces this data plane's state inside it and must > # be unique per data plane. Copy the IAM-granted prefix from > # module.app_db_prereqs.agents[""].key_prefix (default > # app-db/). A hand-typed value that differs fails every state > # read/write with AccessDenied. > backend: > stateBackend: s3 > # From: module.app_db_prereqs.state_bucket_name > bucket: "" > region: "" > # From: module.app_db_prereqs.agents[""].key_prefix > keyPrefix: "" > useLockfile: true > > # Secrets Manager ARNs the data plane may read, used to fetch the AWS-managed > # Aurora master credential during provisioning. Scope this to RDS-managed > # secrets in your account and region. An empty list denies resolution, which > # makes every provision fail. Use the rds!db- prefix instead for standalone RDS. > allowedRefPrefixes: > - arn:aws:secretsmanager:::secret:rds!cluster- > > # Databases per cluster before another cluster joins the pool. > # Helm defaults are maxDatabases: 100 and minAvailableCapacityPercent: 20, so > # a new cluster is enqueued when 20 or fewer slots remain in the current one. > # Set both explicitly so the pool behavior is visible in your values. > pool: > maxDatabases: 100 > minAvailableCapacityPercent: 20 > > # Optional inventory tags only (cost center, team, and similar). Do not set > # ManagedBy, AgentName, Vpc, superblocks:owned, or aws-apn-id - the lifecycle > # worker and physical OpenTofu modules stamp those on every runtime resource. > # The chart merges physicalModuleTags over physicalModuleInputs.tags when both > # are present. > # physicalModuleTags: > # : "" > > # Recommended settings for every Aurora cluster this data plane provisions. > physicalModuleInputs: > # From: module.app_db_prereqs.enhanced_monitoring_role_arn > monitoring_interval: 60 > monitoring_role_arn: "" > > backup_retention_period: 7 > delete_automated_backups: false > deletion_protection: true > skip_final_snapshot: false > > # Always-on capacity, ACUs per instance. Matches the module default > # (2 instances, 2-32 ACUs), which never pauses. > deployment: > serverless_v2: > instance_count: 2 > max_acu: 32 > min_acu: 2 > > # The security group your data plane pods use. Every cluster admits port > # 5432 from this list and allowed_cidr_blocks only; the chart refuses the > # upgrade when both are empty. > source_security_group_ids: > - "" > > subnet_ids: > - "" > - "" > - "" > > # Must match the vpc_id declared in the agents map above. > vpc_id: "" > ``` > > The `deployment` values above are the recommended shape for every data tag. They match the module default, but set them explicitly rather than relying on the default. Setting `min_acu` to `0` lets an idle cluster pause, which costs less but adds a cold start to the next connection (not recommended). See [Reference: Cluster autoscaling](/admin/superblocks-on-aws/database-reference#cluster-autoscaling). > > Every database setting is catalogued in [Reference: Pool options](/admin/superblocks-on-aws/database-reference#pool-options) and [Reference: Physical database options](/admin/superblocks-on-aws/database-reference#physical-database-options), including the Helm-only switches for CloudWatch log exports and Performance Insights described under [Observing](/admin/superblocks-on-aws/database-reference#observing). > > Values not shown keep their chart defaults, which are the recommended settings: > > * **The logical and physical database modules** default to the modules packaged in the data plane image (`./modules/postgres-managed-database` and `./modules/aws-aurora-managed-cluster`). Override `databaseLifecycle.modules.logical.source` or `databaseLifecycle.modules.physical.source` only to run a fork, a custom module, a git pin, or standalone RDS (`./modules/aws-rds-managed-instance`). Keep both sources on compatible releases. Setting `allocated_storage` and `instance_class` without changing `modules.physical.source` still runs the Aurora module. > * **TLS** uses `verify-full` against the AWS trust bundle packaged in the data plane image. The chart refuses to enable Superblocks Database with any weaker mode. > * **The OpenTofu working directory and binary path** are fixed properties of that image. The chart rejects attempts to override either. > * **The resource types the lifecycle worker may create** default to exactly what the database modules it ships with declare. Set `allowedResourceTypes` only to run a fork or a custom module. A non-empty list replaces the default outright rather than adding to it. > > The `agent_tags` in `app_db_prereqs` and the `agentTags` in your Helm values must name the same [data tags](/development-lifecycle/build/data-tags). The connector role's `rds-db:connect` permissions are scoped to the DB users derived from `agent_tags`, so if the two diverge, the data plane's IAM token matches no permitted DB user and queries fail. Nothing validates one against the other. > > **Step 1c: Upgrade your Helm chart.** > > ```bash theme={null} > helm upgrade superblocks-agent superblocksteam/superblocks-agent \ > -f values.yaml \ > --namespace superblocks > ``` > > Your data plane restarts with Superblocks Database enabled and registers its database lifecycle capability with the Superblocks control plane. > > To run more than one data plane in this account and region, see [Reference: Multiple data planes in one account and region](/admin/superblocks-on-aws/database-reference#multiple-data-planes-in-one-account-and-region). Each additional AWS region needs its own prerequisite stack, and must reuse this region's Enhanced Monitoring role. See [Reference: Additional AWS regions](/admin/superblocks-on-aws/database-reference#additional-aws-regions). ### Step 2: Provision your database from the admin panel Once the data plane is running with Superblocks Database enabled, return to the data plane setup wizard, or open the Superblocks admin panel and navigate to **Databases**. You will see the database configuration registered by your data plane, including the engine, capacity settings, and data tags pulled from its running configuration. These are read-only: they reflect what you configured in Terraform or Helm. Click **Provision**. Superblocks dispatches the request to your data plane, which runs `tofu apply` in your AWS account. You do not re-enter any configuration; it is already in the data plane. ```mermaid theme={null} sequenceDiagram autonumber participant Admin as Admin panel participant SB as Superblocks control plane participant DP as Data plane lifecycle worker participant AWS as Your AWS account Admin->>SB: Click Provision SB->>SB: Deduplicate: one provisioning request per deployment DP->>SB: Claim the provisioning request SB->>DP: Dispatch the provisioning request DP->>AWS: tofu init plus tofu apply Note over AWS: Aurora cluster
DB subnet group
Security group and rules
tagged AgentName, ManagedBy, Vpc, superblocks:owned, and aws-apn-id AWS-->>DP: Cluster ready DP->>SB: Terminal callback: success or failure with error detail SB-->>Admin: Admin panel reflects the result ``` Provisioning an Aurora cluster typically takes 5 to 15 minutes. The admin panel shows live status and updates automatically, so you do not need to keep the browser open. **If two admins click Provision at the same time**, only one request proceeds. The second admin sees that provisioning is already in progress and when it started, and can follow the same live status. **When provisioning completes**, the data plane sends a confirmation to the Superblocks control plane and the panel shows a success state. If provisioning fails, you see the error detail and a retry option. Failures are surfaced here, not to end users. ### Step 3: Ready Once the panel shows a success state, your builders can create apps backed by Superblocks Database immediately. There is no cold-start wait, because the database pool is already running. * **Builders** get an isolated logical database inside the shared pool on demand. When the pool is full, Superblocks provisions another cluster first, which takes 5 to 15 minutes. See [Reference: Creating an app database](/admin/superblocks-on-aws/database-reference#creating-an-app-database). * **Deploys are gated.** Superblocks blocks a deploy if the deploy-time database or its required SQL migrations are not ready. ### Step 4: Verify observability Open the newly provisioned cluster in the AWS RDS console and confirm that its settings match the options you selected: * **CloudWatch Logs exports** includes `postgresql`, with a corresponding `/aws/rds/cluster//postgresql` log group retained for 30 days. EKS deployments may show no export if you explicitly disabled it; Fargate deployments must show it. * **Database Insights** is in Standard mode, with Performance Insights enabled and retained for 7 days. EKS deployments may show it disabled if you explicitly opted out; Fargate deployments must show it enabled. * **Enhanced Monitoring** is enabled at a 60-second interval, unless you disabled it. Seeing a signal you opted out of listed as disabled is expected, not a setup failure. This step only confirms that the signals you asked for are available; what the enabled signals actually record is covered under [Reference: Observing](/admin/superblocks-on-aws/database-reference#observing), and dashboards, alarms, and incident response remain your organization's responsibility. ## Apply configuration changes to existing clusters `terraform apply` and `helm upgrade` update the data plane's advertised settings. They do not run OpenTofu against Aurora. After the data plane registers, Superblocks compares those settings to each cluster's last-applied configuration. If they differ, it queues an apply against the existing OpenTofu state, one cluster at a time. Superblocks refuses plans that would replace or destroy a cluster. Use the admin **Databases** page when you need to start or resume that apply yourself. Confirm each action in the dialog. | When | What to click | | - | - | | After you change physical settings and the data plane registers | Wait. Superblocks queues the apply automatically for clusters that drifted. | | Drift remains and no apply is running | **Apply settings** updates only clusters that do not match. | | Someone changed a tagged cluster in the AWS console | **Force apply** reapplies configured settings to every cluster in the pool, including ones that already match. It does not skip safety checks. | | An apply failed | Open the run, then **Retry apply**. Superblocks resumes from the cluster that failed. | Some settings cannot change on an existing pool: VPC, subnet list, subnet-group identity, Aurora parameter-group identity or family, and deployment mode (`serverless_v2` vs `provisioned`). Superblocks still queues an apply, then the data plane refuses it with `policy_blocked` and names the frozen field, for example `subnet_ids` or `vpc_id`. Revert that Terraform or Helm value. After the data plane registers the restored configuration, Superblocks queues a new apply across the clusters from the failed run. The old failed run is superseded and no longer offers **Retry apply**. Backup retention, monitoring, tags, and serverless scaling (ACU range and instance count) can still change on existing clusters. If connected data plane replicas advertise different configurations, Superblocks does not auto-queue an apply, and **Apply settings** and **Force apply** stay unavailable until the replicas agree. Wait for the rollout to finish. ## You own the AWS resources Every resource lives in your account, and AWS bills you directly for it. With Aurora Serverless v2, the ACU range is a set of scaling bounds rather than reserved compute, so you pay for the capacity your apps consume rather than the configured maximum. The Superblocks defaults balance cost and performance for most customers. **Pool growth is automatic.** Superblocks adds another cluster when the current one fills to `max_databases`, or, on Helm, when remaining capacity hits `minAvailableCapacityPercent`. Your spend grows with usage without another `terraform apply`. The capacity and pool settings from [Step 1](#step-1-run-the-terraform-module) (ACU range, `instance_count`, `max_databases`, and on Helm `minAvailableCapacityPercent`) determine what that growth costs. The admin **Databases** page shows current pool state and capacity. Every cluster the pool adds later inherits the [capacity shape](/admin/superblocks-on-aws/database-reference#cluster-autoscaling) in your configuration at the time it is provisioned. When the data plane registers changes to supported physical settings, Superblocks automatically queues updates for existing clusters; see [Apply configuration changes to existing clusters](#apply-configuration-changes-to-existing-clusters). Settle the frozen fields listed there (VPC, subnet list, subnet-group identity, Aurora parameter-group identity or family, and deployment mode) before the first cluster is created. Those cannot change on an existing pool. ### Protect the OpenTofu state bucket The state bucket is how Superblocks tracks what it created so it can later modify, resize, or retire those resources. Superblocks does not retain a copy; the bucket in your account is the only copy. If the state is lost, Superblocks can no longer manage the existing databases and recovery is a manual exercise. * Leave versioning enabled and leave the non-current version expiration alone. * Do not rename, move, or re-encrypt the bucket, and do not manage it with another tool. * Do not add lifecycle rules that expire current object versions. ### Do not manage the tagged resources by hand Editing or deleting the tagged `sb-*` clusters, subnet groups, or security groups directly in the AWS console creates drift. Console edits do not change the data plane's advertised configuration, so they are not applied automatically. Use **Force apply** on the admin **Databases** page to restore the configured state, and route future changes through Terraform or Helm. ### Keep the data plane current The data plane image contains the lifecycle worker and the database modules it applies. Fixes, new engine options, and configuration changes ship with data plane releases, so a data plane that is not upgraded falls behind on both. See [Upgrading the data plane](/enterprise/hybrid-architecture/manage/upgrade). ### What Superblocks does, and what stays yours Superblocks creates, configures, scales, and retires the Aurora clusters and the per-app logical databases, and runs your applications' SQL migrations. Superblocks does **not**: * **Patch or upgrade the database engine.** AWS applies engine patches during the maintenance window you configure. Because applications share a cluster, a patch or failover affects every application on that cluster. Running a second instance (`instance_count = 2`) reduces the impact but does not remove it. * **Restore your data.** Automated backups are configured from your `backup_retention_period`, but performing a point-in-time restore or a snapshot restore is an operation you run in AWS. * **Tune PostgreSQL for your workload**, or manage database grants beyond the roles it creates for each application. * **Monitor the database on your behalf.** Superblocks enables the observability signals described above, but the metrics and logs stay in your AWS account. Your organization owns access, dashboards, alarms, and incident response. # Superblocks File Store Source: https://docs.superblocks.com/admin/superblocks-on-aws/file-store Give every app its own managed file storage on your infrastructure ## Overview Apps need to handle files. Builders ask Clark to "let users upload receipts," "attach documents to a request," or "store generated PDF reports". Every one of those features needs somewhere to put the files. Without a native file store, this creates the same problem as databases: either IT provisions and manages storage buckets manually for every app, or builders use external services that move files outside your network. Superblocks File Store solves both problems: * **Every app gets its own file storage automatically.** Builders describe the feature they want, and Clark provisions an isolated storage bucket on your infrastructure. No tickets, no manual setup, no cloud console required. * **Files never leave your network.** Storage is provisioned on your own Amazon S3 backend inside your environment. Superblocks orchestrates the flow but your files stay on your infrastructure. * **Each app is fully isolated.** Every app gets its own separate bucket, so there is no risk of cross-app file access. * **Dev and production are separated by default.** Just like [Superblocks Database](/admin/superblocks-on-aws/database), every app gets separate development and production storage. Test files never reach production, and the builder does not need to configure it. Each app's file storage is a dedicated bucket on **Amazon S3** in your account. When a builder asks Clark for a feature that involves files, the platform provisions storage on S3 automatically — the builder never knows the underlying storage system exists. ## How it works ### 1. Admin configures S3 In **Organization Settings**, administrators connect their Amazon S3 backend and set it as the default for all new apps. This is a one-time setup. ### 2. Clark provisions storage per app When a builder asks Clark to handle files — for example, "let users upload receipts" or "store generated reports" — Clark automatically: * Provisions an isolated storage bucket for that app * Configures upload and download APIs * Wires up the app UI to the storage backend ### 3. Files stay on your infrastructure All uploaded files are stored directly in your cloud storage backend. Superblocks orchestrates the upload and download flow, but the files themselves live in your environment, subject to your existing access controls, encryption policies, and compliance requirements. ## What builders experience From the builder's perspective, file storage is invisible. They prompt Clark to add a feature that handles files, and Clark provisions the storage, builds the APIs, and connects the UI. Builders do not need to know which storage backend is in use or how to configure it. # Inference on Amazon Bedrock Source: https://docs.superblocks.com/admin/superblocks-on-aws/inference Run Clark AI inference through Amazon Bedrock so every prompt executes in your AWS account ## Overview Inference through customer's Amazon Bedrock is available on [Cloud-Prem](/enterprise/cloud-prem/aws) deployments only. By default, Clark AI runs inference through models hosted in the Superblocks Cloud. Administrators can instead point Clark at **Amazon Bedrock**, so every prompt runs on models in your own AWS account. Once configured, every prompt that every builder sends to Clark runs inference through Bedrock. Tokens burn down your existing AWS commitment and reduce Clark GAU usage. Builders do not need to configure anything; they use Clark exactly as before. ## How it works ### 1. Admin configures Bedrock In **Organization Settings**, an administrator connects Amazon Bedrock and supplies the necessary credentials and the models and regions Clark should use. ### 2. All builders inherit the configuration Once saved, every builder in the organization automatically runs inference through Bedrock for all Clark interactions. There is no per-user or per-app setup required. ### 3. Inference burns down your commitment and reduces Clark GAU usage Every prompt a builder sends — whether exploring a database schema, generating a plan, or writing code — runs inference on Bedrock. Token consumption counts toward your existing AWS commitment and reduces Clark GAU usage. ## What this means for your organization * **Burn down your AWS commitment**: Inference runs on Bedrock, contributing to your AWS commitment and reducing Clark GAU consumption * **Inference runs in your network**: All model inference executes within your AWS account * **No builder friction**: Builders use Clark identically regardless of the underlying provider # Adding context Source: https://docs.superblocks.com/building-with-clark/adding-context Target elements, tag APIs, and upload files to focus your prompts The more context you can provide Clark on where / what to build, the better. For example, to iterate on a specific feature after an initial generation, you can **target** or **tag** the relevant components so Clark knows exactly what parts of the application to focus on (e.g., sidebar, specific div, backend API). Similarly, in addition to prompting with text alone, **uploading files** (e.g. screenshots, CSVs) is an effective way to provide Clark with more information on the requirements at any point in a chat. ## Targeting frontend elements To focus Clark on any specific parts of the UI, select the **Target** icon in the chat or use keyboard shortcuts (hold `⌘` on Mac or `Ctrl` on PC). ![Enter target mode with Clark](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/targeting_prompt.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=a1cf61da92d046c0d1a29bcdf24211c2) After entering target mode, select any element on the canvas to add it to the chat context before submitting a new prompt. Targeted elements are highlighted in purple and added to the chat context. ![Selecting components in target mode](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/targeting_components.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=a0382b516b286a1ab6b5d72a58f37e8b) ## Tagging backend APIs Similar to integrations, you can focus Clark on specific APIs by @mentioning them in chat. ![Tag API in chat with @](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/tag_api_chat.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=76b021c74480b8623f535f37d27cf0a7) ## Uploading files To add more detail to your prompts, upload files like images, JSON, CSVs, and more. For example, include a screenshot or wireframe to convey layout, hierarchy, and component states. You can attach files from the Clark chat in the editor and from the Clark prompt on the homepage. ![Attach files in chat](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/upload_files.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=5ee40d93a4df05d932784a5ec17bd8a4) ### File size limits * **Images**: up to **50 MB** raw. Large images are automatically resized so the longest edge is at most **1568 pixels** before Clark receives them. * **Text files** (for example JSON, CSV, Markdown): up to **1 MB**. # Backend APIs Source: https://docs.superblocks.com/building-with-clark/backend-apis Superblocks APIs power the backend of your applications. APIs can call [integrations](/integrations/overview) (databases, REST or GraphQL APIs, SaaS platforms) and run custom TypeScript logic. ## API panel The API panel shows execution details for each API (docked to bottom of the editor by default). ![Backend API](https://mintcdn.com/superblocks/B6oCkSI8vKs_41uQ/images/building-with-clark/backend_api.png?fit=max\&auto=format\&n=B6oCkSI8vKs_41uQ\&q=85\&s=cc77ae98888945e0e955fda32e7e0ba8) There you can view a list of API calls and drill into individual API calls. Each API call includes a trace view to view timing and inputs / outputs of the API and individual integration calls. ![Backend API integration call](https://mintcdn.com/superblocks/B6oCkSI8vKs_41uQ/images/building-with-clark/backend_api_integration_call.png?fit=max\&auto=format\&n=B6oCkSI8vKs_41uQ\&q=85\&s=b8f3eb8b9aec23c23d6a63a40994f3fe) ## API source code Under the hood, every API is a TypeScript file that uses the Superblocks API SDK to call your integrations. Click **\<> View code** on any API to inspect the source code. For editing this code directly, see [developing apps in code](/building-with-clark/developing-apps-in-code). ![Backend API source code](https://mintcdn.com/superblocks/B6oCkSI8vKs_41uQ/images/building-with-clark/backend_api_source_code.png?fit=max\&auto=format\&n=B6oCkSI8vKs_41uQ\&q=85\&s=26eb63e3032b119d8b338058b1e3f93e) # Checkpoints & publishing Source: https://docs.superblocks.com/building-with-clark/checkpoints Track versions in Clark chat, preview or publish from a checkpoint, and restore earlier work When Clark finishes a [Build mode](/building-with-clark/plan-and-build-modes#build-mode) prompt that changes your app, it automatically creates a **checkpoint** — a version of your app you can preview, publish, or restore. Clark does not create a checkpoint for a prompt that only answers a question, a prompt in Plan mode, or a prompt that stops before it finishes, for example while it waits for your approval or after you close the tab. ![Checkpoint in Clark chat with Preview and Publish](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/01-checkpoint-in-chat.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=ee0eb13593f255097d8aa19e660cb19d) ## Version history in Clark Version history lives in the **Clark AI** panel. To navigate to version history: 1. Open Clark in the editor 2. In the Clark header, click the **Version history** icon (next to **Chat**) The list shows every checkpoint for the app, where each checkpoint may display details like a **Live** badge for the current production version, build status, and a menu for **Preview**, **Publish**, and related actions. ![Version history in the Clark panel](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/version-history.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=3aca06200c926b442b1cab9ba1dc448a) ## Preview from a checkpoint From a checkpoint in chat or version history, click **Preview** to build a preview of that version. When the build is ready, open the preview from the notification (**Your checkpoint preview is ready. Open preview**) or from the Publish detail view when available. ## Publish from a checkpoint From a checkpoint in chat or version history, click **Publish** to promote that version to production. Superblocks builds, runs pre-publish checks, and deploys in one flow. Builders need [permission to deploy the application](/admin/org-administration/resource-roles#applications). Without it, the **Publish** button stays disabled with a message that you do not have permission to publish to production. ### Publish detail view To open the publish details tab, click **View publish details** from a previewed / published checkpoint card, or click any previewed / published version in history. The **Publish** tab shows: * Progress through the pipeline (build, pre-publish policies, database steps when applicable, publish status) * Errors and retries when a step fails * Pre-publish security and policy findings (fix with Clark, acknowledge advisory findings, or **Publish anyway** when allowed) * Database actions such as provisioning, schema migrations, and acknowledgement of destructive migrations before they run in production ![Publish detail view with pipeline and pre-publish checks](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/03-publish-detail.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=67e03fab71cc2c46e336623ad3730c99) ### Git-connected apps For apps connected to Git, publish using the **Deploy** tab (default branch, e.g. `main`). Publishing is disabled on the **History** tab which displays checkpoints for the `superblocks/live` branch. ![Publish main branch for git-enabled app](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/publish-git.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=1d5d180222f183bae92a4eb4747b68d1) For more on Git workflows, see [Connect to Git](/development-lifecycle/version-control/connect-to-git). ## Restore a checkpoint Restoring resets the app edit state and Clark's chat memory to that checkpoint. Messages and checkpoints after the restore point are permanently archived. To restore a checkpoint: 1. Open the checkpoint in chat or find it in **Version history** 2. Choose **Restore** 3. Confirm in **Restore to checkpoint** If the app uses a managed database, restoring the app does not change schema or data. If later migrations were breaking, the app may fail until the schema is made compatible again. # Clark and data access Source: https://docs.superblocks.com/building-with-clark/data-access How Clark accesses data during development and how to control it with data tags Clark accesses runtime data during development to build and debug apps — the same way a human developer would. Clark only operates in the Edit environment; it never runs against Preview or Production environments. ## Why Clark needs data access Like any developer, Clark needs to see runtime data to build correctly. During development, Clark can do things such as: * Execute APIs and read responses * Run one-off queries to sample data * Inspect individual API step output * Read browser console logs * Screenshot the app * Run automated tests This is consistent with how AI coding tools work broadly — agents like browser-based copilots, MCP-connected assistants, and cloud-hosted AI editors all access runtime data during development. Unlike generic AI coding agents, Superblocks gives Administrators explicit control over which data environments Clark can access during development. ## AI inference and data handling Clark is powered by frontier LLMs hosted securely in the Superblocks Cloud or customer cloud. Here's how your data is handled: * **No model training**: Data sent to the LLM for inference is never used to train or fine-tune any model, regardless of your deployment model. * **Where inference runs**: The location of AI inference depends on your [deployment model](/enterprise/deployment-overview). For Cloud and Hybrid deployments, inference runs in the Superblocks Cloud. For Cloud-Prem deployments, inference runs entirely within your cloud environment. * **What Superblocks retains**: Superblocks stores model requests and responses to power the conversational chat experience. For Cloud and Hybrid deployments, this data is stored in the Superblocks Cloud. For Cloud-Prem deployments, it remains in your cloud environment. This is required for the product to function — it's what allows you to see and continue your chat history with Clark. All data processed and stored in the Superblocks Cloud follows security best practices and a SOC 2-aligned program. HIPAA can apply for PHI where a BAA is in place. See the [Security guide](/enterprise/security/overview) for attestations, subprocessors, and how we protect data. ## Developing against lower environments Superblocks lets you connect multiple data environments — for example, a production database and a staging database — and switch between them using [data tags](/development-lifecycle/build/data-tags). In the Edit environment, Clark runs against whichever data tag is active. Developing against lower environments provides two benefits: 1. **Avoid corrupting production data**: When building applications that perform writes, using a non-production environment prevents Clark from accidentally modifying real data. This applies to all customers regardless of deployment model. If you are building read-only applications, developing against production data in the Edit environment does not carry this risk. 2. **Keep sensitive data in your VPC** (Only relevant for Hybrid customer): For customers using the [Hybrid](/enterprise/hybrid-architecture/overview) deployment, the data plane runs inside your VPC, but Clark and AI inference run in Superblocks Cloud. Data accessed in the Edit environment is sent to the Superblocks Cloud so Clark can use it during development. Using non-production data ensures that production data never leaves your network. Admins can restrict what data Clark has access to by configuring data tags used in the Edit environment — see [Manage environments & data tags](/admin/environments). ## Developing against production data For many use cases, developing against production data is a practical and common approach. This is especially true for read-only applications built on data warehouses, SaaS services, or other data sources where there is no risk of corrupting operational data. Building against production avoids the need to duplicate data into lower environments and gives Clark access to real-world data for more accurate development and testing. As mentioned above, [Hybrid](/enterprise/hybrid-architecture/overview) customers should consider that data accessed in the Edit environment is sent to the Superblocks Cloud during development when determining whether to allow development on production data. # Developing apps in code Source: https://docs.superblocks.com/building-with-clark/developing-apps-in-code Extend applications by editing the underlying React code in your IDE Superblocks supports two-way editing, allowing you to edit the underlying React code directly in your preferred IDE (Cursor, Windsurf, VSCode, etc.). Any changes you make sync instantly with the editor. ## Enabling local edit mode To enable local editing, click **Cloud editing** in the bottom right corner of the screen, then follow the instructions in the modal. ![Local editing](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/local-editing-instructions.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=5adb7a3b4e36f618162b94a0cc367aad) ### 1. Select your preferred IDE Choose between VSCode and Cursor—this will be used for installing the **optional** Superblocks extension. For any other IDE, you can still edit apps locally with the Superblocks CLI. More on this below. ### 2. Install Superblocks CLI Run the `npm` install command from the in-app modal, replacing `2.0.X` with the latest version. ```bash theme={null} npm install -g @superblocksteam/cli@2.0.X --foreground-scripts --loglevel=notice ``` The CLI connects to Cloud US (`app.superblocks.com`) by default. If your organization uses Cloud EU or a Cloud-Prem instance, point the CLI at your instance before you log in, replacing `{tenant}` with the value from [Instance URLs](/enterprise/instance-urls): ```bash theme={null} superblocks config set domain {tenant}.superblocks.com ``` If you already logged in to the wrong instance, set the domain and then run `superblocks login` again. ### 3. Install Superblocks extension If using VSCode or Cursor, click the download button to install the Superblocks extension for your selected IDE. ### 4. Download application Click the download button to download the application code to your computer. The first time an application initializes, you will be prompted to enter your personal API key from the [personal settings page](https://app.superblocks.com/personal-settings#profile). Once the application is downloaded, you can explore the project structure, pages, components, and APIs. ![Local app](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/local_app.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=664ed9b4393fe9ecee3992edb16947c5) ### 5. Start the local dev server If using the Superblocks extension, select the koala logo in your IDE and click **Start Dev Server**. When prompted, choose whether you want to upload your files from local or download the latest files from the app. ![Local start dev server](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/local_start_dev_server.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=fd81aac2115c9f86f2056850cc2bcc19) ![Local start dev prompt](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/local_start_dev_prompt.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=09faabb97dc7285b7d629432ffe680d8) If you are not using the extension, you can still start the local dev server using the Superblocks CLI command: ```bash theme={null} superblocks dev [--upload-first] [--download-first] ``` ### 6. Enable local dev mode Once the dev server is running locally, navigate back to Superblocks and toggle on local dev mode. The bottom right corner will now show **Local editing**. Any edits you make in your local application will sync back to Superblocks, and vice versa. ![Code mode](https://superblocks-demo.s3.us-west-2.amazonaws.com/code-mode.gif) # ChatGPT import Source: https://docs.superblocks.com/building-with-clark/import-app/chatgpt Migrate a ChatGPT-generated app into Superblocks with Clark Import an app generated by ChatGPT into Superblocks and turn your prototype into a production-ready application connected to your enterprise data, with platform-managed authentication and RBAC. ## Before you begin Make sure you have: * A ChatGPT-generated project you want to migrate * Access to the Superblocks workspace where the app will live * The integrations (databases, APIs) you plan to connect already configured in Superblocks ## How to import from ChatGPT **1. Start the import** From the Superblocks home screen, click **Import** in the prompt bar, or click the **Import an app** link below it. **2. Select ChatGPT as your source** When prompted to choose a platform, select **ChatGPT**. **3. Export your project from ChatGPT** Export your app as a zip archive from ChatGPT. Before zipping, exclude the following to keep the upload small: * `node_modules/` * `.git/` * `dist/` and `build/` directories Download the zip once ChatGPT finishes preparing it. ![Superblocks migration Export step for ChatGPT: package your project and download the archive before upload](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/general-app-export.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=c2fb8b3ea4d64becf86cf3fddff839b9) **4. Upload the zip** Drop the downloaded zip file into the Superblocks upload area and click **Import**. ![Migration Upload step: drag-and-drop zone for .zip, .tgz, or .gz archives with Import app button](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/upload-project.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4a69e8878e34f02320c597e930dbd593) **5. Clark migrates the app** Clark inspects your project structure and imports what it can, including: * **Code** — your app's source files and logic * **Static assets** — images, fonts, and other files * **Detected data sources** — any databases or APIs Clark identifies in your code Clark then rewrites the code to run on Superblocks: | ChatGPT app | Superblocks | | - | - | | Hardcoded API calls and fetch requests | [Integrations](/integrations/overview) connected to your data sources | | Hardcoded API keys and secrets | Credentials managed by the platform | | Custom auth | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | React pages and components | React pages hosted on the platform, preserving your design and styles | You'll be prompted to connect your integrations — pick the databases, APIs, and services the app should use in your environment. ## What gets migrated Clark analyzes the ChatGPT-generated source code and replaces external dependencies with Superblocks platform features. ChatGPT projects are typically React or vanilla JavaScript apps — layouts, styles, and component structure are preserved as closely as possible. ## Troubleshooting **The zip won't upload** — Make sure the zip excludes `node_modules`, `.git`, and build output directories. Ask ChatGPT to regenerate the export if needed. **Some components look different after migration** — Clark preserves styles where possible, but some UI patterns may render slightly differently in Superblocks. You can edit any component directly after the import completes. **Integrations aren't connecting** — Verify that the integration is configured in your Superblocks workspace before importing. You can add integrations from the [Integrations page](/integrations/overview) and then reconnect them from within the imported app. # Claude import Source: https://docs.superblocks.com/building-with-clark/import-app/claude Migrate a Claude-generated app into Superblocks with Clark Import an app generated by Claude into Superblocks and turn your prototype into a production-ready application connected to your enterprise data, with platform-managed authentication and RBAC. ## Before you begin Make sure you have: * A Claude-generated project you want to migrate * Access to the Superblocks workspace where the app will live * The integrations (databases, APIs) you plan to connect already configured in Superblocks ## How to import from Claude **1. Start the import** From the Superblocks home screen, click **Import** in the prompt bar, or click the **Import an app** link below it. **2. Select Claude as your source** When prompted to choose a platform, select **Claude**. **3. Export your project from Claude** Export your app as a zip archive from Claude. Before zipping, exclude the following to keep the upload small: * `node_modules/` * `.git/` * `dist/` and `build/` directories Download the zip once Claude finishes preparing it. ![Superblocks migration Export step for Claude: copy export prompt, prepare your archive, then download](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/claude-export.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=f2d53243f2781091ee13e4f0b49f70f7) **4. Upload the zip** Drop the downloaded zip file into the Superblocks upload area and click **Import**. ![Migration Upload step: drag-and-drop zone for .zip, .tgz, or .gz archives with Import app button](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/upload-project.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4a69e8878e34f02320c597e930dbd593) **5. Clark migrates the app** Clark inspects your project structure and imports what it can, including: * **Code** — your app's source files and logic * **Static assets** — images, fonts, and other files * **Detected data sources** — any databases or APIs Clark identifies in your code Clark then rewrites the code to run on Superblocks: | Claude app | Superblocks | | - | - | | Hardcoded API calls and fetch requests | [Integrations](/integrations/overview) connected to your data sources | | Hardcoded API keys and secrets | Credentials managed by the platform | | Custom auth | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | React pages and components | React pages hosted on the platform, preserving your design and styles | You'll be prompted to connect your integrations — pick the databases, APIs, and services the app should use in your environment. ## What gets migrated Clark analyzes the Claude-generated source code and replaces external dependencies with Superblocks platform features. Claude projects are typically React or vanilla JavaScript apps — layouts, styles, and component structure are preserved as closely as possible. ## Troubleshooting **The zip won't upload** — Make sure the zip excludes `node_modules`, `.git`, and build output directories. Ask Claude to regenerate the export if needed. **Some components look different after migration** — Clark preserves styles where possible, but some UI patterns may render slightly differently in Superblocks. You can edit any component directly after the import completes. **Integrations aren't connecting** — Verify that the integration is configured in your Superblocks workspace before importing. You can add integrations from the [Integrations page](/integrations/overview) and then reconnect them from within the imported app. # Overview Source: https://docs.superblocks.com/building-with-clark/import-app/index Bring apps from Replit, Lovable, v0, Claude, or any other tool into Superblocks Import apps you've prototyped in other tools — Replit, Lovable, v0, Claude, or any other third-party tool — and turn them into production-ready applications on your enterprise data. Upload a zip of your project and Clark handles the rest: rewriting code to use Superblocks integrations, connecting to your real data sources, and replacing prototypes to production ready applications with platform-managed authentication and RBAC. ![](https://mintcdn.com/superblocks/oaNT4sOYeJo3eCfB/building-with-clark/import-app/choose-source.png?fit=max\&auto=format\&n=oaNT4sOYeJo3eCfB\&q=85\&s=c2612a7b9819a436a4a783e827afc161) ## What gets migrated Clark analyzes your source code and automatically replaces external dependencies with Superblocks platform features: | Source app | Superblocks | | - | - | | Database clients (`pg`, `knex`, Prisma, Supabase) | [Integrations](/integrations/overview) connected to your enterprise databases | | Hardcoded API keys and secrets | Credentials managed by the platform | | Custom auth (Passport, JWT, Supabase Auth) | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | Express routes, Deno functions | [Backend APIs](/building-with-clark/backend-apis) | | Frontend pages and components | React pages hosted on the platform, preserving your design and styles | ## Supported platforms For step-by-step instructions, choose your source platform: > [card] [From Lovable](/building-with-clark/import-app/lovable) > > Import a Lovable project into Superblocks > [card] [From Replit](/building-with-clark/import-app/replit) > > Import a Replit project into Superblocks > [card] [From v0](/building-with-clark/import-app/v0) > > Import a v0 project into Superblocks > [card] [From Claude](/building-with-clark/import-app/claude) > > Import a Claude-generated project into Superblocks > [card] [From ChatGPT](/building-with-clark/import-app/chatgpt) > > Import a ChatGPT-generated project into Superblocks > [card] [Other app](/building-with-clark/import-app/other) > > Import any app via zip upload — Bolt, Cursor, Windsurf, or your own project # Lovable import Source: https://docs.superblocks.com/building-with-clark/import-app/lovable Migrate a Lovable app into Superblocks with Clark Import a Lovable app into Superblocks and turn your prototype into a production-ready application connected to your enterprise data, with platform-managed authentication and RBAC. ## Before you begin Make sure you have: * A Lovable project you want to migrate * Access to the Superblocks workspace where the app will live * The integrations (databases, APIs) you plan to connect already configured in Superblocks ## How to import from Lovable **1. Start the import** From the Superblocks home screen, click **Import** in the prompt bar, or click the **Import an app** link below it. **2. Select Lovable as your source** When prompted to choose a platform, select **Lovable**. **3. Export your project from Lovable** Superblocks provides a ready-made export prompt. Copy it and paste it into the Lovable chat — Lovable will build you a `LovableExport.zip`. Download the zip from Lovable once it's ready. ![Superblocks migration Export step for Lovable: copy export prompt, build LovableExport.zip in Lovable chat, then download](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/lovable-export.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4b56c3273612413539feda8a1b1efe78) **4. Upload the zip** Drop the downloaded zip file into the Superblocks upload area and click **Import**. ![Migration Upload step: drag-and-drop zone for .zip, .tgz, or .gz archives with Import app button](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/upload-project.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4a69e8878e34f02320c597e930dbd593) **5. Clark migrates the app** Clark inspects your project structure and imports what it can, including: * **Code** — your app's source files and logic * **Design and styles** — layouts, component styles, and visual structure * **Backend functionality** — any server-side logic Clark detects Clark then rewrites the code to run on Superblocks: | Lovable | Superblocks | | - | - | | Supabase client and queries | [Integrations](/integrations/overview) connected to your databases | | Hardcoded API keys and secrets | Credentials managed by the platform | | Supabase Auth | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | React pages and components | React pages hosted on the platform, preserving your design and styles | You'll be prompted to connect your integrations — pick the databases, APIs, and services the app should use in your environment. ## What gets migrated Clark analyzes the Lovable source code and replaces external dependencies with Superblocks platform features. Most React components, layouts, and styles migrate as-is. Logic that depends on Supabase or other Lovable-specific services is rewritten to use your connected integrations. ## Troubleshooting **The zip won't upload** — Make sure the zip contains your project's root folder and excludes `node_modules`, `.git`, and build output directories. Re-run the export prompt in Lovable if needed. **Some components look different after migration** — Clark preserves styles where possible, but some Lovable-specific UI libraries may not have a direct equivalent. You can edit any component directly in Superblocks after the import completes. **Integrations aren't connecting** — Verify that the integration is configured in your Superblocks workspace before importing. You can add integrations from the [Integrations page](/integrations/overview) and then reconnect them from within the imported app. # Other app import Source: https://docs.superblocks.com/building-with-clark/import-app/other Import any app into Superblocks with Clark using a zip upload Import any app into Superblocks by uploading a zip of your project. This works for apps built with any tool — Bolt, Cursor, Windsurf, or your own codebase. ## Before you begin Make sure you have: * A project zip ready to upload * Access to the Superblocks workspace where the app will live * The integrations (databases, APIs) you plan to connect already configured in Superblocks ## How to import **1. Start the import** From the Superblocks home screen, click **Import** in the prompt bar, or click the **Import an app** link below it. **2. Prepare your zip** Zip your project's root folder. Before zipping, remove the following to keep the file size small: * `node_modules/` * `.git/` * Build output directories (`dist/`, `build/`, `.next/`, etc.) **3. Upload the zip** On the Superblocks import screen, select the **Other** option when prompted for a source. ![Superblocks migration Export step for a generic or custom source: package the project before continuing](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/general-app-export.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=c2fb8b3ea4d64becf86cf3fddff839b9) Drop your zip file into the upload area and click **Import**. ![Migration Upload step: drag-and-drop zone for .zip, .tgz, or .gz archives with Import app button](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/upload-project.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4a69e8878e34f02320c597e930dbd593) **4. Clark migrates the app** Clark inspects your project structure, identifies frameworks, data sources, and pages, then rewrites the code to run on Superblocks: | Source app | Superblocks | | - | - | | Database clients (`pg`, `knex`, Prisma, Supabase) | [Integrations](/integrations/overview) connected to your enterprise databases | | Hardcoded API keys and secrets | Credentials managed by the platform | | Custom auth (Passport, JWT, Supabase Auth) | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | Express routes, Deno functions | [Backend APIs](/building-with-clark/backend-apis) | | Frontend pages and components | React pages hosted on the platform, preserving your design and styles | You'll be prompted to connect your integrations — pick the databases, APIs, and services the app should use in your environment. ## What gets migrated Clark analyzes your source code and replaces external dependencies with Superblocks platform features. Frameworks Clark works well with include React, Next.js, Vue, and plain HTML/JS. Backend logic written as Express or Deno routes is rewritten as Superblocks Backend APIs. ## Troubleshooting **The zip is too large** — Remove `node_modules/`, `.git/`, and any build output before zipping. These directories are not needed for the import. **Clark can't identify the framework** — Make sure your project has a `package.json` at the root and that framework dependencies (e.g. `react`, `next`, `vue`) are listed. Add a brief `README` describing the project structure if the layout is non-standard. **Some components look different after migration** — Clark preserves styles where possible, but some UI libraries may not have a direct equivalent in Superblocks. You can edit any component directly after the import completes. **Integrations aren't connecting** — Verify that the integration is configured in your Superblocks workspace before importing. You can add integrations from the [Integrations page](/integrations/overview) and then reconnect them from within the imported app. # Replit import Source: https://docs.superblocks.com/building-with-clark/import-app/replit Migrate a Replit app into Superblocks with Clark Import a Replit app into Superblocks and turn your prototype into a production-ready application connected to your enterprise data, with platform-managed authentication and RBAC. ## Before you begin Make sure you have: * A Replit project you want to migrate * Access to the Superblocks workspace where the app will live * The integrations (databases, APIs) you plan to connect already configured in Superblocks ## How to import from Replit **1. Start the import** From the Superblocks home screen, click **Import** in the prompt bar, or click the **Import an app** link below it. **2. Select Replit as your source** When prompted to choose a platform, select **Replit**. **3. Export your project from Replit** Superblocks provides a ready-made export prompt. Copy it and paste it into the Replit AI chat. Replit will package your project into a downloadable zip file. ![Superblocks migration flow on the Export step: copy export prompt, use Replit chat to build ReplitExport.zip, then download](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/replit-export.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=ed54ee7834eb388646e823b8b87f11a5) Download the zip once Replit finishes building it. **4. Upload the zip** Drop the downloaded zip file into the Superblocks upload area and click **Import**. ![Migration Upload step: drag-and-drop zone for .zip, .tgz, or .gz archives with Import app button](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/upload-project.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4a69e8878e34f02320c597e930dbd593) **5. Clark migrates the app** Clark inspects your project structure, identifies frameworks, data sources, and pages, then rewrites the code to run on Superblocks: | Replit | Superblocks | | - | - | | Database clients (`pg`, `knex`, Prisma) | [Integrations](/integrations/overview) connected to your databases | | Hardcoded API keys and secrets | Credentials managed by the platform | | Custom auth (Passport, JWT) | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | Express routes, Deno functions | [Backend APIs](/building-with-clark/backend-apis) | | Frontend pages and components | React pages hosted on the platform, preserving your design and styles | You'll be prompted to connect your integrations — pick the databases, APIs, and services the app should use in your environment. ## What gets migrated Clark analyzes the Replit source code and replaces external dependencies with Superblocks platform features. Most frontend components, layouts, and styles migrate as-is. Backend routes and server-side logic are rewritten as Superblocks Backend APIs, and database clients are replaced with your connected integrations. ## Troubleshooting **The zip won't upload** — Make sure the zip contains your project's root folder and excludes `node_modules`, `.git`, and build output directories. Re-run the export prompt in Replit if needed. **Some components look different after migration** — Clark preserves styles where possible, but some Replit-specific packages may not have a direct equivalent. You can edit any component directly in Superblocks after the import completes. **Integrations aren't connecting** — Verify that the integration is configured in your Superblocks workspace before importing. You can add integrations from the [Integrations page](/integrations/overview) and then reconnect them from within the imported app. # v0 import Source: https://docs.superblocks.com/building-with-clark/import-app/v0 Migrate a v0 app into Superblocks with Clark Import a v0 app into Superblocks and turn your prototype into a production-ready application connected to your enterprise data, with platform-managed authentication and RBAC. ## Before you begin Make sure you have: * A v0 project you want to migrate * Access to the Superblocks workspace where the app will live * The integrations (databases, APIs) you plan to connect already configured in Superblocks ## How to import from v0 **1. Start the import** From the Superblocks home screen, click **Import** in the prompt bar, or click the **Import an app** link below it. **2. Select v0 as your source** When prompted to choose a platform, select **v0**. **3. Export your project from v0** You have two options: * Open your project in v0 and click the **download icon** to save it as a zip, or * Push the project to source control from v0, then download the repo as a zip from source control. ![Superblocks migration Export step for v0: export and package instructions](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/v0-export.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=5c25e4c85f4367d34697c2633509f87d) **4. Upload the zip** Drop the downloaded zip file into the Superblocks upload area and click **Import**. ![Migration Upload step: drag-and-drop zone for .zip, .tgz, or .gz archives with Import app button](https://mintcdn.com/superblocks/U5RkhXSSu8k-JEr-/images/import-apps/upload-project.png?fit=max\&auto=format\&n=U5RkhXSSu8k-JEr-\&q=85\&s=4a69e8878e34f02320c597e930dbd593) **5. Clark migrates the app** Clark inspects your project structure and imports what it can, including: * **Code** — your app's source files and logic * **Design and styles** — layouts, Tailwind classes, and component styles * **Backend functionality** — any server-side logic Clark detects Clark then rewrites the code to run on Superblocks: | v0 | Superblocks | | - | - | | Hardcoded API calls and fetch requests | [Integrations](/integrations/overview) connected to your data sources | | Hardcoded API keys and secrets | Credentials managed by the platform | | Custom auth | Platform-managed [authentication and RBAC](/admin/org-administration/rbac) | | React pages and components | React pages hosted on the platform, preserving your design and styles | You'll be prompted to connect your integrations — pick the databases, APIs, and services the app should use in your environment. ## What gets migrated Clark analyzes the v0 source code and replaces external dependencies with Superblocks platform features. v0 projects are React-based with Tailwind and shadcn/ui components, which migrate well — layouts, styles, and component structure are preserved as closely as possible. ## Troubleshooting **The zip won't upload** — Make sure the zip contains your project's root folder and excludes `node_modules`, `.git`, and build output directories. **Some components look different after migration** — Clark preserves styles where possible, but some shadcn/ui or Radix primitives may render slightly differently in Superblocks. You can edit any component directly after the import completes. **Integrations aren't connecting** — Verify that the integration is configured in your Superblocks workspace before importing. You can add integrations from the [Integrations page](/integrations/overview) and then reconnect them from within the imported app. # Building with Clark AI Source: https://docs.superblocks.com/building-with-clark/index Clark is the AI coding agent for building secure internal apps on top of private enterprise data [YouTube video player](https://www.youtube.com/embed/D_g6lDnX7eI) Watch Clark build an Uber Eats admin panel on top of Postgres, Databricks, Anthropic, Salesforce, and Slack in 15 minutes. Learn about Clark on integrations, plan mode, build mode, files, and automated app testing. To start building with Clark, create a new application in Superblocks, then describe your application requirements in the prompt box. When prompting, you can: * [Tag integrations](/building-with-clark/tagging-integrations) to specify data sources * Ask questions and create detailed prompts in [Plan mode](/building-with-clark/plan-and-build-modes#plan-mode) * Create and edit your app in [Build mode](/building-with-clark/plan-and-build-modes#build-mode) * [Add detailed context](/building-with-clark/adding-context) by targeting application elements and uploading files like screenshots, CSVs, and more * Track changes, preview, and publish with [Checkpoints & publishing](/building-with-clark/checkpoints) # App knowledge Source: https://docs.superblocks.com/building-with-clark/knowledge/app-knowledge Teach Clark about app-specific architecture, business logic, and conventions App knowledge is scoped to a single application. Think of it like an `agents.md` or [agent skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) for your app — a set of persistent instructions that Clark follows every time it works in this app. ## Adding app knowledge To teach Clark knowledge about your app, simply tell it what to remember in the chat. For example: * "Remember that this app uses a master-detail layout — left panel is always a filterable list, right is the selected item's details." * "Remember that all monetary values are stored in cents and should be displayed as dollars with two decimal places." * "Remember that the fetchOrders API must always include a `storeId` filter." Clark will extract the key instruction, propose a knowledge entry, and save it once you approve. From that point on, Clark references this knowledge automatically in every conversation within the app. You can also click the **knowledge icon** in the chat toolbar and select **Add knowledge** — this injects a prompt that tells Clark to identify useful insights from the current conversation to add to the knowledge base. ![Add knowledge from the chat toolbar](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/toolbar-add.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=a37e1afe90cfbec4b5dc0215f33f9ca1) ## Viewing and managing app knowledge To view all app knowledge, click the **knowledge icon** in the chat toolbar and select **View knowledge**. You can also click through from a new knowledge entry in the chat after Clark saves one. ![View knowledge from the chat toolbar](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/toolbar-view.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=7d195380e15d63413c1402f4b679455d) This opens the knowledge panel where you can review all saved entries and disable or delete individual ones. ![Knowledge panel showing saved entries](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/knowledge-panel.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=767498adf81991a5b6555ee0e00d8110) ## What to capture App knowledge is useful for details like: * **Architecture decisions** — state management approach, component hierarchy, routing patterns * **Business logic** — domain rules specific to this app, calculation methods, validation requirements * **Data dependencies** — which APIs power which views, refresh patterns, caching strategies * **UI conventions** — layout patterns, component reuse rules, interaction behaviors specific to this app ## How it works Clark doesn't load all app knowledge upfront. Instead, it looks up relevant entries on the fly using progressive disclosure — pulling in only the knowledge that's relevant to what you're currently working on. You don't need to reference specific knowledge entries in your prompts. For knowledge that applies beyond a single app, see [Organization Knowledge](/admin/org-administration/knowledge), [Integration Knowledge](/integrations/knowledge), or [User Knowledge](/building-with-clark/knowledge/user-knowledge). # Knowledge Source: https://docs.superblocks.com/building-with-clark/knowledge/index Define persistent context that Clark follows by default across all conversations Clark stores and retrieves memories across conversations. Admins can add memory, and Clark will automatically learn with every builder prompt. This enables Clark to navigate scaled databases, complex SaaS instances, and undocumented APIs as they evolve. You can define knowledge at four levels so Clark always has the right context without you repeating yourself: 1. **[Organization](/admin/org-administration/knowledge)** — org-wide standards like design systems, coding conventions, and domain terminology 2. **[Integration](/integrations/knowledge)** — data source details like schema quirks, query patterns, and API behavior 3. **[User](/building-with-clark/knowledge/user-knowledge)** — personal preferences for how Clark works with you 4. **[App](/building-with-clark/knowledge/app-knowledge)** — app-specific architecture, business logic, and UI conventions ## Platform knowledge vs. app knowledge Knowledge is split into two categories: **Platform knowledge** — Organization, Integration, and User knowledge are defined and managed outside of any individual app. They apply across your entire Superblocks environment and are configured by admins (org and integration) or individual users (personal preferences). See [Organization Knowledge](/admin/org-administration/knowledge) and [Integration Knowledge](/integrations/knowledge) for setup details. **App knowledge** — defined within a specific application and scoped to Clark conversations in that app. Builders configure this directly in the app settings. See [App Knowledge](/building-with-clark/knowledge/app-knowledge) for details. ## How knowledge is applied Clark looks up relevant knowledge on the fly using progressive disclosure — pulling in only the entries that are relevant to what you're currently working on. You don't need to reference knowledge in your prompts. 1. **Organization knowledge** — always included 2. **Integration knowledge** — included when the relevant integration is used 3. **User knowledge** — always included for the current user 4. **App knowledge** — included when working within the relevant app Enabling too many knowledge entries at once can reduce Clark's effectiveness. Keep entries focused and disable any that aren't actively needed. # User knowledge Source: https://docs.superblocks.com/building-with-clark/knowledge/user-knowledge Set personal preferences for how Clark works with you User knowledge is personal — it applies only to your own Clark conversations across all apps. Use it to capture your individual preferences so Clark adapts to how you like to work — things like code style, workflow preferences, and the types of apps you typically build. ## Adding user knowledge Navigate to the **Knowledge** page and chat with Clark to describe what you want it to remember. Clark will create the right knowledge entry at the right scope for you, then present it for your review before saving. We recommend using Clark to write entries because it optimizes them for LLM retrieval — producing focused, well-structured instructions that Clark can look up effectively at build time. For example, you might tell Clark: * "I prefer TypeScript over JavaScript. Always use typed interfaces for API responses." * "When presenting options, give me a brief summary — I don't need long explanations." * "I primarily build data-heavy dashboard apps. Optimize for table and chart components." Clark will draft the entry, scope it to **Personal**, and present it for your review before saving. ![Clark creating a personal knowledge entry](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/user-knowledge.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=1c6432e98f639cedc5635dddaf142fa7) You can also ask Clark to **explore your existing knowledge**, refine entries, or identify duplicates — for example, "Review my personal knowledge and suggest anything I should add based on how I've been building." ## Permissions User knowledge is private. Only you can see and manage your entries, and they are only used in your own Clark conversations. ## Related User knowledge is part of Clark's broader [Knowledge](/building-with-clark/knowledge) system. You can also define knowledge at the [organization](/admin/org-administration/knowledge), [integration](/integrations/knowledge), and [app](/building-with-clark/knowledge/app-knowledge) levels. # Upgrade 2.0 apps to 3.0 Source: https://docs.superblocks.com/building-with-clark/migrate-to-typescript Upgrade legacy Clark apps from YAML APIs to TypeScript APIs (Superblocks 3.0) In this guide, **2.0** means the earlier Clark app format (YAML APIs, flat project layout). **3.0** means the current format (TypeScript APIs under a `client/` and `server/` layout). Apps built with Clark before April 2026 are often still on 2.0. Upgrading to 3.0 makes Clark faster and more accurate and unlocks the latest editor and Git features. Clark runs the upgrade for you, rewriting and testing your APIs. The change is one-way once you finalize. ## How do I know if my app is on 2.0? Open the app in the editor. If it is still on 2.0, you will see a banner that lets you **Upgrade**. If you can open the **Code** tab (`< >`) and view the app source, the app is already on 3.0 and will not show the upgrade banner. ## Why upgrade? | Benefit | What you get | | - | - | | **Faster, more accurate Clark** | Quicker, more reliable builds and edits, especially for APIs | | **Revamped editor** | Inspect code and watch each API run as it is triggered | | **Sync to source control** | Connect the app to your Git repository of choice | For how TypeScript APIs work after upgrade, see [Backend APIs](/building-with-clark/backend-apis). ## Features that need alternatives in 3.0 Some 2.0 patterns are not supported the same way in 3.0 apps: * **Custom backend libraries** used inside APIs * **Environment variables** in APIs (removed for credential security; use integrations and secrets instead) * **One-off REST requests** (ad hoc REST steps outside a configured REST integration) * **Python** API steps Clark will help you find alternatives during the upgrade. If you need additional support, [contact us](/enterprise/support/help). ## How to upgrade **1. Start the upgrade** Open your application in the Superblocks editor, then click the **Upgrade** button in the banner at the top of the page. ![Application banner with button to upgrade](https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/upgrade_banner.png?fit=max\&auto=format\&n=7CbbcscP4WvIOOp8\&q=85\&s=a041a6829c2b683f99a316ef215622f3) **2. Confirm and begin migration** Confirm the migration details and settings, including adjustment of API write permissions to prevent Clark from testing APIs that write to sensitive integrations. Click **Upgrade now** to start the migration. ![Application modal with upgrade details for user to confirm](https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/upgrade_confirmation.png?fit=max\&auto=format\&n=7CbbcscP4WvIOOp8\&q=85\&s=303a04361298e604dd828e0c7273c7bf) **3. Let Clark migrate and test** Clark will create a checklist and get to work migrating and testing your application. At any point in time you can select **Abort migration** to restore the previous version. ![Application in the process of migration](https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/migrating.png?fit=max\&auto=format\&n=7CbbcscP4WvIOOp8\&q=85\&s=0e8dd87bb53b7d2fa8fbd659bd4d049e) **4. Finish and finalize** Finalizing permanently deletes the pre-upgrade backup. You cannot abort or roll back to the 2.0 app after that. Clark also loses access to the legacy API code as a reference for future edits. Once the upgrade completes and you are satisfied with the results, click **Finish upgrade** then **Finalize upgrade** to confirm. ![Button to finish upgrade](https://mintcdn.com/superblocks/7CbbcscP4WvIOOp8/images/building-with-clark/finish_migration.png?fit=max\&auto=format\&n=7CbbcscP4WvIOOp8\&q=85\&s=130a5d503cc902f04356e0f5acbfc3ad) ## Abort and restore To cancel the upgrade at any point, click **Abort upgrade**, then confirm with **Abort and restore**. Aborting does the following: * Upgrade progress is discarded * Clark generation stops * The app restores to the pre-upgrade backup checkpoint * Clark chat context is cleared * The page reloads when restore finishes ## Troubleshooting ### APIs could not be upgraded or verified * Use **Fix with Clark** for APIs that failed conversion * Use **Get testing instructions** when Clark could not auto-test some APIs (for example write APIs you blocked from testing) * Manually verify those APIs before you finalize ### Unsupported integrations The upgrade details modal may also list specific integrations that are not fully supported in 3.0 for your app. Clark still attempts the upgrade, but those APIs may need manual attention. See [Features that need alternatives in 3.0](#features-that-need-alternatives-in-30). ## Related * [Backend APIs](/building-with-clark/backend-apis) * [Developing apps in code](/building-with-clark/developing-apps-in-code) * [Connect to Git](/development-lifecycle/version-control/connect-to-git) # Plan & Build modes Source: https://docs.superblocks.com/building-with-clark/plan-and-build-modes Work with Clark to create a detailed prompt in Plan mode, then execute in Build mode Prompting supports two modes: **Plan** and **Build**. Plan mode is especially helpful when you're getting started—you can explore integration data and structure, clarify requirements, review strategy, and refine the prompt before building. Once you're satisfied with the plan, switch to Build mode, where Clark executes the prompt to create or update your application. ## Plan mode You can interact with Clark in **Plan** mode to craft a detailed prompt before building. In this mode, Clark leverages read-only tools and will not make any changes to your application. Below are common actions Clark takes in Plan mode. ### Inspecting integration metadata and running one-off queries Clark checks integration metadata such as REST API specs and SQL table schemas to determine what resources to query. Similarly, Clark can run one-off queries to those data sources to read sample data and better understand its structure for rendering the UI. ![Clark runs one-off queries in plan mode](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/plan_query.png) ### Prompting for clarification around key features and design choices Clark asks questions to understand the application's required functionality, design, layout, and more. You can answer by selecting one of the multiple choice options or clarifying in the main chat. ![Clark asks clarifying questions in plan mode](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/plan_question.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=e0977f5ddb950699dbc9e50012a23b80) ### Generating the plan Once Clark fully understands the data, features, and implementation strategy, a plan is generated. You can reply back to edit the plan or click **Build it** to switch modes and have Clark start creating the application. ![Clark generated detailed application plan](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/final_plan.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=c23aca9a272f5ec4e23e204a748a05b4) ## Build mode In **Build** mode, Clark gets to work creating the application. You can use Build mode on its own without any planning, which is ideal for smaller targeted edits or detailed prompts you've prepared ahead of time. ![Clark in Build mode](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/building-with-clark/build_start.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=6aa58abc9bcdc9237bfaf63498576b31) In this mode, Clark uses various build tools to perform operations including: * Creating pages and component files * Writing and compiling backend APIs * Installing libraries You can expand these tool calls in the chat to inspect details around Clark's thought process and the generated code. ![Clark creating files](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/building-with-clark/build_create_files2.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=75789de4f4fe156c4cf77f0a945fc681) ### Testing and debugging In the same way Clark acts like a human engineer in Plan mode by running one-off queries and checking API responses, Clark performs similar actions in Build mode to iteratively test, debug, and edit features as they're built. This includes: * Testing APIs * Checking code for issues * Checking for runtime errors and inspecting console logs * Capturing screenshots to confirm UI renders as expected ![Clark testing APIs](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/build_test_apis.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=663be7d6ea2e0fb57fb35950915ad0e7) ![Clark testing APIs](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/build_test_apis_2.png?fit=max\&auto=format\&n=tt5q66tB8IiNvsPL\&q=85\&s=b2488d227c8e64c48aa7f8f9d6cd6865) ![Clark in Build mode debugging](https://mintcdn.com/superblocks/bKXJZ0WLJtmaDm_J/images/building-with-clark/build_debugging.png?fit=max\&auto=format\&n=bKXJZ0WLJtmaDm_J\&q=85\&s=5f4c47befb285c6690200a98765ae2a3) Once all requirements are fulfilled and checks pass, Clark finalizes the app, making it available for you to interact with and continue building. ![Clark completes first build](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/build_final_app.png) # Prompt engineering Source: https://docs.superblocks.com/building-with-clark/prompt-engineering Best practices and examples for prompting Clark AI to generate high-quality Superblocks applications ## Understanding prompting in Superblocks ### Introduction Prompting is your primary interface for communicating with Clark through written instructions. Think of it like giving instructions to a skilled developer who can see your screen and build components in real time but needs clear direction to understand exactly what you want. Clark operates using large language models (LLMs), which means the precision and quality of your prompts directly correlate with the effectiveness of the results you receive. The fundamental principle: **Great prompts = Great outputs.** ### Why prompt engineering matters Effective prompting is the difference between getting basic responses and unlocking Clark's full potential for complex problem-solving. Understanding how to communicate with Clark enables users across all technical backgrounds to achieve significantly better results. For developers: * Generate sophisticated components following specific architectural patterns and design principles * Debug complex issues using targeted, systematic problem-solving methodologies * Automate repetitive development tasks through precise, reusable instruction sets For non-technical users: * Construct advanced workflows and business processes without requiring coding expertise * Generate database queries and API integrations using conversational language * Convert high-level business requirements into functional, deployable applications Clark has the ability to deliver production-ready, enterprise-grade solutions and this guide will demonstrate how to do that most effectively. ## One-shot vs iterative prompting **Use one-shot when**: * Requirements fit in 2-3 sentences with a single clear outcome * You have a well-defined task with clear specifications * Building simple components with straightforward functionality **Use iterative when**: * Requirements need explanation or have multiple possible approaches * You're not sure exactly what the end result should look like * Working on complex features or exploratory development * You need flexibility to refine and adjust as you build **Best practice:** Start with one-shot for simple, well-defined tasks, then switch to iterative when requirements become unclear or complex. You can also combine both approaches - use one-shot for initial creation, then iterative for improvements and refinements. ## Example: Building a data table with filtering Scenario: We work for Dunder Mifflin paper company and need to build an internal application to manage inventory and sales. The below image is the application we need to build: ![Inventory dashboard with filters, metrics, table, and chart](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/dunder-mifflin-final.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=170528857f77bd7d4557c8b90aa81de4) ### One-shot approach Ask Clark to build the complete data table component all at once, including the header, filter bar, table display and filtering logic in a single comprehensive prompt. This works well when you have a clear vision of the final component and understand exactly how all the pieces should work together. ### Iterative approach Break the component down into logical building blocks: #### Step 1 - header section & filter (UI only) Break the application into pieces starting with the header and filter bar. Write the prompt to focus only on the UI. Sample prompt: ``` Create the Header Section at the top of the application. - Include a logo at the top left - Next to the company logo include the application name - Add user profile component in top right to identify who is currently logged into the app. Include the full name and email address Underneath the header section, create a filter section with all of the components aligned horizontally: - Add dropdowns for location and paper category filtering. Set their width to "Fill Parent" - Add "Apply Filters" and "Reset" buttons and set their width to "Fill Parent" ``` #### Step 2 - metric cards (UI only) Add a simple prompt describing the metric card UI beneath the results in Step 1. Sample prompt: ``` Underneath the filter section, create a section with 4 metrics cards. - Display the metric card components horizontally - In the metrics cards display stats for 'Total Inventory', 'Low Stock Items', 'Pending Orders' and 'YTD Sales' ``` #### Step 3 - data table & chart (UI only) Create the main content area with a split layout containing a table and a chart. This will fill the rest of the page. Continue iterating on the UI as needed. Sample prompt: ``` Underneath the metric card section, create the main dashboard body: - Have the left panel reflect an inventory table (70% width) - The right panel to show an analytics chart (30% width) - Set the height for both panels to "Fill Parent" ``` #### Step 4 - add data to the table Add data to each component using the integrations connected to your Superblocks instance. To add extra context, use the '@' symbol to tag the specific integration you'd like to pull data from. Sample prompt: ``` Using the @DunderMifflin integration, create an API to fetch all inventory data and populate the table. ``` #### Step 5 - add logic Once data is connected, start tying different components together and adding logic to your application. The below example adds filter logic to the table and actions on a button click. Sample prompt: ``` When users click "Apply Filters" or select dropdown options, run the API with applied filters. If a filter is 'all', pass along all values. ``` ### Why This Iterative Approach Works Better * **Progressive complexity:** Each step builds naturally on the previous one, making it easier to spot issues early and adjust the approach. * **Easier debugging:** When problems arise, you know exactly which piece isn't working rather than debugging a complex component with multiple interconnected systems. * **Flexibility:** You can change direction between steps if you realize a different filtering approach would work better after seeing the table in action. * **Better testing:** You can test each component piece individually to ensure it works correctly before adding the next layer of complexity. * **Frontend-first development:** Clark builds the visual interface first, allowing you to see and understand how components fit together. Once the layout and user experience are solid, the underlying logic becomes easier to implement correctly. ## Tips and Tricks ### Adding images to prompts Detailed prompts yield better results and images take this even further. Include a screenshot or wireframe to convey layout, hierarchy and component states. To an LLM, a picture really is worth a thousand words. When you add an image, briefly specify what to focus on (e.g., filters, metrics, table columns) so Clark extracts the right details. Click the image icon when prompting to upload an image. ![Upload Image](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/image_upload.gif?s=eeff71e57eb10756da9d9a16ef4dd2b7) ### Targeting specific components and APIs Targeting specific components, APIs and data sources in your prompt significantly improves Clark's accuracy. When making iterative changes, target relevant items as often as possible. Use the methods below. #### Tagging the frontend Add UI components to your prompt in either of these ways: * Hover over a component and click the Target button. * Or click the Target button in the chat sidebar to enable target mode, then click components to add them. ![Upload Image](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/tagging_frontend.gif?s=38b2af38cea21e250990e47a31a32226) #### Tagging a backend API Add a backend API to your prompt by opening the API, clicking the three-dot menu, then selecting "Add to chat." ![Upload Image](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/tagging_backend.gif?s=1aea821b1286160f1137db9f13c04f5c) #### Tagging a data source Add a data source by opening the integration, clicking the three-dot menu, then selecting "Add to chat." You can also reference it directly with `@IntegrationName` (e.g., `@DunderMifflin`). ![Upload Image](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/tagging_datasource.gif?s=91df8fa3535d3f55f97da3bc237c1534) ### Discarding Clark outputs Discarding a generation can feel counterintuitive but it often saves time. When Clark's output misses your intent — due to missing detail or a model hallucination — use the Discard button to revert to the previous state. This gives you a clean baseline and a clearer path to add the right context for a more accurate next iteration. Note: A hallucination is confident sounding output that's actually incorrect. When generating an application or API, this will result in an output different from what the prompt asked for. ### Using Rollbacks and Commits Rollbacks let you restore the app to any previous generation. Clark automatically creates a rollback when it finishes a Build mode generation that changes your app. Open the History/Rollbacks panel, choose a version and confirm to restore. ![Upload Image](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/rollbacks.gif?s=c2648274acf20e8f5fea9eee78b95672) Commits can be added after milestones during the building journey. This establishes clear progress in development and can be rolled back to if needed. ![Upload Image](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/generative-ai/clark-ai-prompting-guide/commits.gif?s=e74c8d4e1aade54243a85d5b6ce94a26) # Access controls in apps Source: https://docs.superblocks.com/building-with-clark/rbac Use groups and user identity to control what users can see and do in your app Clark builds secure access control into your app by default. When you describe who should see what, Clark puts authorization checks in the right place, filtering data in backend APIs using the authenticated user's identity and adjusting the UI to match. This guide covers the concepts behind in-app access control and how to prompt Clark to build it into your app. ## How it works ### User identity Every backend API in Superblocks has access to the current user's identity through `ctx.user`. This is populated from the authenticated session and can't be modified by the end user or passed in from the frontend. | Property | Description | | - | - | | `ctx.user.userId` | Unique user identifier | | `ctx.user.email` | User's email address | | `ctx.user.name` | Display name | | `ctx.user.groups` | Array of group names the user belongs to | | `ctx.user.metadata` | Custom metadata passed via embed session tokens (embedded apps only) | When you ask Clark to restrict access, it uses `ctx.user` in backend API code to gate access or filter data. This is the secure path because the identity comes from the server, not the browser. ### Groups Groups are the main building block for access control. They map to your identity provider (Okta, Azure AD, etc.) via SCIM sync, or can be managed manually in Organization Settings. For example, a user in the `"finance-admins"` group might see all invoices, while a user in `"finance-viewers"` can only see their own department's records. ### Backend vs. frontend checks Clark enforces access control in two layers: | Layer | What it does | Example | | - | - | - | | **Backend API** | Filters data and blocks unauthorized actions using `ctx.user` | Only return orders where `owner_email` matches the current user | | **Frontend** | Hides or disables UI elements for a better experience | Hide the "Delete" button for non-admins | Backend checks are the security boundary. Frontend checks improve the experience by not showing users things they can't access. Clark builds both layers when you describe the behavior you want. ## What Clark generates When you prompt Clark with access control requirements, it generates code like the following. **Backend — gating an entire API:** ```typescript theme={null} async run(ctx) { if (!ctx.user.groups.includes("admin")) { throw new Error("Access denied: admin group required"); } // ... rest of the API logic } ``` **Backend — filtering data by user identity:** ```typescript theme={null} async run(ctx) { const orders = await ctx.integrations.db.query( "SELECT * FROM orders WHERE owner_email = $1", OrderSchema, [ctx.user.email] ); return { orders }; } ``` **Frontend — conditional rendering based on group:** ```tsx theme={null} const isAdmin = user?.groups?.includes("admin"); if (!isAdmin) { return

You don't have access to this page.

; } ``` You don't need to write any of this yourself. Clark generates it from your prompt. These examples are here so you can recognize what Clark built and understand what it's doing. ## Common patterns ### Role-gated API access Restrict an entire API to users in a specific group. If the user isn't in the group, the API returns an error before accessing any data. **Good for:** Admin dashboards, sensitive operations (delete, export), management tools. ### Row-level security Filter query results using `ctx.user.email` or `ctx.user.userId` so users only see their own data. **Good for:** Multi-tenant apps, "my orders" views, user-specific dashboards. ### Feature-level gating Return different fields or allow different mutations depending on the user's group, without blocking the entire API. **Good for:** APIs that serve multiple roles (viewers see read-only data, editors can update). ### Frontend conditional rendering Hide buttons, tabs, or pages for users who don't have access. Clark pairs this with backend enforcement automatically. **Good for:** Navigation menus, action buttons, admin-only sections. ## How to prompt Clark ### Describe who and what Tell Clark which group should have access and what they should (or shouldn't) see. Be specific about group names. ``` Build an orders page. Admins (users in the 'admin' group) should see all orders. Regular users should only see their own orders. On the frontend, hide the 'Export All' button for non-admins. ``` Clark will build the backend API with `ctx.user` checks, filter the data query, and conditionally render the button, all from this single prompt. ### More examples **Gating an API:** ``` Only allow users in the 'admin' group to access this API. If they're not an admin, throw an access denied error. ``` **Row-level security:** ``` Filter the orders query so users can only see orders where the owner_email matches their own email. ``` **Multi-level access:** ``` Users in the 'manager' group can see all records in their department. Regular users can only see their own. ``` **Frontend UX:** ``` Show an 'Admin Settings' tab in the sidebar only for users in the 'org-admins' group. ``` ``` If the user doesn't have the 'editor' group, make the form fields read-only instead of hiding them. ``` ### Tips for better results | Tip | Why | | - | - | | Name the specific group (e.g., `"admin"`, `"finance-viewers"`) | Clark uses the exact group name in the check | | Mention both backend and frontend behavior | Clark builds the full pattern: API enforcement + UI polish | ## Setting up groups For in-app access control to work, your users need to be in the right groups: * **SCIM sync** (recommended): Sync groups from your IdP (Okta, Azure AD) automatically. See [Manage users and groups with SCIM](/admin/org-administration/auth/scim). * **Manual management**: Create and assign groups in Organization Settings. See [Managing user groups](/admin/org-administration/groups/managing-groups). * **Embed tokens**: Pass `groupIds` when generating session tokens for embedded users. See [Embedded app authentication](/hosting/embedded-apps/authentication). ## Related * [About user groups](/admin/org-administration/groups) * [Managing group permissions](/admin/org-administration/groups/managing-group-permissions) * [Superblocks RBAC (platform-level)](/admin/org-administration/rbac) * [Embedded app authentication & metadata](/hosting/embedded-apps/authentication) * [Backend APIs](/building-with-clark/backend-apis) * [Knowledge (teaching Clark persistent rules)](/building-with-clark/knowledge) # Superblocks in Claude Source: https://docs.superblocks.com/building-with-clark/superblocks-in-claude Build, edit, and publish governed Superblocks apps without leaving Claude Superblocks in Claude is in beta. Reach out to your Superblocks account team to request access. [https://www.youtube.com/embed/rwarTWtdvRY?si=pH-s0tQNustiG-Kt](https://www.youtube.com/embed/rwarTWtdvRY?si=pH-s0tQNustiG-Kt) ## Overview Superblocks in Claude lets you build in Superblocks without leaving Claude. Add Superblocks to Claude, then ask in plain language to import, build, edit, or publish an app. Clark does the work in Superblocks, and Claude opens your app in its built-in browser so you can click through it. Many builders and business users already prototype in Claude and want to take that work to production in a governed way. Superblocks in Claude meets them where they are, with no separate onboarding and no new tool to learn. The apps they ship land on Superblocks with your organization's guardrails already applied. ## What you can do * **Start a new app**: Ask Claude to build a new app in Superblocks and get an editor link back. * **Import an existing app**: Bring a prototype you built in Claude into Superblocks. Clark imports the app, replaces integrations with your governed data sources, and adds platform authentication and RBAC. * **Edit an app**: Describe a change and Clark starts building against your existing app. * **Publish an app**: Ask to deploy and get a deployed link back, after [Code Security](/admin/code-security/index) policies run. ## Set up Superblocks in Claude An admin of your Claude organization adds the Superblocks plugin once. Each user then installs it from the plugin marketplace in Claude Desktop. ### Admins: add the plugin to your organization You need the **Owner** or **Primary Owner** role in a Claude Team or Enterprise organization. **1. Download the plugin** Download the Superblocks plugin ZIP provided by your account team. Do not unzip it. **2. Upload the plugin** In Claude, go to **Organization settings > Plugins & skills**, select **Add > Upload a plugin**, and choose the plugin ZIP. **3. Make the plugin available to install** On the **Inventory** tab, open the menu at the end of the **Superblocks** row. Select **Default access**, then choose **Available to install**. Users in your organization can now install Superblocks from the plugin marketplace. **4. Check that the built-in browser is on** In **Organization settings > Cowork**, make sure **Built-in browser** is turned on so users can open their Superblocks apps in it. ### Admins: update the plugin When your account team sends a new version of the plugin ZIP: 1. Go to **Organization settings > Plugins & skills** and select the **Superblocks** row on the **Inventory** tab. 2. Open the plugin's menu, select **Upload new version**, and choose the new ZIP. 3. In **Version history**, open the newly uploaded version's menu and select **Make this the current version**. 4. Confirm that the newly uploaded version is marked **Current**. This is the version served to members. Uploading the ZIP alone does not make it current. Once it is marked **Current**, users get the new version the next time they start a session. To roll back, go to the plugin's **Version history**, open an earlier version's menu, and select **Revert to this version**. See [Manage plugins for your organization](https://claude.com/docs/plugins/admin) in the Claude docs for more plugin settings. ### Users: install the plugin Use **Cowork** mode, not **Chat**, when working with Superblocks. For a smoother experience, we recommend enabling **auto-approval mode** so Claude can continue without pausing for every tool call. Only enable it for tasks you trust. **1. Add the plugin** In Claude Desktop, open Cowork and select **+ > Plugins > Manage Plugins**. On the **Discover** tab, find **Superblocks** and select **Add**, then accept the prompts that appear. If Superblocks isn't listed, ask your Claude organization admin to add it. **2. Use the built-in browser** In Claude Desktop, go to **Settings > Cowork** and set **Preferred browser** to **Built-in browser** so Claude opens your Superblocks apps there. If **Built-in browser** isn't an option, ask your Claude organization admin to turn it on. **3. Configure your Superblocks instance** Start a new Cowork session and run `/configure`. When prompted, enter your [Superblocks instance URL](/enterprise/instance-urls), such as `https://app.superblocks.com` for Cloud US. **4. Sign in** Complete the OAuth sign-in flow in the browser window that opens. You can now build with Superblocks in Claude. ## How it works ### 1. Ask in natural language Prompt Claude the same way you already do: ``` "Import this app into Superblocks, connect it to our Postgres database, and send me the editor link." ``` ``` "Add an approvals table to my Superblocks expense app and publish it." ``` ### 2. Plan and refine with Clark Clark works with you conversationally in Cowork, just like in the Superblocks UI. Before building, it can ask clarifying questions about functionality, data, and design, inspect your integration metadata, and propose a plan in Cowork. You answer in the same Cowork session, and Clark refines its approach before it starts building. See [Plan & Build modes](/building-with-clark/plan-and-build-modes) for how this works in the editor. ### 3. Open your app in Claude's browser Claude opens your app in its built-in browser, where you can click through it and verify your changes. Return to Cowork to ask for another change, such as "make the table sortable." When you're ready, open the app in the Superblocks editor or share its deployed link. ## Governed by default Prototypes built directly in AI tools tend to hardcode credentials and reinvent auth and permissions app by app, which becomes a security risk and tech debt as they multiply. Superblocks applies governance at the platform level rather than per app: connected integrations, authentication, RBAC, and policies are managed centrally, so a change made once applies to every app. Apps you build from Claude inherit that same model automatically. * **Identity-aware**: Claude acts as you, with your identity resolved through your SSO provider and mapped to your permissions in Superblocks, so builders only do what their role allows. * **RBAC and integrations**: Imported apps are rewritten to use your connected [integrations](/integrations/overview) and platform-managed [authentication and RBAC](/admin/org-administration/rbac) instead of hardcoded credentials. * **Code Security**: Publishing runs [Code Security](/admin/code-security/index) policies, and every app keeps native version control and one-click deploy. ## Superblocks in Claude vs. Admin MCP Superblocks in Claude is for building apps. The [Admin MCP](/admin/mcp-server) is for administering the platform from AI coding agents like Cursor and Claude Code. ## Related > [card] [Import an app](/building-with-clark/import-app/index) > > Bring prototypes from Claude, Replit, Lovable, v0, and more into Superblocks today > [card] [Admin MCP](/admin/mcp-server) > > Connect AI coding agents like Cursor and Claude Code to administer your Superblocks org # Tagging integrations Source: https://docs.superblocks.com/building-with-clark/tagging-integrations Specify data sources in your prompts by tagging integrations Clark knows all the [integrations](/integrations) you have access to as a developer. To explore your available integrations, type the `@` sign in chat. Then scroll or filter the list to select a specific integration and tag it in your prompt. Clark will use any tagged integrations as the data sources for planning and building your application's backend APIs. ![](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/tagging_integrations.gif?s=1e3ae658fc20a2d3f86cbe9268784c0b) For database integrations, you can also use the arrow keys to inspect and tag metadata like schemas, tables, and columns. ![](https://mintcdn.com/superblocks/tt5q66tB8IiNvsPL/images/building-with-clark/tagging_integrations_detailed.gif?s=44198a7e0afd12367f110f67f07bfd2c) You can exclude mentioning integrations if you prefer to focus on frontend development first before connecting to a backend in later prompts. # Workflows Source: https://docs.superblocks.com/building-with-clark/workflows Automate business processes across your systems with AI-built workflows triggered by webhooks, schedules, Slack messages, emails, and more **Coming soon** - Workflows are coming to Superblocks soon. [Contact us](mailto:support@superblockshq.com) to join the early access list. ## Overview Workflows let you automate business processes that span multiple systems (databases, APIs, SaaS tools, and custom logic), triggered automatically on a schedule or from custom events in your systems via webhooks. Describe what you want to automate in natural language, and Clark builds your workflow end-to-end on top of your integrations. Superblocks Workflows are real TypeScript code (just like the backend APIs you already use in your applications) but triggered automatically by external events. ## What you can build * **Webhook automations** - Receive events from Stripe, GitHub, Segment, or any service and react with multi-step logic across your stack * **Scheduled jobs** - Run reports, sync data, or clean up resources on a cron schedule * **Slack-triggered workflows** - Let teams kick off approvals, lookups, or actions directly from Slack * **Email-triggered workflows** - Parse incoming emails to create tickets, route requests, or update records * **Cross-system orchestration** - Chain together database queries, API calls, AI models, and notifications into reliable automated pipelines ## How it works ### 1. Build with Clark Tell Clark what you want to automate, just like building a backend API today. Clark writes the workflow logic, wires up your integrations, and handles error cases. ``` "When a new order comes in via webhook from Shopify, enrich the customer from our Postgres database, run a fraud check against our ML model, and if approved, update the order status and send a confirmation via Slack." ``` Clark generates a complete TypeScript workflow using your connected integrations. You can inspect the code, test individual steps, and iterate, all from the same editor you use to build apps. ### 2. Add triggers Every workflow has one or more triggers. Choose from: | Trigger | Description | | - | - | | **Webhook** | HTTP endpoint that receives POST requests from any external service | | **Schedule** | Cron-based execution (every 5 minutes, daily at 9am, first Monday of the month) | | **Slack** | Activated by a message, slash command, or interaction in Slack | | **Email** | Activated by an incoming email to a generated address | ### 3. Deploy and monitor Deploy your workflow with one click. Superblocks handles execution reliability, retries, and observability. Every run is logged with full trace visibility (inputs, outputs, timing, and errors for each step) so you can debug production issues in seconds. ## Key capabilities ### Full integration access Workflows use the same integrations you've already configured in Superblocks: Postgres, Snowflake, REST APIs, Salesforce, and more. No separate configuration or credentials to manage. ### Secure by default Workflows execute on your On-Premise Agent, so sensitive data never leaves your network. All triggers are authenticated and audited. RBAC controls who can create, edit, and deploy workflows. ### Version controlled Like all Superblocks resources, workflows have native version control, automatic checkpointing, [Code Security](/admin/code-security/index) policies, and one-click deploy. They can also be synced to your Git provider for code review and audit. ## Use cases | Use case | Trigger | What it does | | - | - | - | | New user onboarding | Webhook (Auth0) | Create CRM record, provision accounts, notify team in Slack | | Daily revenue report | Schedule (9am daily) | Query Snowflake, format summary, post to #finance Slack channel | | Support escalation | Email | Parse email, create Jira ticket, assign based on priority, notify on-call | | Deployment notifications | Webhook (GitHub) | Track deploys, update status page, post changelog to Slack | | Approval flows | Slack (slash command) | Collect approval from managers via Slack buttons, update database, notify requester | | Data sync | Schedule (every 15 min) | Sync records between Salesforce and Postgres, log discrepancies | # Using data tags Source: https://docs.superblocks.com/development-lifecycle/build/data-tags Use data tags to control which data sources are accessed in each environment Data tags in Superblocks let you define named configurations — like **Production**, **Staging**, or **us-east** — and use them to control which data sources your apps connect to in each environment. * Use non-production data tags in Edit mode so developers (and Clark) can safely build and test without touching production data. * Assign production data tags to the Production environment to keep production data isolated. * Add multiple data tags to an environment (e.g., `us-east`, `us-west`, `eu-west`) to let users switch between regions in deployed apps. To create new data tags or configure which environments they're allowed in, see the [Manage environments & data tags](/admin/environments) admin guide. Hybrid customers: see [Plan your data planes](/enterprise/hybrid-architecture/plan/index). ## Set up data tags for an application Each environment (Edit, Preview, Production) in your app can have one or more data tags assigned. The available data tags are restricted by the admin — only data tags that the admin has allowed for a given environment will appear as options. To configure data tags for your app: 1. Open the **Settings** icon on the lower left corner of any App 2. Click **Environments** ![Settings menu](https://mintcdn.com/superblocks/9luYYaGEgXp4pGR_/images/administration/environments/in-app-env-switcher.png?fit=max\&auto=format\&n=9luYYaGEgXp4pGR_\&q=85\&s=65b12ba9fc0dffb2c5707eeab1983472) 3. For each environment, select the data tags you want to use from the allowed options 4. Choose a default data tag for each environment ![App environment setup](https://mintcdn.com/superblocks/9luYYaGEgXp4pGR_/images/administration/environments/in-app-env-menu.png?fit=max\&auto=format\&n=9luYYaGEgXp4pGR_\&q=85\&s=bb6c444637dd099eef1e47f7a0637d6b) Only data tags that the admin has assigned to a given environment will be available for selection. For example, if a data tag is only allowed in Production, it won't appear as an option in Edit or Preview. ## Change the default data tag When multiple data tags are available in an environment, you can set a default. This is the data tag used to execute APIs in this environment by default. To change the default, select the radio button next to the data tag you want to use by default: ![Default data tag selection](https://mintcdn.com/superblocks/9luYYaGEgXp4pGR_/images/administration/environments/set-default.png?fit=max\&auto=format\&n=9luYYaGEgXp4pGR_\&q=85\&s=20dcfc07f45edf8e77ffe22b25a039f5) # Local development Source: https://docs.superblocks.com/development-lifecycle/build/local-dev Connect to local development servers while developing in the Superblocks editor **Who can use this feature?**\\ Local development can only be used by organizations that self-host the Superblocks data plane using the [Hybrid or Cloud-Prem](/enterprise/deployment-overview) architectures. When building applications, it can be useful to access databases or APIs that are running locally to help speed up development and testing. This lets you: * Quickly make changes to REST APIs to return data needed for your app * Access new database schemas and update queries while those schemas are in development * Debug cross-service errors by setting breakpoints in downstream services Superblocks makes accessing datasources in any environment (including on your local machine) as easy as clicking a button, by using [data tags](/development-lifecycle/build/data-tags). This guide provides a brief overview of [how Superblocks executes APIs](#architecture), [how to configure your organization](#set-up) so your team can access locally hosted services while developing, and where local development fits into [Superblocks SDLC](#localhost-and-superblocks-sdlc). ## Architecture When building Superblocks Apps, you can think of the architecture as being similar to that of microservices. When a Superblocks API is run, a request is sent by the user's browser to the [Agent service](/enterprise/hybrid-architecture/overview). The agent then connects to other services (Integrations) to get data, before returning the results back to the browser. ![Superblocks Architecture when running local agents](https://superblocks-demo.s3.us-west-2.amazonaws.com/localhost_architecture.png) Usually agents are deployed to central cloud environments that all developers can access. When deployed in this fashion, the agent can only access other services in that environment or on public networks (e.g. Slack's API). For local development however, the agent will need to access ports on the local machine, which can be accomplished by running the agent locally. With local agents running, you can then update your Integrations to include a local configuration so the agent knows how to connect to the locally running APIs/Databases. ## Set up ### 1. Create a Localhost data tag To route API execution requests from the browser to a locally hosted agent, we'll use data tags. Define a new **Localhost** data tag and assign it to the **Edit** environment. When this data tag is selected in the Editor, Backend API requests will be sent from the developer's browser to the local agent to execute. To create the data tag: 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** 2. Click [**Environments**](https://app.superblocks.com/environments) 3. Click **Add Data Tag** 4. Name the new data tag **Localhost**, assign it to the **Edit** environment, and click **Create** Note that this data tag will be used by **all developers** on your account. When the application editor is set to use this data tag, API requests will only run if an agent is running at `localhost:8000` on the developer's machine. ### 2. Deploy the agent locally Now that you have a data tag defined for local development, you're ready to deploy an agent to your local machine. To do so: 1. Create an **Agent key** on the [Access Tokens](/admin/org-administration/auth/access-tokens#create-an-access-token) page 2. Run the following command, replacing `{AGENT_KEY}` with the token you just generated ```bash theme={null} curl -s https://charts.superblocks.com/agent/compose.yaml | \ SUPERBLOCKS_AGENT_KEY="{AGENT_KEY}" \ SUPERBLOCKS_AGENT_HOST_URL="http://localhost:8080" \ SUPERBLOCKS_AGENT_TAGS="profile:localhost" \ SUPERBLOCKS_DOCKER_AGENT_TAG="latest" \ SUPERBLOCKS_AGENT_DATA_DOMAIN="app.superblocks.com" \ docker compose -p superblocks -f - up ``` Note: Each developer that's contributing to an Application using the Localhost data tag will need to follow these instructions to run an agent on their machine. It is encouraged that all developers run the agent on the same port. To make this simple and scalable, it's good practice to create a shared `.env` file/start up script that developers can use when configuring their machine to run the agent. ### 3. Configure integrations to connect to local datasources With the agent running, Integrations can now connect to locally hosted services. To configure an integration to connect to a local service: 1. Go to the [**Integrations**](https://app.superblocks.com/integrations) page and select the integrations developers can connect to locally 2. Click on the ellipsis menu followed by **Manage** 3. Click the **+** icon to add a new configuration and select **Localhost** as the data tag 4. Fill out the configuration form with the values needed to connect to the local server/database and click **Save** Instead of setting host addresses to `localhost` be sure to set `host.docker.internal` #### Per-developer configuration Not sure what ports your developers will run local servers/databases on? No problem. You can use [Environment Variables](/enterprise/hybrid-architecture/extend/storing-environment-variables) to define the host/port/base URL/etc to use when connecting. For example, the following Integration uses an environment variable called `ORDERS_API_PORT` to define the localhost port where the server is running. ![Localhost REST Integration form with Environment Variables](https://superblocks-demo.s3.us-west-2.amazonaws.com/localhost_RESTAPI.png) When defining variables in this way, each developer can set the environment variable to the port they use on their machine. You can also use this if each of your developers has their own Cloud environment. Let's say for example that each developer has an API server running at `https://{username}.acme.com/api/v1`. You can create an `SUPERBLOCKS_AGENT_APP_ENV_API_SERVER_USERNAME` variable that each developer will set so that the API's base URL will update dynamically based on the developer executing the API. ![Integration form that sets the Base URL dynamically for each developer](https://superblocks-demo.s3.us-west-2.amazonaws.com/localhost_envvariable.png) ### 4. Use localhost in the editor With an agent running and integrations defined, you're ready to start building. To have Superblocks route API requests to your local agent, just set the default data tag in Edit mode to **Localhost**. ![Localhost data tag selected for Edit](https://superblocks-demo.s3.us-west-2.amazonaws.com/localhost_editor.png) ## Localhost and Superblocks SDLC When creating apps DIY, a typical deployment lifecycle has the following steps: * Make and preview changes on the developer's computer * Create a PR and review the changes on a remote test server * Merge changes and deploy them to a remote production server In Superblocks, you have a similar lifecycle using three built-in Development Environments: * **Edit**: Where developers make and test changes * **Preview**: Where users can review changes before they're deployed * **Deployed**: Where end-users access your application Each environment can be connected to one or more [data tags](/development-lifecycle/build/data-tags) so you can access databases and APIs that correspond to the phase of development being done in Superblocks. Local services should generally only be accessed in the **Edit** environment since they are developer specific. Once you're ready for someone else to review your changes, [create a commit](/development-lifecycle/version-control/superblocks-sdlc#commit). Each commit generates a unique URL called a [Commit Preview](/development-lifecycle/version-control/superblocks-sdlc#commit-previews) that you can share with your team to review. These URLs use the **Preview** environment, which should be set to access a data tag like `staging`, `qa`, or some other Cloud environment that all reviewers can access. # Rate limits and quotas Source: https://docs.superblocks.com/development-lifecycle/build/rate-limits-and-quotas Learn about the service limits applied to Applications, Workflows, and Scheduled Jobs to optimize the performance and stability of the Superblocks cloud The following applies only to customers on the Superblocks Cloud architecture. It does **not** apply to customers using the Superblocks Hybrid or Cloud-Prem architectures ([details](/enterprise/deployment-overview)). For users on Superblocks Cloud, tier based service limits are in place to optimize product performance and stability. If you need higher service limits for your use case, please reach out to our [support team](/enterprise/support/help) to request a limit increase. ## Time quotas | Quota | Description | Free | Trial | Pro | Enterprise | | - | - | - | - | - | - | | Application API duration | Duration of an API in an Application | 30 seconds | 5 minutes | 5 minutes | 5 minutes | | Workflow duration | Duration of a Workflow | 30 seconds | 10 minutes | 10 minutes | 10 minutes | | Scheduled Job duration | Duration of a Scheduled Job | 1 minute | 30 minutes | 30 minutes | 30 minutes | | Language step duration | Duration of any language step (Python / JavaScript) in an Application, Workflow, or Scheduled Job) | 1 minute | 1 minute | 2 minutes | 2 minutes | ## Size quotas | Quota | Description | Free | Trial | Pro | Enterprise | | - | - | - | - | - | - | | Step size\* | Step output returned | 5 MB | 10 MB | 20 MB | 20 MB | | Stream send size | Size of data sent to the client per message for streaming APIs | 500 kB | 500 kB | 1 MB | 2 MB | | Parallel pool size | Number of paths that can be used in the Parallel block | 10 | 10 | 50 | 50 | \* The **step size** refers to an API step's *output* (return value + console logs). You can still process in excess of these limits *within* a language step as long as the data is not returned. Note, API steps return serialized JSON which is included in this limit. ### Returning data from the Application backend to the frontend The following applies only to organizations whose payload quota is set at > 10 MB. When returning data from backend API steps to the frontend, it is recommended to keep it below **10MB** for performance reasons. Returning more data could cause degraded performance for end-users. This may require the use of server-side pagination to limit the payload of the data. ## Rate limits API steps are rate limited. The **throughput** of steps cannot exceed the following limits. | Rate Limit | Description | Free | Trial | Pro | Enterprise | | - | - | - | - | - | - | | Steps per second - User | Steps executed per second for an individual user | 500 | 500 | 5000 | 5000 | | Steps per second - Organization | Steps executed per second across an entire organization | 5000 | 5000 | 50000 | 50000 | | Steps per second - API | Steps executed per second for a single API | 500 | 500 | 5000 | 5000 | # Using secrets Source: https://docs.superblocks.com/development-lifecycle/build/using-secrets Reference secrets from your secret stores in integration configuration forms \ After an admin has [configured a secret store](/admin/secrets-management/overview), you can reference secrets in integration forms using the `{{sb_secrets}}` object. Secrets can only be referenced in integration forms. They can't be referenced in any application code directly. ## Referencing secrets Secrets are accessed from their respective stores using the syntax: ```js theme={null} {{sb_secrets.STORE_NAME.SECRET_NAME}} ``` Use this syntax in an integration's configuration form, for fields such as a password, API key, or connection string. Secrets are fetched at runtime from a particular store based on the API's current [**data tag**](/development-lifecycle/build/data-tags). ### JSON secrets If your secret is stored as a JSON object in key:value form, use the JavaScript `JSON.parse()` function to reference the secret value: ```js theme={null} {{JSON.parse(sb_secrets.STORE_NAME.SECRET_NAME).SECRET_KEY}} ``` ### Special characters If your secret name includes spaces or special characters, use array notation instead of dot notation: ```js theme={null} {{sb_secrets.STORE_NAME['SECRET_NAME']}} ``` ## Caching An admin can configure caching for each secret store to reduce calls to the secrets manager and improve API performance. If you've recently rotated a secret and aren't seeing the new value, ask your admin to clear the cache for that secret store. For more information on setting up and managing secret stores, see the [Secrets Management admin guide](/admin/secrets-management/overview). # Connect to Git Source: https://docs.superblocks.com/development-lifecycle/version-control/connect-to-git Connect your Superblocks applications to a Git repository for version-controlled, PR-based development workflows. Superblocks Git lets you connect each application to its own Git repository. Once connected, you get a full PR-based development workflow: edit in Superblocks, commit and push to your repo, open a pull request, and deploy once merged. ## Supported providers Superblocks works with any of the following Git hosting providers: | Provider | Remote URL format | | - | - | | **GitHub** | `https://github.com/org/repo.git` | | **GitLab Cloud** | `https://gitlab.com/group/repo.git` | | **GitLab Self-Hosted** | `https://gitlab.example.com/group/repo.git` | | **Bitbucket** | `https://bitbucket.org/workspace/repo.git` | | **Azure DevOps** | `https://dev.azure.com/org/project/_git/repo` | Both HTTPS and SSH remote URL formats are supported. ## Repository model Each Superblocks application is connected to **one Git repository**. The repository stores the application's definition files and a CI/CD pipeline configuration that keeps Superblocks in sync. When you first connect an app, Superblocks initializes the repository with your application's files and creates a CI pipeline file appropriate for your provider. ## Branching model Superblocks uses a two-branch workflow: * **`superblocks/live`** — the working branch where all edits happen in the Superblocks editor * **`main`** (or your repository's default branch) — the production branch that represents what is deployed ![Branching diagram showing edits on superblocks/live merging into main for deployment](https://mintcdn.com/superblocks/C7umFswFm14ss0rr/images/development-lifecycle/source-control/branching-diagram.svg?fit=max\&auto=format\&n=C7umFswFm14ss0rr\&q=85\&s=78206f77aa2f3106e6a0bd0fc3af0bd5) ### Development workflow 1. You edit on the **`superblocks/live`** branch in the Superblocks editor 2. When you want to sync your changes to Git, you make a commit 3. Once you want to promote your changes to production, you create a pull request in your Git repository 4. You go through your review process in Git and merge your PR when ready 5. These changes sync back to Superblocks via your CI/CD pipeline 6. You publish the synced changes to production from the **Deploy** tab in Clark version history When `superblocks/live` is created for the first time and does not yet exist on the remote, it is based on the tip of your repository's default branch. ## Setup ### Prerequisites Before connecting, you need: * A Git repository hosted on one of the [supported providers](#supported-providers). **The repository must be empty** * A **Personal Access Token (PAT)** with the required permissions for your provider (see [token permissions](#token-permissions) below) ### Connect an application to Git 1. Open your application in the Superblocks editor 2. Open **Git Settings** from the editor toolbar 3. Select your **Git provider** from the dropdown 4. Enter the **remote URL** of your repository 5. Enter your **Personal Access Token** 6. Click **Connect** Superblocks validates your credentials, initializes the repository, and switches the editor to the `superblocks/live` branch. After connecting to Git, existing checkpoints created before the connection will no longer be restorable. Make sure you are satisfied with the current state of your application before proceeding. ### Set up the CI/CD pipeline After connecting, Superblocks automatically adds a CI/CD configuration file to your repository. This pipeline syncs changes from `main` back to Superblocks whenever a merge occurs. To complete the setup, add your **Superblocks token** as a CI/CD secret: 1. Copy your Superblocks API token from **Personal Settings → API Key** (the Git setup screen also displays it for you) 2. In your Git provider, navigate to the secrets or variables settings for your repository and add a secret named `SUPERBLOCKS_TOKEN` with the token value The CI/CD file and secrets location depend on your provider: > [tab] GitHub > > **CI file:** `.github/workflows/superblocks-sync.yml` > > **Add the secret:** Repository **Settings → Secrets and variables → Actions → New repository secret** > > Add `SUPERBLOCKS_TOKEN` with your Superblocks API key. > > Optionally, add `NPM_AUTH_TOKEN` if the Superblocks CLI package is hosted in a private GitHub Packages registry. > [tab] GitLab > > **CI file:** `.gitlab-ci.yml` > > **Add the variable:** Repository **Settings → CI/CD → Variables** > > Add `SUPERBLOCKS_TOKEN` with your Superblocks API key. Mark it as **Protected** and **Masked**. > [tab] Bitbucket > > **CI file:** `bitbucket-pipelines.yml` > > **Add the variable:** Repository **Settings → Repository variables** > > Add `SUPERBLOCKS_TOKEN` with your Superblocks API key. Check **Secured** to mask the value in logs. > [tab] Azure DevOps > > **CI file:** `.azure-pipelines/superblocks-sync.yml` > > **Add the variable:** > > 1. First, create a pipeline from the `.azure-pipelines/superblocks-sync.yml` YAML file > 2. Then open the pipeline editor and add a variable named `SUPERBLOCKS_TOKEN` with your Superblocks API key. Mark it as **secret** ### Connect additional users If another team member needs to work on an app that is already connected to Git, they need: 1. **Repository access** — ask a repo admin to add them as a collaborator 2. **A valid PAT** — when they open the app for the first time, Superblocks prompts them to enter their own personal access token Each user authenticates independently with their own PAT, so commits are attributed to the correct author. ## Token permissions The required PAT permissions vary by provider: > [tab] GitHub > > Use a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) scoped to your repository: > > | Permission | Access level | > | - | - | > | **Administration** | Read-only | > | **Contents** | Read and write | > | **Metadata** | Read-only | > | **Workflows** | Read and write | > > If GitHub does not let you scope a fine-grained token to the repository (this can happen for some organization settings), create a [classic personal access token](https://github.com/settings/tokens) with the **repo** and **workflow** scopes instead. > [tab] GitLab > > Use a [personal access token](https://gitlab.com/-/user_settings/personal_access_tokens) or a project access token: > > | Setting | Value | > | - | - | > | **Scope** | `api` | > | **Role** (project access tokens only) | Maintainer | > > For self-hosted GitLab, create the token from your instance's token settings page. > [tab] Bitbucket > > Use a [repository access token](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/) created in your repository's settings: > > | Permission | Access level | > | - | - | > | **Repositories** | Read and Write | > | **Pull requests** | Read and Write | > | **Pipelines** | Read | > [tab] Azure DevOps > > Use a [personal access token](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) scoped to the organization that owns the repository: > > | Permission | Access level | > | - | - | > | **Code** | Read & Write | > | **Project and Team** | Read | ## Using Clark for Git You can use **Clark**, the Superblocks AI assistant, to perform Git operations directly from the editor. If the app is not yet connected to Git, asking Clark to run a Git operation triggers the setup flow automatically. Once connected, you can ask Clark things like: * *"What's the current git status?"* * *"Show me the recent commits"* * *"Commit my changes with the message 'fix: update button styles'"* * *"Pull the latest changes from remote"* ## Deploying changes When a change is merged to `main`, the CI/CD pipeline syncs that commit back to Superblocks. To publish: 1. Open **Clark AI** and switch to **Version history** 2. Open the **Deploy** tab (your repository's default branch) 3. Preview the synced version if you want to verify changes 4. Click **Publish** to make it live for end users ## Updating your Git token If your personal access token expires or becomes invalid, open **Git Settings** from the editor toolbar. You do not need to disconnect the repository. 1. Enter a new PAT in the token field 2. Click **Save** Superblocks validates the token and refreshes Git authentication in place. Prefer updating the token this way instead of disconnecting and reconnecting, so the app stays linked to the repository. ## Disconnecting from Git If you need to disconnect an application from Git: 1. Open **Git Settings** from the editor toolbar 2. Click **Disconnect** 3. Type the repository name to confirm Disconnecting removes the link between the app and the repository. The repository itself is not deleted or modified. ## Troubleshooting ### "Invalid or insufficient permissions for this token" The PAT cannot access the repository or is missing required scopes. Update the token in **Git Settings** (see [Updating your Git token](#updating-your-git-token)), and double-check the [token permissions](#token-permissions) for your provider. ### "Repository not found" The remote URL is incorrect, the repository does not exist, or the token does not have access to it. ### CI/CD pipeline not syncing Verify that: * The `SUPERBLOCKS_TOKEN` secret is set correctly in your provider's CI/CD settings * The CI/CD configuration file exists in your repository and has not been modified or deleted * The pipeline is triggered on pushes to `main` (or your default branch) # Superblocks SDLC Source: https://docs.superblocks.com/development-lifecycle/version-control/superblocks-sdlc Superblocks version control helps you track, preview, publish, and roll back application changes Using version control you can: * [**Track versions**](#track-versions) as Clark checkpoints * [**Preview**](#preview) a version before it goes live * [**Publish**](#publish) a version to production * [**Roll back**](#roll-back) by publishing an earlier version * [**Undeploy**](#undeploy) an app so end users cannot access it * [**Restore**](#restore) the editor and chat to an earlier checkpoint * Use [**Git**](#git-connected-apps) for PR-based workflows when the app is connected to a repository ## Track versions After each Clark prompt completion, Superblocks saves a **checkpoint**. To see your app's checkpoints, open **Clark AI**, then click the **Version history** icon in the Clark header. ![Version history in the Clark panel](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/version-history.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=3aca06200c926b442b1cab9ba1dc448a) ## Preview From a checkpoint in chat or version history, click **Preview**. Superblocks builds a shareable preview of that version so you can QA without changing production. ## Publish From a checkpoint in chat or version history, click **Publish** to promote that version to production. Superblocks builds, runs pre-publish checks, and deploys in one flow. Click **View publish details** from a previewed / published checkpoint card, or click any previewed / published version in history to watch build progress, review errors, and complete pre-publish security or database actions. ![Publish detail view](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/03-publish-detail.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=67e03fab71cc2c46e336623ad3730c99) Builders need [permission to deploy the application](/admin/org-administration/resource-roles#applications). Without it, the **Publish** button stays disabled with a message that you do not have permission to publish to production. ## Roll back To revert production to a previous version, publish the desired older checkpoint from **Version history**. End users of the app will now see the earlier version the next time they refresh or load the app. ## Undeploy You can **Undeploy** an application to make it temporarily unavailable to end users. To undeploy an application: 1. Open **Version history** in Clark 2. Open the menu on the **Live** version 3. Click **Undeploy** and confirm ![Undeploy an app](https://mintcdn.com/superblocks/-077B3_3izMdW8zr/images/development-lifecycle/source-control/undeploy-app.png?fit=max\&auto=format\&n=-077B3_3izMdW8zr\&q=85\&s=b1990c05806fae1f671c49a46cc725a3) After undeploying, the application is no longer accessible to end users. You can keep working in edit mode and publish again when ready. ## Restore You can **Restore** an application in order to discard later edit-mode work and reset Clark's chat memory to an earlier point. To restore an application: 1. Open the checkpoint in chat or find it in **Version history** 2. Choose **Restore** 3. Confirm in **Restore to checkpoint** Restore only affects edit mode and chat history. The live production version does not change until you publish again. If you need to change what end users see, [publish](#publish) or [roll back](#roll-back) instead. ## Git-connected apps When an app is connected to Git: * Edits happen on `superblocks/live` * You **commit** and open pull requests in your repository * After merging to your default branch and the CI sync completes, publish from the **Deploy** tab in Clark version history (not from the History / `superblocks/live` list) ![Publish main branch for git-enabled app](https://mintcdn.com/superblocks/mm1QoNLfd7KZacuX/images/building-with-clark/checkpoints/publish-git.png?fit=max\&auto=format\&n=mm1QoNLfd7KZacuX\&q=85\&s=1d5d180222f183bae92a4eb4747b68d1) For more on Git workflows, see [Connect to Git](/development-lifecycle/version-control/connect-to-git). # Superblocks Cloud Source: https://docs.superblocks.com/enterprise/cloud-architecture Superblocks Cloud delivers the full power of Superblocks as a fully managed, multi-tenant SaaS platform, designed for organizations that want to move fast with minimal operational overhead. With Superblocks Cloud, AI inference, the Superblocks control plane, and the Superblocks data plane are all hosted and operated entirely in Superblocks’ cloud infrastructure. Customers benefit from rapid setup, seamless upgrades, and a fully managed experience, while still maintaining strong security controls, governance, and enterprise-grade reliability. The result is the fastest path to building and operating internal applications with AI—without managing infrastructure, provisioning cloud resources, or operating platform components yourself. ## Cloud architecture ![](https://mintcdn.com/superblocks/9gY8R6Ph9jAsQ-Bn/images/enterprise-deployment/cloud.png?fit=max\&auto=format\&n=9gY8R6Ph9jAsQ-Bn\&q=85\&s=3bda9f8321566ba6c2ecdd8964822b27) This model provides low latency, simple networking, and fast time to value for organizations with regional data requirements. ### How it works In the Superblocks Cloud deployment model: * Superblocks is delivered as a fully managed, multi-tenant SaaS platform operated by Superblocks * AI inference is executed in Superblocks’ cloud environment, using managed AI services and models selected and operated by Superblocks * Applications connect to Superblocks-managed data plane, which securely connect to your external systems and data sources * Your team authenticates using your enterprise SSO provider, with identity and access governed by Superblocks RBAC and enterprise identity integrations * Superblocks operates and supports the platform end-to-end, including infrastructure, networking, scaling, security, and reliability This model ensures that customers can build, deploy, and operate internal applications without managing cloud infrastructure, while Superblocks handles platform operations—including upgrades, security patches, scaling, and ongoing support. ### Why choose Cloud Superblocks Cloud is best for organizations prioritizing speed, simplicity, and rapid time to value. Customers across technology, e-commerce, SaaS, and digital-first enterprises often choose this deployment model because: * **Fastest time to value:** Get started in minutes with no infrastructure setup, cloud accounts, or platform operations required. * **Fully managed AI and infrastructure:** AI inference, application hosting, and platform services are managed and operated entirely by Superblocks. * **Simplified security and operations:** Superblocks manages infrastructure security, networking, patching, and upgrades, reducing operational burden on customer teams. * **Enterprise-ready governance:** Built-in RBAC, audit logs, and environment controls support enterprise security and compliance requirements. All updates and upgrades are planned, executed, and supported by Superblocks. Customers are not required to manage infrastructure, deploy updates, or operate the platform. Customers retain ownership over application code and can manage user access, and integration configuration from an admin UI. # Superblocks AWS Cloud-Prem Source: https://docs.superblocks.com/enterprise/cloud-prem/aws Superblocks AWS Cloud-Prem delivers the full power of Superblocks in a deployment model designed for organizations that require strict data residency, security controls, and infrastructure ownership. With AWS Cloud-Prem, Superblocks runs as a dedicated, single-tenant deployment inside your AWS account. This gives customers direct control over networking, data boundaries, and compliance posture, while Superblocks continues to manage the platform lifecycle, upgrades, and reliability. The result is the trust and governance of customer-owned infrastructure—without the operational burden, slow iteration cycles, or complexity of traditional self-hosted deployments. ## AWS single region architecture ![](https://mintcdn.com/superblocks/OrdihIqDANiNTUaJ/images/enterprise-deployment/cloud-prem.png?fit=max\&auto=format\&n=OrdihIqDANiNTUaJ\&q=85\&s=e081bef89cb8d516fd7f91b1b02dd23d) In the single region deployment the Control Plane and Data Plane run in the same AWS region. ## AWS multi-region architecture ![](https://mintcdn.com/superblocks/AmKWe0YbRbizsd5G/images/enterprise-deployment/cloud-prem-multi.png?fit=max\&auto=format\&n=AmKWe0YbRbizsd5G\&q=85\&s=819049290c7a6f2edb076a2bc79d6d50) In a multi-region deployment, the Superblocks control plane runs in a single AWS VPC in one region, while each AWS region that hosts customer data runs a local data plane. Applications connect directly to the regional data plane closest to the data, ensuring low latency and regional isolation. All communication is outbound-only from the data plane, so customers are not required to allow inbound network access or open firewall ports. This architecture delivers regional performance, strong network isolation, and simplified security posture while supporting global deployments. ## How it works In the Superblocks AWS Cloud-Prem deployment model: * Superblocks is deployed as a dedicated, single-tenant instance within your AWS account * AI inference is executed on Amazon Bedrock, using models and regions you control * Applications connect directly to the Superblocks data plane running in an AWS region colocated with your private data, minimizing latency and data movement * Your team authenticates using your enterprise SSO provider, with identity and access governed by your existing IAM policies * Superblocks operates and supports the platform as a fully managed service, adhering to least-privilege access and customer-defined boundaries This model ensures that all application data, AI inputs, and AI outputs remain within your AWS environment, while Superblocks manages platform operations—including upgrades, security patches, reliability, and ongoing support—without requiring you to run or maintain the system yourself. ## Why choose Cloud-Prem AWS Cloud-Prem is best for enterprises requiring the highest level of compliance, security and data residency. Customers in Financial Services, Insurance, Healthcare & Life Sciences, Telecommunications and Government often choose this deployment model because: * **AWS data residency and isolation:** All application data, AI prompts, and AI responses are processed and stored entirely within your AWS account and selected AWS regions. * **Customer-managed AI inference on Amazon Bedrock:** Clark performs inference using Amazon Bedrock in your AWS account, governed by your regional selection, model access controls, and service policies. * **Enhanced observability and audit readiness:** Increased visibility into platform activity enables integration with your AWS logging, monitoring, and audit workflows to support compliance requirements. * **AWS-native security and governance enforcement:** Apply your existing AWS IAM policies, VPC network controls, security groups, and governance guardrails directly to Superblocks. * **Leverage AWS Enterprise Discount Program (EDP):** All infrastructure resources run in your AWS account and can count toward your existing AWS committed spend and procurement agreements. ## Managed service model In AWS Cloud-Prem, Superblocks is responsible for: * Delivering regular platform updates and feature enhancements * Managing upgrades * Ensuring release compatibility, stability, and reliability * Providing operational support and incident response All upgrades are planned, executed, and supported by Superblocks. This ensures Cloud-Prem environments remain secure, supported, and current, without requiring customers to plan, test, or operate upgrades themselves. Customers retain control over cloud-level access, security policies, deployment environments, and AI execution boundaries, while Superblocks manages the ongoing operation and lifecycle of the platform. # Optional configurations Source: https://docs.superblocks.com/enterprise/cloud-prem/configure/index A Cloud-Prem deployment works without any of the configurations on this page. Each one is opt-in: turn it on when your organization needs it, either during your initial deployment or later. | Configuration | What it does | How it's applied | | - | - | - | | [Observability destinations](/enterprise/cloud-prem/configure/observability-destinations) | Sends logs, metrics, and traces to Datadog or to OpenTelemetry and Prometheus endpoints, configured per signal | You store settings in AWS Secrets Manager; Superblocks applies them at the next deployment | | [Custom resource tags](/enterprise/cloud-prem/configure/resource-tags) | Applies your organization's tags to the platform resources Superblocks deploys | You send key/value pairs to your deployment team; Superblocks applies them at the next deployment | | [Custom WAF rule groups](/enterprise/cloud-prem/configure/waf-rule-groups) | Attaches your own AWS WAF rule groups to the WAFs that Cloud-Prem deploys to protect inbound traffic | You send rule group ARNs to your deployment team; Superblocks attaches them at the next deployment | | [AWS Network Firewall](/enterprise/cloud-prem/configure/network-firewall) | Inspects and filters outbound traffic from the Cloud-Prem account, using your own firewall or one the bootstrap deploys | You set variables in the bootstrap Terraform and apply it; Superblocks wires the firewall into your instance at the next deployment | | Image mirroring and scanning | Superblocks copies Cloud-Prem container images into your own registry so you can scan them; your scan results can block a deployment | Contact your deployment team | ## Request a configuration To add or change a configuration, follow the steps on its page if it has one, then contact your Superblocks deployment team. If you are still preparing your initial deployment, share your choices with them before the deployment starts so they are included from day one. The [deployment guide](/enterprise/cloud-prem/deployment-guide) shows where each step fits. # AWS Network Firewall Source: https://docs.superblocks.com/enterprise/cloud-prem/configure/network-firewall Route outbound traffic from your Cloud-Prem account through [AWS Network Firewall](https://docs.aws.amazon.com/network-firewall/latest/developerguide/what-is-aws-network-firewall.html) so you can inspect and filter it. The firewall is yours: you choose how it's deployed and you control its rules. This applies to outbound traffic only. To filter inbound traffic, use [custom WAF rule groups](/enterprise/cloud-prem/configure/waf-rule-groups). ## Choose a setup You configure Network Firewall with variables in the bootstrap Terraform you run during [deployment](/enterprise/cloud-prem/deployment-guide). The bootstrap README walks you through setting them. Use this page to choose a setup and confirm the right variables are set for it. See the [variable reference](#bootstrap-variable-reference) for every variable. Pick one of three setups: | Setup | Who deploys the firewall | Who manages the rules | Traffic it filters | | - | - | - | - | | [Bring your own firewall](#bring-your-own-firewall) | You | You | Control plane and Superblocks-managed data planes | | [Bootstrap-managed firewall](#bootstrap-managed-firewall) | The bootstrap Terraform | You. The firewall starts by passing all traffic | Control plane only | | [Bootstrap-managed firewall with the default allowlist](#use-the-default-allowlist) | The bootstrap Terraform | The bootstrap Terraform, using the Superblocks default allowlist plus your additions and exclusions | Control plane only | Bootstrap-managed firewalls don't filter data plane traffic A firewall created with `enable_network_firewall` only filters traffic from the Cloud-Prem control plane. If your instance includes Superblocks-managed data planes, their outbound traffic doesn't go through it. That means builders can create REST APIs and integrations that connect to domains outside your allowlist. To filter data plane traffic as well, [bring your own firewall](#bring-your-own-firewall) instead. Self-hosted data planes run outside the Cloud-Prem account, so neither setup covers them. You can add Network Firewall during your initial deployment or later. To add it or change setups later, update the variables and re-apply the bootstrap Terraform. Superblocks wires the firewall into your instance at the next deployment. ## Bring your own firewall Use a Network Firewall you already deploy and manage. Cloud-Prem routes outbound traffic from each availability zone's public subnet through your firewall endpoint instead of directly to the internet gateway. This applies to both the control plane and Superblocks-managed data planes. The bootstrap Terraform creates the Cloud-Prem VPC, so set up the firewall in this order: 1. Apply the bootstrap Terraform without any firewall variables. This creates the Cloud-Prem VPC. 2. Deploy your Network Firewall with an endpoint in the Cloud-Prem VPC for each availability zone Cloud-Prem uses. 3. Set `firewall_endpoint_ids` to a map of availability zone ID to firewall endpoint ID. Use AZ IDs such as `usw2-az1`, not AZ names such as `us-west-2a`. ```hcl theme={null} firewall_endpoint_ids = { "usw2-az1" = "vpce-0123456789abcdef0" "usw2-az2" = "vpce-0fedcba9876543210" } ``` 4. Re-apply the bootstrap Terraform. Superblocks wires the firewall into your instance at the next deployment. Your firewall rules must allow the [required outbound domains](#required-outbound-domains), or Cloud-Prem can't reach the services it depends on. Don't set `enable_network_firewall` when you bring your own firewall. The two options can't be combined. ## Bootstrap-managed firewall Have the bootstrap Terraform create the firewall for you. It creates firewall subnets and endpoints in the Cloud-Prem VPC and routes outbound traffic, and the return traffic from the internet gateway, through them. It filters control plane traffic only, not traffic from [Superblocks-managed data planes](#choose-a-setup). 1. Set `enable_network_firewall` to `true`. 2. Add a `cidr_firewall` entry with exactly one IPv4 CIDR to each availability zone in `network.subnets`: ```hcl theme={null} enable_network_firewall = true network = { # ...your existing network settings subnets = { "usw2-az1" = { # ...your existing subnet settings cidr_firewall = ["10.0.250.0/28"] } "usw2-az2" = { # ...your existing subnet settings cidr_firewall = ["10.0.250.16/28"] } } } ``` 3. Apply the bootstrap Terraform. Superblocks wires the firewall into your instance at the next deployment. The firewall policy starts by passing all traffic. You manage the rules yourself in AWS, outside Terraform, and re-applying the bootstrap doesn't overwrite them. Your rules must allow the [required outbound domains](#required-outbound-domains). To have the bootstrap enforce an allowlist for you instead, [use the default allowlist](#use-the-default-allowlist). ## Use the default allowlist With a bootstrap-managed firewall, you can have the bootstrap enforce the Superblocks default allowlist. Outbound control plane traffic is then blocked unless it's going to an allowed domain. Traffic from Superblocks-managed data planes isn't filtered. ```hcl theme={null} enable_network_firewall = true enable_network_firewall_default_rule_groups = true # Domains your deployment reaches beyond the Superblocks platform network_firewall_extra_allowed_domains = [ ".okta.com", "api.example.com", ] # Default domains for parts of the platform you don't use network_firewall_excluded_default_domains = [ "registry.npmjs.org", ] ``` | Variable | Description | | - | - | | `enable_network_firewall_default_rule_groups` | Enforces the default allowlist. Requires `enable_network_firewall` | | `network_firewall_extra_allowed_domains` | Domains to allow in addition to the default list, such as your identity provider, an internal package registry, or your own APIs. A leading dot, such as `.example.com`, matches the domain and all its subdomains | | `network_firewall_excluded_default_domains` | Default domains to remove for parts of the platform you don't use. Each entry must match a [default domain](#required-outbound-domains) exactly, or the Terraform plan fails | | `network_firewall_default_rule_group_capacity` | Capacity reserved for the allowlist rule group. Defaults to `100` | To see the allowlist the firewall is enforcing, run: ```bash theme={null} terraform output network_firewall ``` While the default allowlist is on, Terraform owns the firewall policy. Rules you change outside Terraform are reverted the next time you re-apply the bootstrap. Make changes with the variables above instead. ### Increase the rule group capacity AWS fixes a rule group's capacity when it's created. Raise `network_firewall_default_rule_group_capacity` before adding enough extra domains to exceed it. Changing the capacity replaces the rule group, so apply it in two steps: 1. Set `enable_network_firewall_default_rule_groups` to `false` and apply. 2. Set the new capacity, set `enable_network_firewall_default_rule_groups` back to `true`, and apply again. ## Required outbound domains The Cloud-Prem control plane needs to reach these domains. The default allowlist includes all of them. If you manage your own rules, allow them yourself. Replace `` with your Cloud-Prem AWS region. | Purpose | Domains | | - | - | | AWS services | `.amazonaws.com`, `..api.aws`, `eks-auth..api.aws`, `ssm..api.aws`, `ec2..api.aws`, `eks..api.aws` | | Superblocks | `.superblocks.com`, `.superblockshq.com` | | Datadog | `.datadoghq.com` | | Container and package registries | `github.com`, `.githubusercontent.com`, `registry.npmjs.org`, `npm.pkg.github.com`, `registry.terraform.io`, `releases.hashicorp.com`, `checkpoint-api.hashicorp.com` | | TLS certificate issuance | `acme-v02.api.letsencrypt.org` | | [CVE detection](/admin/code-security/supply-chain/cve-detection) advisory feed | `storage.googleapis.com` | Also allow the domains your deployment reaches beyond the Superblocks platform, such as your identity provider, the APIs and databases your apps connect to, and any [observability destinations](/enterprise/cloud-prem/configure/observability-destinations) you send telemetry to. Allowlists limit Clark web search If your firewall blocks all outbound traffic except allowed domains, Clark can't search the web. Clark then can't explore documentation or gather information from the internet while it builds, so its results may be less informed. To let Clark reach specific sites, such as documentation for the libraries and APIs your team builds with, allow their domains. With the [default allowlist](#use-the-default-allowlist), add them to `network_firewall_extra_allowed_domains`. ## Bootstrap variable reference | Variable | Type | Default | Set it for | | - | - | - | - | | `firewall_endpoint_ids` | Map of AZ ID to firewall endpoint ID | `{}` | Bring your own firewall. Filters control plane and Superblocks-managed data plane traffic. Must be empty when `enable_network_firewall` is `true` | | `enable_network_firewall` | Boolean | `false` | Bootstrap-managed firewall, with or without the default allowlist. Filters control plane traffic only | | `network.subnets[*].cidr_firewall` | List with one IPv4 CIDR | Empty | Bootstrap-managed firewall. Required for every availability zone when `enable_network_firewall` is `true`, and must be empty otherwise | | `enable_network_firewall_default_rule_groups` | Boolean | `false` | Default allowlist. Requires `enable_network_firewall` | | `network_firewall_extra_allowed_domains` | List of strings | `[]` | Default allowlist. Ignored otherwise | | `network_firewall_excluded_default_domains` | List of strings | `[]` | Default allowlist. Ignored otherwise | | `network_firewall_default_rule_group_capacity` | Number | `100` | Default allowlist, when you need more capacity | ## Related * [Optional configurations](/enterprise/cloud-prem/configure/index) * [Custom WAF rule groups](/enterprise/cloud-prem/configure/waf-rule-groups) * [Cloud-Prem deployment guide](/enterprise/cloud-prem/deployment-guide) # Observability destinations Source: https://docs.superblocks.com/enterprise/cloud-prem/configure/observability-destinations Cloud-Prem always writes full telemetry to AWS services in your Cloud-Prem account. You can also send each signal (logs, metrics, and traces) to your own observability tool, so your team can monitor Superblocks alongside the rest of your stack. Adding a destination does not change what Superblocks receives. Superblocks continues to receive the base telemetry it needs to operate and support your deployment. ## How destinations work ```mermaid theme={null} flowchart LR CP["Cloud-Prem services"] --> CW["CloudWatch
logs and metrics"] CP --> XR["AWS X-Ray
traces"] CP --> SB["Superblocks
base telemetry"] CP -.-> DEST["Your destination
Datadog, OTLP, or Prometheus
per signal"] ``` * **Your AWS account always gets everything.** Logs and metrics go to Amazon CloudWatch and traces go to AWS X-Ray, whether or not you add a destination. * **Each signal is configured on its own.** Logs, metrics, and traces can each go to one additional destination, and each signal can use a different one. For example, you can send logs to Datadog and traces to an OTLP endpoint. * **You own the settings; Superblocks applies them.** You store destination settings and credentials in AWS Secrets Manager in your Cloud-Prem account. Superblocks applies them at the next deployment. ## Choose a destination | Destination | Setup | Best when | | - | - | - | | **Datadog** | Built in, configured per signal | Your team already uses Datadog | | **OpenTelemetry and Prometheus** | Built in, configured per signal | You use Grafana Cloud or another tool that accepts OTLP for traces and logs, and Prometheus remote write for metrics | | **Forward from your AWS account** | You build and own the forwarding | Your tool isn't supported directly, or you already forward CloudWatch and X-Ray data centrally | ## Configure a destination **1. Gather your destination details** Collect the values for each signal you want to send. You only need values for the signals you are configuring. > [tab] Datadog > > | Value | Description | > | - | - | > | API key | A Datadog API key. One key is used for every signal you send to Datadog | > | Site | Your Datadog site, such as `datadoghq.com` or `datadoghq.eu` | > [tab] OpenTelemetry and Prometheus > > | Signal | Endpoint type | Example (Grafana Cloud) | > | - | - | - | > | Metrics | Prometheus remote write | `https://prometheus-prod-01-eu-west-0.grafana.net/api/prom/push` | > | Traces | OTLP | `https://otlp-gateway-prod-eu-west-0.grafana.net/otlp` | > | Logs | OTLP | `https://otlp-gateway-prod-eu-west-0.grafana.net/otlp` | > > For each endpoint, also collect the `Authorization` header value it expects, including the scheme, such as `Basic `. **2. Create the secret in AWS Secrets Manager** In your Cloud-Prem AWS account, create a secret named exactly `superblocks-main/superblocks/customer_exporter`. Include only the signals you want to send, and write every value as a string, including `"true"`. > [tab] Datadog > > ```bash theme={null} > aws secretsmanager create-secret \ > --name "superblocks-main/superblocks/customer_exporter" \ > --secret-string '{ > "DATADOG_API_KEY": "", > "DATADOG_SITE": "datadoghq.com", > "DATADOG_METRICS_ENABLED": "true", > "DATADOG_TRACES_ENABLED": "true", > "DATADOG_LOGS_ENABLED": "true" > }' > ``` > [tab] OpenTelemetry and Prometheus > > ```bash theme={null} > aws secretsmanager create-secret \ > --name "superblocks-main/superblocks/customer_exporter" \ > --secret-string '{ > "MIMIR_ENABLED": "true", > "MIMIR_ENDPOINT": "https://prometheus-prod-01-eu-west-0.grafana.net/api/prom/push", > "MIMIR_AUTHORIZATION": "Basic ", > "TEMPO_ENABLED": "true", > "TEMPO_ENDPOINT": "https://otlp-gateway-prod-eu-west-0.grafana.net/otlp", > "TEMPO_AUTHORIZATION": "Basic ", > "OTLP_LOGS_ENABLED": "true", > "OTLP_LOGS_ENDPOINT": "https://otlp-gateway-prod-eu-west-0.grafana.net/otlp", > "OTLP_LOGS_AUTHORIZATION": "Basic " > }' > ``` See the [secret reference](#secret-reference) for every supported key. **3. Tell Superblocks** Let your Superblocks deployment team know the secret is ready. Superblocks applies the configuration at the next deployment. **4. Verify data is arriving** After the deployment completes, check your destination for new data from each signal you configured. If your Cloud-Prem account restricts outbound traffic, allow connections from the Cloud-Prem account to your destination's endpoints before you verify. With the [AWS Network Firewall](/enterprise/cloud-prem/configure/network-firewall) default allowlist, add them to `network_firewall_extra_allowed_domains`. The default list already includes `.datadoghq.com`, but not other Datadog sites such as `datadoghq.eu`. ### Send signals to different destinations To split signals across destinations, combine keys from both in the same secret and enable each signal for only one destination. This example sends logs to Datadog and traces to an OTLP endpoint, and leaves metrics in your AWS account only: ```json theme={null} { "DATADOG_API_KEY": "", "DATADOG_SITE": "datadoghq.com", "DATADOG_LOGS_ENABLED": "true", "TEMPO_ENABLED": "true", "TEMPO_ENDPOINT": "https://otlp-gateway-prod-eu-west-0.grafana.net/otlp", "TEMPO_AUTHORIZATION": "Basic " } ``` ## Forward from your AWS account If you'd rather route telemetry yourself, use AWS features to forward it from your Cloud-Prem account. Superblocks doesn't configure or manage this forwarding. | Signal | Where it lands | How to forward it | | - | - | - | | Logs | Amazon CloudWatch Logs | [Subscription filters](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Subscriptions.html) to Amazon Data Firehose, Kinesis, or Lambda | | Metrics | Amazon CloudWatch | [Metric streams](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Metric-Streams.html) to Amazon Data Firehose or a supported partner | | Traces | AWS X-Ray | Your observability tool's X-Ray integration, or the [X-Ray APIs](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) | You can combine approaches. For example, send traces to an OTLP endpoint through the secret and forward logs yourself with a subscription filter. ## Change or remove a destination To change the secret, replace its value with the full, updated JSON, then tell your Superblocks deployment team: ```bash theme={null} aws secretsmanager put-secret-value \ --secret-id "superblocks-main/superblocks/customer_exporter" \ --secret-string '{ ... }' ``` * **Change a destination:** update its endpoint, credentials, or site. * **Stop sending a signal:** set that signal's `_ENABLED` key to `"false"`. * **Stop sending all signals:** set every `_ENABLED` key to `"false"`, or delete the secret. Changes take effect at the next deployment. Your CloudWatch and X-Ray data, and the base telemetry Superblocks receives, are unaffected. ## Troubleshooting If data isn't arriving after the deployment completes, check: * **Secret name:** the secret is named exactly `superblocks-main/superblocks/customer_exporter` and is in your Cloud-Prem account. * **Secret contents:** the secret is valid JSON, uses the exact key names in the [secret reference](#secret-reference), and every value is a string (`"true"`, not `true`). * **One destination per signal:** a signal isn't enabled for both Datadog and an OpenTelemetry or Prometheus endpoint. * **Credentials:** the API key or `Authorization` value is valid, includes the scheme (such as `Basic`), and has permission to write data. * **Datadog site:** the site matches your Datadog account. * **Network access:** outbound traffic from the Cloud-Prem account can reach your destination's endpoints. If everything checks out, contact your Superblocks deployment team. ## Secret reference All values are strings. ### Datadog | Key | Description | | - | - | | `DATADOG_API_KEY` | Datadog API key, used for every signal sent to Datadog | | `DATADOG_SITE` | Datadog site, such as `datadoghq.com` or `datadoghq.eu` | | `DATADOG_METRICS_ENABLED` | `"true"` to send metrics to Datadog | | `DATADOG_TRACES_ENABLED` | `"true"` to send traces to Datadog | | `DATADOG_LOGS_ENABLED` | `"true"` to send logs to Datadog | ### OpenTelemetry and Prometheus | Key | Signal | Description | | - | - | - | | `MIMIR_ENABLED` | Metrics | `"true"` to send metrics to a Prometheus remote write endpoint | | `MIMIR_ENDPOINT` | Metrics | Prometheus remote write URL | | `MIMIR_AUTHORIZATION` | Metrics | `Authorization` header value, including the scheme | | `TEMPO_ENABLED` | Traces | `"true"` to send traces to an OTLP endpoint | | `TEMPO_ENDPOINT` | Traces | OTLP endpoint URL | | `TEMPO_AUTHORIZATION` | Traces | `Authorization` header value, including the scheme | | `OTLP_LOGS_ENABLED` | Logs | `"true"` to send logs to an OTLP endpoint | | `OTLP_LOGS_ENDPOINT` | Logs | OTLP endpoint URL | | `OTLP_LOGS_AUTHORIZATION` | Logs | `Authorization` header value, including the scheme | # Custom resource tags Source: https://docs.superblocks.com/enterprise/cloud-prem/configure/resource-tags Apply your organization's tags to the AWS resources Superblocks deploys in your Cloud-Prem account, so they fit your cost allocation, ownership, and governance policies. ## Which resources are tagged Your tags are applied to the platform resources Superblocks deploys. They aren't applied to the resources created by the bootstrap Terraform you run during [deployment](/enterprise/cloud-prem/deployment-guide). ## Add tags 1. Choose the tags you want as key/value pairs. For example: | Key | Value | | - | - | | `CostCenter` | `1234` | | `Owner` | `platform-team` | | `DataClassification` | `confidential` | 2. Send the list to your Superblocks deployment team. 3. Superblocks applies the tags at the next deployment. You can add tags during your initial deployment or at any time after. ## Tag rules * **AWS tag rules apply.** Keys and values must follow AWS [tag naming limits and requirements](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html#tag-conventions). Keys that start with `aws:` are reserved by AWS. * **The `superblocks:` prefix is reserved.** Superblocks uses the `superblocks:` tag namespace for its own tags. Don't start any of your tag keys with `superblocks:`. ## Change or remove tags To change or remove tags, send the updated list to your deployment team. Changes take effect at the next deployment. ## Related * [Optional configurations](/enterprise/cloud-prem/configure/index) # Custom WAF rule groups Source: https://docs.superblocks.com/enterprise/cloud-prem/configure/waf-rule-groups Cloud-Prem deploys regional and global [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) web ACLs to protect inbound traffic to your instance. You can attach your own WAF rule groups to apply your organization's rules alongside the Superblocks rules. This applies to inbound traffic only. To filter outbound traffic, use [AWS Network Firewall](/enterprise/cloud-prem/configure/network-firewall). ## Rules Superblocks already applies Every Cloud-Prem WAF includes these rules, so you don't need to add your own versions of them: | Rule | What it does | | - | - | | Superblocks IP allowlist | Always allows the Superblocks deploy plane NAT egress IPs and support VPN CIDRs, so upgrade pipelines and support access are never rate-limited or blocked | | JWKS path carve-out | Allows `/.well-known/jwks.json` from any source IP so CloudFront can validate JWTs for deployed applications. Control plane WAF only | | Rate limit | Blocks IPs that send more than 10,000 requests in a 5-minute window | | AWS Common Rule Set | The [AWS Managed Rules Common Rule Set](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-crs), which protects against common web exploits such as those in the OWASP Top 10 | ## How your rules are evaluated AWS WAF evaluates rules in priority order, lowest first. Rules fall into three priority bands: | Priority | Rules | | - | - | | 0–19 | Superblocks critical rules: the Superblocks IP allowlist (0) and the JWKS path carve-out (10) | | 20–99 | **Your rule groups**, in the order you list them | | 100+ | Superblocks generic rules: the rate limit (100) and the AWS Common Rule Set (105) | The Superblocks critical rules always run before yours, so your rule groups can't block Superblocks upgrades, support access, or JWT validation. In AWS WAF, an **Allow** or **Block** action stops evaluation. If one of your rules allows a request, the request skips the rate limit and the AWS Common Rule Set. Prefer **Block** and **Count** actions in your rule groups, and use **Allow** only for traffic you trust fully. ## Add rule groups Your rule groups are attached to the regional and global WAFs. AWS only lets a web ACL use rule groups with the same scope, so create each rule group in both scopes: | WAF | Rule group scope | Create it in | | - | - | - | | Regional | Regional | The **same AWS region as your Cloud-Prem control plane** | | Global | CloudFront | **`us-east-1`**, whatever region your Cloud-Prem instance runs in | Rule groups in any other region can't be attached. For example, if your Cloud-Prem control plane runs in `eu-west-1`, create the Regional rule group in `eu-west-1` and the CloudFront rule group in `us-east-1`. The IP sets your rules reference must be in the same scope and region as their rule group. 1. Create your rule groups in AWS WAF, in both scopes and regions. See [Managing your own rule groups](https://docs.aws.amazon.com/waf/latest/developerguide/waf-user-created-rule-groups.html) in the AWS documentation. 2. Send the rule group ARNs to your Superblocks deployment team, in the order you want them evaluated. 3. Superblocks attaches them at the next deployment. You can add rule groups during your initial deployment or at any time after. ## Update your rules To add, change, or remove rules, edit the rules in the rule groups you've already given Superblocks. Because your rule groups are attached by ARN, your changes take effect right away, without a Superblocks deployment or a request to your deployment team. * **Update both scopes.** Make the same change to the Regional and the CloudFront copies of the rule group. * **Don't create your own web ACL.** AWS allows only one web ACL per resource, so associating your own web ACL with Cloud-Prem resources replaces the Superblocks web ACL and removes the Superblocks IP allowlist, rate limit, and AWS Common Rule Set. * **Don't edit the Superblocks web ACLs directly.** Superblocks manages them, and changes made outside a deployment can be overwritten. If new rules would exceed the rule group's capacity, which AWS fixes when the rule group is created, create a new rule group with more capacity and send its ARN to your deployment team. ## Change or remove rule groups To add a new rule group, remove one, or change their order, send the updated list of ARNs to your deployment team. Changes take effect at the next deployment. ## Common use cases Most customers use rule groups to restrict who can reach their instance. The examples below are rules for the AWS WAF console's rule JSON editor. Replace the IP set ARNs with your own, and create the [IP sets](https://docs.aws.amazon.com/waf/latest/developerguide/waf-ip-set-managing.html) in the same scope and region as the rule group. Test before you enforce Set a new rule's action to **Count** instead of **Block**, watch its CloudWatch metrics or sampled requests to see what it would block, then switch it to **Block**. ### Allow only known IP addresses Block every request that doesn't come from an IP address you trust. Write this as a **Block** rule for traffic outside your IP set, not an **Allow** rule for traffic inside it. An Allow rule would skip the Superblocks rate limit and AWS Common Rule Set. ```json theme={null} { "Name": "block-outside-ip-allowlist", "Priority": 0, "Action": { "Block": {} }, "Statement": { "NotStatement": { "Statement": { "IPSetReferenceStatement": { "ARN": "" } } } }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "block-outside-ip-allowlist" } } ``` Your IP set must include every source that reaches your instance, or those requests are blocked. Check for: * **Corporate network egress IPs** for offices and other locations where builders and app users work. * **VPN egress IPs** for remote employees and contractors. * **Self-hosted data plane egress IPs**, if you run data planes outside the Cloud-Prem account. * **CI/CD and automation IPs** for pipelines and scripts that call the Superblocks APIs, the [MCP server](/admin/mcp-server), or the [CLI](/building-with-clark/developing-apps-in-code). * **Identity provider IPs** for SCIM provisioning. See [Allow SCIM requests from your identity provider](#allow-scim-requests-from-your-identity-provider). AWS WAF IP sets hold either IPv4 or IPv6 addresses, not both. If any of these sources use IPv6, create a second IP set and reference both. ### Allow SCIM requests from your identity provider If you use [SCIM](/admin/org-administration/auth/scim/index), your identity provider sends provisioning requests to `https://{tenant}.superblocks.com/scim/v2` from its own servers, not from your network. An IP allowlist blocks them unless you allow your identity provider's IP ranges. AWS WAF can't match requests by source domain, so allow your identity provider by IP range instead, and only for the SCIM path: | Identity provider | Published IP ranges | | - | - | | Okta | [Okta IP address ranges](https://help.okta.com/en-us/content/topics/security/ip-address-allow-listing.htm) for your Okta cell | | Microsoft Entra ID | The `AzureActiveDirectory` [service tag](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#ip-ranges) | Put those ranges in their own IP set and add a SCIM exception to your IP allowlist rule. This version blocks a request unless it comes from your allowed IPs, or it's a SCIM request from your identity provider: ```json theme={null} { "Name": "block-outside-ip-allowlist", "Priority": 0, "Action": { "Block": {} }, "Statement": { "AndStatement": { "Statements": [ { "NotStatement": { "Statement": { "IPSetReferenceStatement": { "ARN": "" } } } }, { "NotStatement": { "Statement": { "AndStatement": { "Statements": [ { "ByteMatchStatement": { "SearchString": "/scim/v2", "FieldToMatch": { "UriPath": {} }, "PositionalConstraint": "STARTS_WITH", "TextTransformations": [{ "Priority": 0, "Type": "NONE" }] } }, { "IPSetReferenceStatement": { "ARN": "" } } ] } } } } ] } }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "block-outside-ip-allowlist" } } ``` Identity providers update their IP ranges over time. Keep the IP set current, or provisioning starts failing. ### Restrict access by country Block requests from outside the countries where your organization operates. List the allowed countries as two-letter [ISO 3166 country codes](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-type-geo-match.html): ```json theme={null} { "Name": "block-outside-allowed-countries", "Priority": 1, "Action": { "Block": {} }, "Statement": { "NotStatement": { "Statement": { "GeoMatchStatement": { "CountryCodes": ["US", "CA"] } } } }, "VisibilityConfig": { "SampledRequestsEnabled": true, "CloudWatchMetricsEnabled": true, "MetricName": "block-outside-allowed-countries" } } ``` Country matching is based on the request's IP address, so it also blocks your identity provider, CI/CD pipelines, and travelling users when their traffic comes from another country. Account for the same sources as an [IP allowlist](#allow-only-known-ip-addresses). Superblocks support and upgrade traffic isn't affected, because the Superblocks IP allowlist runs first. ## Related * [Optional configurations](/enterprise/cloud-prem/configure/index) * [AWS Network Firewall](/enterprise/cloud-prem/configure/network-firewall) # Cloud-Prem deployment guide Source: https://docs.superblocks.com/enterprise/cloud-prem/deployment-guide Superblocks deploys and operates Cloud-Prem for you. Your team prepares an AWS account, runs a Superblocks-provided Terraform configuration, and hands off to Superblocks, who builds the platform in your account and keeps it running. ## Who does what | Your team | Superblocks | | - | - | | Prepares the AWS account that hosts Cloud-Prem | Provides the Terraform configuration for your setup | | Runs the Terraform and shares the results | Deploys the full platform into your account | | Chooses and provides any [optional configurations](/enterprise/cloud-prem/configure/index) | Applies your configurations as part of a deployment | | Creates an SSO application in your identity provider | Configures SSO on your instance | | Invites builders after go-live | Operates, upgrades, and supports the platform | ## Deployment stages **1. Plan your deployment** Work with your Superblocks deployment team to choose an AWS region and identify who on your team will prepare the account, review security, and administer Superblocks. Review the [optional configurations](/enterprise/cloud-prem/configure/index) and decide which ones to include from day one. **2. Prepare for deployment** **Set up single sign-on.** Cloud-Prem instances are SSO only, so no one can sign in until SSO is configured. Create an application in your identity provider by following the guide for your provider in [Single sign-on](/admin/org-administration/auth/single-sign-on/index). Prepare settings for any optional configurations you chose. For example, if you're sending telemetry to your own tools, create the [observability destinations](/enterprise/cloud-prem/configure/observability-destinations) secret now. **3. Run the Superblocks Terraform and hand off** Run the Terraform configuration that Superblocks provides in your Cloud-Prem account. It sets up two things: * **An in-account deployment mechanism** that deploys and upgrades Cloud-Prem from inside your account. * **Cross-account IAM roles** that Superblocks uses to trigger deployments and manage your instance. When the Terraform finishes, tell your deployment team, including which optional configurations you've prepared so they're part of the initial deployment. **4. Superblocks deploys Cloud-Prem** Superblocks deploys the platform into your account and configures SSO and any optional configurations you prepared. Your deployment team lets you know when your instance is ready. **5. Go live** Sign in to your Cloud-Prem instance through your identity provider, then invite your builders. Optionally, set up [SCIM](/admin/org-administration/auth/scim/index) to provision users and groups from your identity provider. ## Add configurations after go-live You don't have to decide everything up front. Optional configurations can be added or changed after go-live: prepare any settings described on the configuration's page, then tell your Superblocks deployment team. Superblocks applies the change at the next deployment. ## Next steps > [card] [Optional configurations](/enterprise/cloud-prem/configure/index) > > See every opt-in configuration and how it's applied. > [card] [Cloud-Prem on AWS](/enterprise/cloud-prem/aws) > > How Cloud-Prem works and why teams choose it. # Enterprise deployment Source: https://docs.superblocks.com/enterprise/deployment-overview Superblocks is built to integrate seamlessly into enterprise environments, with flexible deployment options that balance speed, security, and compliance. Superblocks offers three deployment models: 1. **Cloud** – All data and AI inference run in the Superblocks Cloud 2. **Hybrid** – Production data remains in the customer VPC for deployed apps, while only non-production data is accessed by Clark in the Superblocks Cloud 3. **Cloud-Prem** – The full Superblocks platform, including AI inference, is deployed within your AWS environment and fully managed by Superblocks ## Superblocks architecture Superblocks is built on a modular, enterprise-grade architecture with clear separation between control, development, inference, and execution. * **Control Plane:** Hosts the Superblocks Editor and platform services, including metadata, configuration, access control, and orchestration required to build and manage applications. * **Clark Development Sandbox**: A secure, ephemeral development sandbox where Clark generates and modifies code. The Devbox includes access to tools, a Vite dev server, and a browser environment for automated testing. * **Clark AI Agent**: Executes AI inference in Superblocks Cloud (Cloud and Hybrid) or in the customer's cloud environment (Cloud-Prem). Data sent to the AI model is never used for training. Model requests and responses are retained to provide the conversational chat experience. * **Data Plane**: Executes backend logic written in SQL, Python, or JavaScript. The data plane securely proxies requests to customer APIs * **Global Cache**: Serves deployed application frontends globally, providing low-latency access and improved performance for end users. ### Cloud architecture ![](https://mintcdn.com/superblocks/9gY8R6Ph9jAsQ-Bn/images/enterprise-deployment/cloud.png?fit=max\&auto=format\&n=9gY8R6Ph9jAsQ-Bn\&q=85\&s=3bda9f8321566ba6c2ecdd8964822b27) In the **Cloud** deployment model, all Superblocks services are hosted in the Superblocks Cloud. Customers securely connect their SaaS applications, APIs, and databases directly to the platform. All data is encrypted in transit and at rest. Each code execution runs in an isolated, ephemeral environment, ensuring strong tenant isolation and default data segregation. ### Hybrid architecture ![](https://mintcdn.com/superblocks/9gY8R6Ph9jAsQ-Bn/images/enterprise-deployment/hybrid.png?fit=max\&auto=format\&n=9gY8R6Ph9jAsQ-Bn\&q=85\&s=75ce3ea7b557ffad015f9b29b42dca96) In the Hybrid deployment model, the Superblocks data plane is deployed within the customer’s VPC, where all backend code executes close to customer data for low latency and data residency. Production customer data remains entirely within the customer VPC. Clark operates in the Superblocks Cloud, where AI inference is performed using non-production data only. Most Hybrid customers run two data planes, one for pre-production and one for production. See [Plan your data planes](/enterprise/hybrid-architecture/plan/index). ### Cloud-Prem architecture ![](https://mintcdn.com/superblocks/OrdihIqDANiNTUaJ/images/enterprise-deployment/cloud-prem.png?fit=max\&auto=format\&n=OrdihIqDANiNTUaJ\&q=85\&s=e081bef89cb8d516fd7f91b1b02dd23d) In the Cloud-Prem deployment model, the entire Superblocks platform, including the control plane, data plane, and Clark inference is deployed within the customer’s AWS environment. This deployment is fully managed by Superblocks within your cloud environment. No customer data leaves the customer cloud environment, ensuring maximum data residency, isolation, and compliance. For global enterprises with multi-region or multi-cloud environments, a single control plane is utilized, while a data plane is deployed for each region that customer data will be accessed. ![](https://mintcdn.com/superblocks/AmKWe0YbRbizsd5G/images/enterprise-deployment/cloud-prem-multi.png?fit=max\&auto=format\&n=AmKWe0YbRbizsd5G\&q=85\&s=819049290c7a6f2edb076a2bc79d6d50) ## Choosing a deployment model | Deployment Model | Primary Advantage | Clark Inference | Clark Dev Sandbox | Control Plane | Data Plane | Network Setup | | - | - | - | - | - | - | - | | **Cloud** | Fastest setup with fully managed infrastructure | Superblocks Cloud | Superblocks Cloud | Superblocks Cloud | Superblocks Cloud | Public endpoints, IP allowlisting | | **Hybrid** | Production data stays in-customer VPC with cloud-managed AI | Superblocks Cloud (non-prod data only) | Superblocks Cloud | Superblocks Cloud | Customer AWS, GCP or Azure Account | Data plane reaches private data sources without opening firewall | | **Cloud-Prem** | Maximum data residency, isolation, and compliance | Customer AWS Account | Customer AWS Account | Customer AWS Account | Customer AWS Account | Full deployment in customer cloud | **Cloud** is recommended for organizations seeking the fastest time to value with minimal infrastructure and operational overhead. This model works best when production systems can be securely accessed from the public internet or support IP allowlisting, and when strict data residency or in-VPC execution requirements are not needed. **Hybrid** is recommended for organizations that need to keep production data and execution within their own VPC for security, compliance, or latency reasons, while still benefiting from a fully managed control plane and AI-assisted development in the cloud. This model is ideal when production systems cannot be publicly exposed, but non-production environments can safely interact with cloud-hosted services. **Cloud-Prem** is recommended for organizations with the most stringent security, compliance, or data-residency requirements that require all application execution, AI inference, and platform services to run entirely within their own cloud environment. This model is ideal for regulated industries or environments where external connectivity is restricted, while still allowing Superblocks to fully manage and operate the platform inside the customer’s cloud boundary. # AWS ECS Fargate Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/aws_ecs_fargate Estimated deployment time: 5 minutes The [Superblocks Terraform module for AWS](https://registry.terraform.io/modules/superblocksteam/superblocks/aws/latest) deploys the data plane as an ECS Fargate service and configures all the required infrastructure to expose it to end users in Superblocks. ## Deploy with Terraform Follow the steps below to deploy the data plane on ECS Fargate using Terraform. ### Install prerequisites * Install [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) * Install [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and configure [AWS Credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) file Do not use root user credentials when deploying the data plane. To learn more about best practices for managing access keys, visit the AWS docs [here](https://docs.aws.amazon.com/accounts/latest/reference/credentials-access-keys-best-practices.html). ### Create Terraform file To get started, navigate to the [Setup Wizard](https://app.superblocks.com/opas) to generate a `superblocks_agent_key`. We recommend following [secret management best practices](https://awstip.com/managing-secrets-on-terraform-71ed245a455f) such as using environment variables, encrypted files, or a secret store to securely pass the `superblocks_agent_key` into your Terraform code. ```hcl theme={null} module "terraform_aws_superblocks" { source = "superblocksteam/superblocks/aws" version = "~>1.0" vpc_id = "[VPC_ID]" lb_subnet_ids = "[LIST_OF_SUBNET_IDS_FOR_LOAD_BALANCER]" ecs_subnet_ids = "[LIST_OF_SUBNET_IDS_FOR_SUPERBLOCKS_DATA_PLANE_ECS_CLUSTER]" domain = "[DOMAIN]" subdomain = "[SUBDOMAIN_FOR_SUPERBLOCKS_DATA_PLANE]" superblocks_agent_key = "[YOUR_AGENT_KEY]" } ``` If you use the EU Superblocks instance, also set `superblocks_agent_data_domain = "eu.superblocks.com"`. By default, the module deploys the data plane within an existing VPC (where your underlying data sources live). To find your VPC details, use `aws ec2 describe-vpcs` or navigate to your VPC in the AWS management console. Alternatively, if you want your agent to access data across multiple VPCs, update the module to create a new VPC then set up VPC peering between the newly configured VPC and existing AWS VPCs. To update the module to create a new VPC, set the following variable. ```hcl theme={null} create_vpc = true ``` For more details on configuring VPC peering see [Connect VPCs using VPC peering](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-peering.html). For all available configuration options, see the [Terraform registry](https://registry.terraform.io/modules/superblocksteam/superblocks/aws/latest). ### Initialize and apply Terraform ```bash theme={null} terraform init terraform apply ``` Note, the Terraform script may fail if you have reached your AWS Service Limits. For more information on managing your AWS account limits, visit [Managing AWS Service Quotas](https://aws.amazon.com/premiumsupport/knowledge-center/manage-service-limits/). ## Billable services The Terraform module makes use of the following AWS services. Be aware of the pricing associated with these. * [VPC](https://aws.amazon.com/vpc/pricing/) - Network where all cloud resources reside (may be additional cost depending on settings and connecting VPN) * [ECS Fargate](https://aws.amazon.com/fargate/pricing/) - ECS cluster, service, and task to run the data plane container * [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/pricing/?nc=sn\&loc=3) - ALB to front the Fargate service * [Route 53](https://aws.amazon.com/route53/pricing/) - Hosted zone and record for DNS (optional) # Azure Container Apps Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/azure_container_apps This guide walks you through deploying the Superblocks data plane on **Azure Container Apps** using either the **Azure Portal**, the **Azure CLI** or a **YAML File**. ## Prerequisites * Azure subscription with permissions to create resources * Superblocks Agent Key ([generate one](https://app.superblocks.com/access-tokens)) * [Install Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-macos) (See [quickstart](https://learn.microsoft.com/en-us/azure/container-apps/get-started?tabs=bash) for example usage) ## Deploy resources ### Create Subnet If your agent needs to talk to internal APIs and databases inside a specific Azure VNet, create a new subnet inside that VNet. The subnet should be dedicated to the Azure Container Apps Environment with no other resources. > [tab] Azure Portal > > Navigate to your VNet then choose **Settings** -> **Subnets** -> **+ Subnet**. Configure the subnet settings, including setting **Subnet Delegation** to "Microsoft.App/environments". > [tab] Azure CLI > > Run the following command to create a new subnet delegated to container app environments. > > ```bash theme={null} > az network vnet subnet create \ > --resource-group MyResourceGroup \ > --vnet-name MyVnet \ > --name MySubnet \ > --address-prefixes 10.0.0.0/24 \ > --delegations Microsoft.App/environments > ``` ### Create Container Apps Environment > [tab] Azure Portal > > 1. Navigate to **Container Apps** -> **+ Create** -> **Container App** > 2. Under **Container Apps environment**, click the link to **Create new environment** > 3. Configure **Networking** to enable or disable **Public Network Access** and specify the **Virtual network** using the VNet / subnet created in the [previous section](#create-subnet). > [tab] Azure CLI > > Run the following command, using `--infrastructure-subnet-resource-id` to specify the Subnet ID for the subnet created in the [previous section](#create-subnet). > > ```bash theme={null} > az containerapp env create \ > --name MyContainerappEnvironment \ > --resource-group MyResourceGroup \ > --location eastus \ > --infrastructure-subnet-resource-id SUBNET_ID > ``` For more information on public vs. private endpoints, see [Networking in Azure Container Apps environment](https://learn.microsoft.com/en-us/azure/container-apps/networking?tabs=workload-profiles-env%2Cazure-cli). ### Create Container App > [tab] Azure Portal > > 1. Go to **Container Apps** → **+ Create** > 2. Under **Basics** tab, specify the subscription, resource group, app name, and container apps environment (see [Create container apps environment](#create-container-apps-environment)) > 3. Under **Container** tab: > > **Container details** > > These are the required container image settings if using the Superblocks hosted image. Update these accordingly if you host your own custom image. > > * Image source: Select **Docker Hub or other registries** > * Image type: Select **Public** > * Registry login server: `ghcr.io` > * Image: `superblocksteam/agent:latest` > > **Container resource allocation** > > * Set 2 CPU, 4.0 GiB memory > > **Environment variables** > > * Add `SUPERBLOCKS_AGENT_DATA_DOMAIN = app.superblocks.com` > * Add `SUPERBLOCKS_ORCHESTRATOR_AGENT_HOST_URL = https:.` > * Add `SUPERBLOCKS_ORCHESTRATOR_AGENT_TAGS = profile:*` > 4. Under **Ingress** tab: > * Enable ingress, configure **Ingress traffic** settings, and set **Target port** to 8080 > 5. Click **Create** > > When creating the container app through the Azure Portal, there are a few additional configuration steps required after the container app is created. Navigate to the container app resource and complete the following: > > * Under **Application** -> **Scale**, set **Min Replicas** to 1. To adjust horizontal scaling, optionally configure **Max replicas**. > * Under **Security** -> **Secrets**, create a secret to store the Superblocks agent key, using either a Container Apps Secret or Key Vault reference. > * Under **Application** -> **Containers**, select the **Environment variables** tab and set both `SUPERBLOCKS_AGENT_KEY` and `SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_KEY` to the previously created secret reference. Click **Save as a new revision**. > [tab] Azure CLI > > First, install the required extensions and providers: > > ```bash theme={null} > az extension add --name containerapp --upgrade > az provider register --namespace Microsoft.App > az provider register --namespace Microsoft.OperationalInsights > ``` > > ```bash theme={null} > APP_NAME="superblocks-agent" > AGENT_KEY="" > AGENT_URL="" > > az containerapp create \ > --name $APP_NAME \ > --resource-group myresourcegroup \ > --environment superblocks-env \ > --image superblocksteam/agent:latest \ > --cpu 2.0 --memory 4.0Gi \ > --ingress external --target-port 8080 \ > --secrets agent-key=$AGENT_KEY \ > --env-vars SUPERBLOCKS_AGENT_KEY=secretref:agent-key \ > SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_KEY=secretref:agent-key \ > SUPERBLOCKS_AGENT_DATA_DOMAIN="app.superblocks.com" \ > SUPERBLOCKS_ORCHESTRATOR_AGENT_HOST_URL=$AGENT_URL \ > SUPERBLOCKS_ORCHESTRATOR_AGENT_TAGS="profile:*" \ > --min-replicas 1 --max-replicas 1 > ``` > > **Note:** If using a private registry, provide full image path and configure credentials accordingly. > [tab] YAML Template > > You can deploy the Superblocks data plane on Azure Container Apps by creating a `.yaml` file and passing it to the `az containerapp create` command. > > ```yaml theme={null} > properties: > environmentId: "/subscriptions//resourceGroups//providers/Microsoft.App/managedEnvironments/" > configuration: > ingress: > external: > allowInsecure: > targetPort: 8080 > secrets: > - name: "agent-key" > value: "" > template: > containers: > - image: ghcr.io/superblocksteam/agent:latest > name: > resources: > cpu: 2.0 > memory: 4.0Gi > env: > - name: "SUPERBLOCKS_ORCHESTRATOR_SUPERBLOCKS_KEY" > secretRef: "agent-key" > - name: "SUPERBLOCKS_AGENT_KEY" > secretRef: "agent-key" > - name: "SUPERBLOCKS_AGENT_DATA_DOMAIN" > value: "app.superblocks.com" > - name: "SUPERBLOCKS_ORCHESTRATOR_AGENT_HOST_URL" > value: "https:." > - name: "SUPERBLOCKS_ORCHESTRATOR_AGENT_TAGS" > value: "profile:*" > scale: > minReplicas: 1 > maxReplicas: 1 > ``` > > Run: > > ```bash theme={null} > az containerapp create -n ContainerAppName -g MyResourceGroup --environment MyContainerAppEnv --yaml "path/to/yaml/file.yml" > ``` ## Verify agent is running Check the application status: ```bash theme={null} az containerapp show \ --name superblocks-agent \ --resource-group myresourcegroup \ --query properties.configuration.ingress.fqdn -o tsv ``` View application logs: ```bash theme={null} az containerapp logs show \ --name my-container-app \ --resource-group my-container-apps ``` Visit the [data plane page](https://app.superblocks.com/opas) in Superblocks to confirm the service appears as **Active**. ## Billable services The Superblocks data plane may make use of the following Azure services. Be aware of the pricing associated with these. * [Azure Container Apps](https://azure.microsoft.com/en-us/pricing/details/container-apps/) - Serverless container platform with consumption-based pricing (includes free monthly grants of 180,000 vCPU-seconds, 360,000 GiB-seconds, and 2M requests) * [Azure Monitor & Log Analytics](https://azure.microsoft.com/en-us/pricing/details/monitor/) - Logging and monitoring solution for diagnostics (optional) * [Azure Key Vault](https://azure.microsoft.com/en-us/pricing/details/key-vault/) - Secure secret storage for credentials and configuration (optional) * [Virtual Network](https://azure.microsoft.com/en-us/pricing/details/virtual-network/) - Network infrastructure for private deployments (optional) # Google Cloud Run Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/google_cloud_run Estimated deployment time: 5 minutes The [Superblocks Terraform module for Google](https://registry.terraform.io/modules/superblocksteam/superblocks/google/latest) deploys the data plane as a Google Cloud Run service and configures all the required infrastructure to expose it to end users in Superblocks. ## Deploy with Terraform Follow the steps below to deploy the data plane on Google Cloud Run using Terraform. ### Install prerequisites * Install [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) * Install and authorize the [gcloud CLI](https://cloud.google.com/sdk/docs/authorizing) ### Create Terraform file To get started, navigate to the [Setup Wizard](https://app.superblocks.com/opas) to generate a `superblocks_agent_key`. We recommend following [secret management best practices](https://awstip.com/managing-secrets-on-terraform-71ed245a455f) such as using environment variables, encrypted files, or a secret store to securely pass the `superblocks_agent_key` into your Terraform code. ```hcl theme={null} module "terraform_google_superblocks" { source = "superblocksteam/superblocks/google" version = "~>1.0" project_id = "[GOOGLE_CLOUD_PROJECT_ID]" region = "[GOOGLE_CLOUD_REGION]" superblocks_agent_key = "[YOUR_AGENT_KEY]" # Subdomain & domain in your Superblocks data plane host url, for example superblocks.example.com sudomain = "[YOUR_SUBDOMAIN]" domain = "[YOUR_DOMAIN]" # Google Cloud DNS Zone Name zone_name = "[YOUR_DOMAINS_CLOUD_DNS_ZONE_NAME]" } ``` If you use the EU Superblocks instance, also set `superblocks_agent_data_domain = "eu.superblocks.com"`. If you use Google Cloud DNS, find the `zone_name` for your `domain` by running `gcloud dns managed-zones list --filter "dns_name ~ ${domain}`. If you don't use Google Cloud DNS, see the [Custom Domain Mapping](https://registry.terraform.io/modules/superblocksteam/superblocks/google/latest#custom-domain-mapping) section for how you can manually configure the DNS for your agent. ### Initialize and apply Terraform ```bash theme={null} terraform init terraform apply ``` For all available configuration options, see the [Terraform registry](https://registry.terraform.io/modules/superblocksteam/superblocks/google/latest). ## Billable services The Terraform module makes use of the following GCP services. Be aware of the pricing associated with these. * [Cloud Run](https://cloud.google.com/run/pricing) - Service to run the data plane container * [Cloud DNS](https://cloud.google.com/dns/pricing) - Managed zone and record for DNS (optional) # Deployment overview Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/index Deploy the Superblocks data plane in your network ## Before you deploy [Plan your data planes](/enterprise/hybrid-architecture/plan/index) first. That page decides how many data planes you run and which data tags each one serves. This page assumes that decision is already made. ## Prerequisites * An account and adequate permission to create new services within your cloud provider (ex: AWS, Google Cloud, Azure, etc) * Admin permissions in your Superblocks organization * Ability to create DNS records for your company's DNS provider (if you plan to create a custom domain for your agent) ## Required knowledge Deploying and managing the Superblocks data plane requires knowledge of how to manage and scale cloud infrastructure. Usually this means the data plane is deployed by a DevOps engineer or someone with equivalent experience. Knowledge and experience with specific services will depend on the cloud provider and components being deployed, but should generally include familiarity with: * Running containerized services using Docker, Kubernetes, or a container management service such as ECS Fargate or Google Cloud Run * Configuring DNS records in your domain registrar (ex: Route53, Google Domains, etc) * Configuring and managing SSL certificates * Experience configuring a network loadbalancer or reverse proxy ## Deployment methods For a production deployment, use one of the following options depending on your infrastructure. * [AWS ECS Fargate](/enterprise/hybrid-architecture/deployment/aws_ecs_fargate) * [Google Cloud Run](/enterprise/hybrid-architecture/deployment/google_cloud_run) * [Kubernetes](/enterprise/hybrid-architecture/deployment/kubernetes) * [Azure Container Apps](/enterprise/hybrid-architecture/deployment/azure_container_apps) * [Virtual Machine](/enterprise/hybrid-architecture/deployment/virtual_machine) Alternatively, a deployment is available for [local testing](/enterprise/hybrid-architecture/deployment/local_docker). # Kubernetes Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/kubernetes Estimated deployment time: 15 minutes The Superblocks data plane can be deployed on any Kubernetes cluster with the Superblocks Helm chart. If your organization doesn't use Helm to manage Kubernetes resources, you can still install the [Helm CLI](https://helm.sh/docs/intro/install/) and use it to generate the [manifest templates](https://helm.sh/docs/helm/helm_template/) to deploy directly. ## Installation ### Add the chart repository ```bash theme={null} helm repo add superblocks https://charts.superblocks.com/superblocks helm repo update ``` ### Configure values file Create a local `values.yaml` file with the default chart values. You can export the defaults by running `helm show values superblocks/superblocks-agent > values.yaml`. Aside from the default settings, the following settings are required to enable Ingress and allow communication from your users to the agent running in the cluster. ```yaml theme={null} superblocks: agentHostUrl: "https://SUBDOMAIN.DOMAIN.TLD" agentRedisPassword: "my-redis-password" # Existing agentRedisPassword secret must contain the value: # SUPERBLOCKS_AGENT_REDIS_PASSWORD: # agentRedisPasswordExistingSecret: "my-redis-password-secret", optional. Secret is created for you if not specified. #(...) service: # Use ClusterIP if your ingress controller routes traffic directly to pods. # Otherwise, update the service type based on your ingress controller settings. # For example, defaults for native cloud controllers require NodePort. type: ClusterIP ports: grpc: 8081 http: 8080 metrics: 9090 ingress: enabled: true class: "" # nginx annotations: {} # kubernetes.io/tls-acme: "true" hosts: - host: SUBDOMAIN.DOMAIN.TLD paths: - path: / pathType: Prefix tls: [] # - secretName: chart-example-tls # hosts: # - SUBDOMAIN.DOMAIN.TLD ``` The values for `superblocks.agentHostUrl` and `ingress.hosts[0].host` should be the same DNS entry (CNAME or A record) that points to the [ingress-managed load balancer](https://kubernetes.io/docs/concepts/services-networking/ingress/#what-is-ingress) in front of the agent. If you use the EU Superblocks instance, also set `superblocks.agentDataDomain` to `eu.superblocks.com`. ### Deploy the chart Navigate to the [Setup Wizard](https://app.superblocks.com/opas) and click on the relevant Kubernetes tab for your platform (EKS, GKE, or AKS). After making changes to `values.yaml`, save and deploy the chart. Adjust `superblocks.agentTags` as needed, as described in [Set agent tags](/enterprise/hybrid-architecture/deployment/multiple_environments). ```bash theme={null} helm upgrade -i -n superblocks superblocks-agent superblocks/superblocks-agent \ --create-namespace \ -f values.yaml \ --set superblocks.agentKey='' \ --set superblocks.agentTags='profile:*' \ --set superblocks.agentDataDomain="app.superblocks.com" ``` ## Billable services When running the data plane on Kubernetes, it is important to be aware of your container management provider's pricing (i.e. [EKS](https://aws.amazon.com/eks/pricing/), [GKE](https://cloud.google.com/kubernetes-engine/pricing), [AKS](https://azure.microsoft.com/en-us/pricing/details/kubernetes-service/)) and the cost of any associated infrastructure like networking, load balancers, and DNS. # Local Docker Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/local_docker Estimated deployment time: 2 minutes For testing purposes, you can install the agent on your local machine with [Docker Compose](https://docs.docker.com/compose/install/) following these steps. Meant for testing only. A local deployment means you are the only user who can access the agent from Superblocks. To deploy the agent for use across your organization, use one of the [production deployment methods](/enterprise/hybrid-architecture/deployment/). ## Install and run container on your machine To generate a `SUPERBLOCKS_AGENT_KEY`, go to the Superblocks [Setup Wizard](https://app.superblocks.com/opas). ```bash theme={null} curl -s https://charts.superblocks.com/agent/compose.yaml | \ SUPERBLOCKS_AGENT_KEY="" \ SUPERBLOCKS_AGENT_HOST_URL="http://localhost:8080" \ SUPERBLOCKS_AGENT_DATA_DOMAIN="app.superblocks.com" \ SUPERBLOCKS_DOCKER_AGENT_TAG="latest" \ docker compose -p superblocks -f - up ``` If you use the EU Superblocks instance, set `SUPERBLOCKS_AGENT_DATA_DOMAIN` to `eu.superblocks.com`. ## Connect to a local database To connect your agent to a locally running database, you must specify `host.docker.internal` in the Superblocks integration config, not `localhost`. More on this [here](/integrations/troubleshooting/troubleshooting-databases#testing-with-hybrid-using-localhost). # Set agent tags Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/multiple_environments After you [plan your data planes](/enterprise/hybrid-architecture/plan/index), set each data plane's agent tags to the exact tags it serves. To configure agent tags, set the following variable depending on your deployment method. The value is a comma-separated list, so a data plane that serves two tags uses `profile:dev,profile:staging`. > [tab] Terraform > > ``` > superblocks_agent_tags = "profile:" > ``` > [tab] Helm > > ```yaml theme={null} > superblocks: > #(...) > agentTags: "profile:" > ``` > [tab] Docker > > When running the agent with Docker Compose, set `SUPERBLOCKS_AGENT_TAGS` along with other required environment variables. > > ``` > curl -s https://charts.superblocks.com/agent/compose.yaml | \ > SUPERBLOCKS_AGENT_TAGS="profile:" \ > docker compose -p superblocks -f - up > ``` The agent tag format uses the `profile:` prefix for backwards compatibility. Each `profile:` value maps to the data tag with the matching key. If you enable [Superblocks Database](/admin/superblocks-on-aws/database-setup), do not use `profile:*`; database work is routed by exact data tag. See [Data planes and Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database). # Virtual machine Source: https://docs.superblocks.com/enterprise/hybrid-architecture/deployment/virtual_machine Estimated deployment time: 10 minutes The Superblocks data plane can be deployed on a virtual machine with Docker Compose. Note, this method is not as scalable as using container management services like [AWS ECS Fargate](./aws_ecs_fargate) or [Google Cloud Run](./google_cloud_run). If you use this method in production, we recommend deploying on a minimum of 3 instances. ## Deploy Follow the steps below to deploy the data plane on a virtual machine. ### Launch VM Launch a virtual machine using Amazon Linux, Ubuntu, CentOS, or Debian. The instance should have at least 4 GiB of memory and 20 GiB of storage. Make sure the instance's security group allows inbound traffic on HTTP port 80 and HTTPS port 443. Example below for an AWS EC2 instance. ![data plane security group inbound rules](https://mintcdn.com/superblocks/0x599EHVvFHaqYo0/images/on-premise-agent/opa_quickstart_inbound_rules.png?fit=max\&auto=format\&n=0x599EHVvFHaqYo0\&q=85\&s=72c8406b526ee21d2c82788fef17d5a9) ### Create CNAME or A record Next, create a CNAME or A record of a custom domain pointed to the IP address of the VM. This custom domain will be used in the agent configuration. ### Install agent **1. Download script on VM** ```bash theme={null} sudo curl -SL https://charts.superblocks.com/agent/quickstart.sh -o /usr/bin/superblocks sudo chmod +x /usr/bin/superblocks ``` **2. Configure agent variables** To generate a `SUPERBLOCKS_AGENT_KEY`, go to the Superblocks [Setup Wizard](https://app.superblocks.com/opas). ```bash theme={null} sudo superblocks conf SUPERBLOCKS_AGENT_KEY [YOUR_AGENT_KEY] sudo superblocks conf SUPERBLOCKS_LETSENCRYPT_EMAIL [YOUR_EMAIL_ADDRESS] sudo superblocks conf SUPERBLOCKS_AGENT_HOST_URL https://YOUR.VALID.DOMAIN.COM sudo superblocks conf SUPERBLOCKS_PROXY_REPLICA_COUNT 1 sudo superblocks conf SUPERBLOCKS_DOCKER_AGENT_TAG latest ``` Note, `SUPERBLOCKS_AGENT_HOST_URL` is the custom domain configured under prerequisites. If you use the EU Superblocks instance, set `SUPERBLOCKS_AGENT_DATA_DOMAIN` to `eu.superblocks.com`. **3. Start the service** When starting for the first time, this will install docker and pull docker images. ```bash theme={null} sudo superblocks start ``` **4. Verify** After the installation completes, check that the service is successfully deployed and can be connected to locally. ```bash theme={null} curl localhost:8080/health ``` To validate that the service is up and available over https, visit `https://YOUR.VALID.DOMAIN.COM/health`. ![Verify data plane custom domain via HTTPS](https://mintcdn.com/superblocks/0x599EHVvFHaqYo0/images/on-premise-agent/opa_quickstart_verify.png?fit=max\&auto=format\&n=0x599EHVvFHaqYo0\&q=85\&s=4c7b7c1e607bd4d3dcc72b2a2b6d8e39) ## Billable services When running the data plane on a virtual machine, it is important to be aware of your cloud provider's instance pricing (i.e. [EC2](https://aws.amazon.com/ec2/pricing/), [GCE](https://cloud.google.com/compute/all-pricing), [Azure VM](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/series/)) and the cost of any associated infrastructure like networking, load balancers, and DNS. # Additional configuration Source: https://docs.superblocks.com/enterprise/hybrid-architecture/extend/additional-configuration Configure additional environment variables in the Superblocks data plane The data plane exposes certain environment variables for additional configuration. Depending on how the data plane is deployed, you can set these environment variables directly, or use deployment-specific variables like Helm chart values or Terraform settings. If the data plane's Helm chart or Terraform module does not expose a dedicated configuration for a given environment variable, the environment variable can be set using the generic configuration below: > [tab] Terraform > > Update your `main.tf` with a list of objects containing the environment variable names and values. > > ``` > superblocks_agent_environment_variables = [{name = "ENV_VAR_NAME", value = "value"}] > ``` > [tab] Helm > > Set environment variables under `extraEnv` or `envFrom` in the Helm chart `values.yaml`. > > ```yaml theme={null} > # Specify extra environment variables that will be applied > extraEnv: > ENV_VAR_NAME: value > > # Specify environment variables that will be applied from secrets or configmaps. > envFrom: > - secretRef: > name: my-agent-env-secret > - configMapRef: > name: my-agent-env-configmap > ``` ## Examples See the docs below for common environment variables pertaining to each category: * [Size and time limits](/enterprise/hybrid-architecture/manage/size_and_time_limits) * [Set agent tags](/enterprise/hybrid-architecture/deployment/multiple_environments) * [Database connection pooling](/enterprise/hybrid-architecture/manage/database_connection_pooling) * [Upgrading](/enterprise/hybrid-architecture/manage/upgrade) * [Data plane's local Redis](/enterprise/hybrid-architecture/manage/local_redis) # Storing environment variables Source: https://docs.superblocks.com/enterprise/hybrid-architecture/extend/storing-environment-variables You can store your credentials as environment variables when [self-hosting the Superblocks data plane](/enterprise/hybrid-architecture/overview), enabling you to store secrets locally rather than in the Superblocks Cloud. Environment variables prefixed with `SUPERBLOCKS_AGENT_APP_ENV_` can be referenced using the global `Env` object. ## Environment variable prefix (`SUPERBLOCKS_AGENT_APP_ENV_`) All environment variables that are prefixed with `SUPERBLOCKS_AGENT_APP_ENV_` are accessible through the `Env` global variable. You can use them in Superblocks with the environment variable name without the prefix (e.g. `Env.postgres_password`). To use: 1. Specify environment variables prefixed with `SUPERBLOCKS_AGENT_APP_ENV_` (e.g. `SUPERBLOCKS_AGENT_APP_ENV_POSTGRES_PASSWORD`) in the environment where the data plane is deployed 2. Reference the environment variable insider Superblocks as a property on the global `Env` object by the suffix of the environment variable (e.g. `{{Env.postgres_password}}` for the example above) ### Example: Configuring a Postgres integration with environment variable secrets 1. Expose the environment variables `SUPERBLOCKS_AGENT_APP_ENV_POSTGRES_USERNAME` and `SUPERBLOCKS_AGENT_APP_ENV_POSTGRES_PASSWORD` in your data plane deployment 2. Navigate to the [Integrations](https://app.superblocks.com/integrations) tab in the menu bar on the left side of the Home page and select a [Postgres](https://app.superblocks.com/integrations/postgres) integration 3. Enable "Fetch credentials dynamically" via the toggle at the top of the Postgres integration form 4. Enter the username and password as `{{Env.postgres_username}}` and `{{Env.postgres_password}}`. ![Enabling Fetch credentials dynamically for Postgres](https://mintcdn.com/superblocks/ohww6-Z99ndA0n1k/images/on-premise-agent/storing-environment-variables/env_vars.png?fit=max\&auto=format\&n=ohww6-Z99ndA0n1k\&q=85\&s=b285232436d02915ee7aa285389b41c0) # Database connection pooling Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/database_connection_pooling When [self-hosting the Superblocks data plane](/enterprise/hybrid-architecture/overview), Superblocks database integrations support connection pooling. That is, when a backend API using a database integration is executed, the agent caches the connection so that subsequent queries can reuse it, instead of establishing a new connection. The default connection pool settings can be adjusted with the following environment variables. ## Connection pool variables | Environment Variable | Description | Default | | - | - | - | | `SUPERBLOCKS_CONNECTION_CACHE_TTL_MS_DEFAULT` | Time connections remain open / idle in the pool (setting this to 0 disables connection pooling) | 60000 ms | | `SUPERBLOCKS_CONNECTION_CACHE_MAX_CONNECTIONS_PER_DATASOURCE` | Max pool size for a given DB integration | 5 | | `SUPERBLOCKS_CONNECTION_CACHE_MAX_CONCURRENT_CONNECTIONS` | Max pool size across all integrations | 1000 | Note, the max connection limits do not prevent more concurrent connections from being created when needed. They are limits on the number of connections kept in the *pool*, but the agent will still serve new requests normally regardless of whether any of these limits have been reached. New requests beyond the max pool limit will create new connections that tear down immediately after completing, versus being kept open in the pool. # Local Redis Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/local_redis The Superblocks data plane includes an embedded Redis service that runs in the container. Redis is used to cache the intermediate step outputs of APIs during execution. This Redis instance is not exposed externally by default and not configured for external network access. Starting in data plane `v1.29.1`, the password for the local Redis user is set to a default value. We recommend setting this to a new value using the `SUPERBLOCKS_AGENT_REDIS_PASSWORD` environment variable (see [Additional configuration](/enterprise/hybrid-architecture/extend/additional-configuration) for deployment-specific settings). Otherwise, you generally do not need to configure any Redis settings, as it is an internal implementation detail of the data plane. # Monitoring the data plane Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/monitoring To monitor the health of your self-hosted Superblocks data plane, go to the [data plane page](https://app.superblocks.com/opas) in app. This page shows all instances and their current health status. Healthy instances will show up as "Active" while unhealthy ones appear as either "Disconnected" or "Browser Unreachable." Since the data plane is deployed behind a load balancer, the cluster is considered healthy provided at least one replica is "Active". If all of the instances within a cluster are "Disconnected" or show as "Browser Unreachable", Superblocks will not be able to execute API requests for that environment. To troubleshoot disconnected or unreachable instances, see the [Troubleshooting guide](/enterprise/hybrid-architecture/manage/troubleshooting). ![two active instances reporting in Superblocks](https://mintcdn.com/superblocks/0x599EHVvFHaqYo0/images/on-premise-agent/monitoring/opa_monitor_status.png?fit=max\&auto=format\&n=0x599EHVvFHaqYo0\&q=85\&s=49dcfd04befa49c625526911cc0b5f99) # Observability Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/observability Configure telemetry, traces, and metrics for the Superblocks data plane ## Disabling Telemetry By default, the agent sends telemetry (traces, logs, and events) to Superblocks intake endpoints. You can disable this for compliance, air-gapped environments, or local development. ### Disable All Remote Telemetry Set a single environment variable to turn off all outbound telemetry: ```bash theme={null} SUPERBLOCKS_ORCHESTRATOR_TELEMETRY_REMOTE_ENABLED=false ``` This disables: * **OTEL traces and logs** (falls back to stdout via `stdouttrace`) * **Remote logs** (emitter to `logs.intake.superblocks.com`) * **Audit logs** (emitter to the Superblocks server, `/api/v2/agents/audit`) * **Events** (emitter to `events.intake.superblocks.com`) * **Cloud events** (inbound gRPC event listener) Local console logging and Prometheus metrics (`/metrics` on port `9090`) remain available. ### Disable Individual Components For finer-grained control, disable specific telemetry components independently: | Environment Variable | Default | Description | | - | - | - | | `SUPERBLOCKS_ORCHESTRATOR_OTEL_COLLECTOR_HTTP_URL` | `https://traces.intake.superblocks.com/v1/traces` | OTLP HTTP endpoint for traces, logs, and metrics. Set to `""` to disable (traces fall back to stdout). | | `SUPERBLOCKS_ORCHESTRATOR_EMITTER_REMOTE_ENABLED` | `true` | Remote log emission to `logs.intake.superblocks.com`. | | `SUPERBLOCKS_ORCHESTRATOR_EMITTER_AUDIT_ENABLED` | `true` | Audit log emission. | | `SUPERBLOCKS_ORCHESTRATOR_EMITTER_EVENT_ENABLED` | `true` | Event emission. | | `SUPERBLOCKS_ORCHESTRATOR_EVENTS_CLOUD_ENABLED` | `false` | Cloud event listener (gRPC). | Example — disable only OTEL traces while keeping logs and events: ```bash theme={null} SUPERBLOCKS_ORCHESTRATOR_OTEL_COLLECTOR_HTTP_URL="" ``` ### Redirecting Telemetry To send telemetry to your own collector instead of Superblocks, point the OTLP URL to your endpoint: ```bash theme={null} SUPERBLOCKS_ORCHESTRATOR_OTEL_COLLECTOR_HTTP_URL="https://your-otel-collector:4318/v1/traces" ``` The agent derives the logs endpoint (`/v1/logs`) and metrics endpoint (`/v1/metrics`) from this base URL automatically. ### What Remains Active Even with all remote telemetry disabled: * **Prometheus metrics** are served at `/metrics` on the metrics port (default `9090`). These are pull-based and do not send data externally. * **Local console logs** continue to write to stdout/stderr. *** ## Traces The agent flushes OpenTelemetry traces from four **services** that can be set in DataDog with the `service` label: ``` orchestrator the orchestrator component worker.go the worker executing plugins written in Golang worker.py the worker executing plugins written in Python worker.js the worker executing plugins written in JavaScript ``` Most spans contain the following sets of attributes, which DataDog calls tags, which can aid in filtering while in DataDog: ``` api-id the identifier of the api api-name the name of the api api-type the type of the api organization-name the name of the organization organization-id the identifier of the organization organization-tier the tier of the organization correlation-id the unique id that persists for all logs and spans for an execution profile the profile selected for the execution resource-name the name of the resource the span is observing resource-type the type of the resource the span is observing version the version of the agent ``` Each span has one of the following names, which DataDog calls **resources**, that can also be filtered upon with the `resource_name` label. Here is a non-exhaustive list: ``` execute.api.await the root span name for synchronous api executions execute.api.stream the root span name for asynchronous api executions engine.resolve the complete resolution of a script by the engine execute.block. observes the resolution of a block execute.step. observes the execution of a step block from the orchestrator execute.plugin. observes the execution of a plugin from the workers v8.run observes the execution of a new v8 script v8.context observes the creation of a new v8 context v8.isolate observes the creation of a new v8 isolate esbuild.transform observes the transpilation of bindings prior to execution store.write observes any writes to the underlying agent store (redis, grpc, etc) store.read observes any reads from the underlying agent store (redis, grpc, etc) fetch.api observes the retrieval of the api definition hydrated with configurations fetch.job observes the retrieval of job definitions hydrated with configurations fetch.secrets observes the retrieval of secret values fetch.integration observes the retrieval of an integration configuration fetch.integrations observes the retrieval of an integration configurations fetch.bindings observes the retrieval of bindings values by language plugins ``` # Outbound requests Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/requests Network requests made by the Superblocks data plane for firewall and allowlist configuration This page documents all outbound network requests the Superblocks data plane makes to Superblocks Cloud. Use this as a reference when configuring firewall rules or network allowlists. ## Required Requests The following table lists all the required operational outgoing calls from the agent to Superblocks Cloud. The Superblocks Cloud host is `https://api.superblocks.com`, and most calls to Superblocks Cloud are authenticated with the organization-specific agent key, which is loaded into the agent as the `SUPERBLOCKS_AGENT_KEY` environment variable. Note: This list shows requests made to Superblocks Cloud APIs that are required for proper agent operation. Network requests made by Superblocks users as part of API steps, for example, requests made to an API using the `requests` library in Python steps or requests made by integrations that access public REST APIs, are also outbound calls made by the agent. These outbound calls are made at the discretion of agent operators. | Path | Type | Source | Target | Description | Authentication | | - | - | - | - | - | - | | `/api/v1/agents/register` | `POST` | Agent | Superblocks Cloud | Route called to register an agent with Superblocks Cloud. | Superblocks Agent Key | | `/api/v1/agents` | `DELETE` | Agent | Superblocks Cloud | Route called to deregister an agent from the Superblocks Cloud (called during agent shutdown). | Superblocks Agent Key | | `/api/v1/agents/healthcheck` | `POST` | Agent | Superblocks Cloud | Route called to post health check information to Superblocks Cloud, including diagnostic and execution metrics (default: called on a 30s interval). | Superblocks Agent Key | | `/api/v1/agents/datasource/:id` (DEPRECATED) | `POST` | Agent | Superblocks Cloud | Route called to get OAuth client information needed to perform OAuth Token exchanges. | Superblocks Agent Key + User JWT | | `/api/v1/integrations` | `GET` | Agent | Superblocks Cloud | Route called to fetch integration configurations from the Superblocks Cloud. | Superblocks Agent Key + User JWT | | `/api/v1/agents/user/userToken` | `GET` | Agent | Superblocks Cloud | Route called to get the currently logged in user's OAuth2.0 access token from Superblocks Cloud. This is then sent as an authorization header or query parameter in integration requests. | Superblocks Agent Key + User JWT | | `/api/v1/agents/user/userToken` | `POST` | Agent | Superblocks Cloud | Route called after OAuth token exchanges are completed to cache access tokens generated for the use in Superblocks Cloud. Token caches ensure users do not have to login multiple times for an Integration. | Superblocks Agent Key + User JWT | | `/api/v1/agents/user/userToken` | `DELETE` | Agent | Superblocks Cloud | Route called to delete all of the user's OAuth2.0 access tokens that have been cached for Integrations. Initiated when developers use the `logoutIntegration()` function in frontend JS. | Superblocks Agent Key + User JWT | | `/api/v1/agents/userToken` | `GET` | Agent | Superblocks Cloud | Route called to get a shared OAuth2.0 access token to use in Integration authentication. | Superblocks Agent Key + User JWT + Org API Token | | `/api/v1/agents/userToken` | `POST` | Agent | Superblocks Cloud | Route called after a successful OAuth2.0 token exchange to save shared access token for an Integration. | Superblocks Agent Key + User JWT + Org API Token | | `/api/v1/oauth2/gsheets/refresh` | `POST` | Agent | Superblocks Cloud | Route called to refresh Google Sheet OAuth2.0 access tokens used by the Google Sheets integration. | Superblocks Agent Key + User JWT + Org API Token | | `/api/v2/agents/audit` | `POST` | Agent | Superblocks Cloud | Route called to create audit log records in Superblocks Cloud for API executions. | Superblocks Agent Key | | `/api/v2/agents/pending-jobs` | `POST` | Agent | Superblocks Cloud | Route called to fetch deployed Scheduled Jobs that should be run by the agent based on their configured schedule. | Superblocks Agent Key | | `/api/v3/apis/:apiId` | `GET` | Agent | Superblocks Cloud | Route called to fetch an API definition from Superblocks Cloud. For deployed APIs, definitions are fetched from the Global Edge Network by default, and round trip to the Superblocks Cloud only if unavailable. | Superblocks Agent Key + User JWT + Org API Token | | `/api/v3/apis/signatures` | `PUT` | Agent | Superblocks Cloud | When Agent Signing is enabled, this route is called to update the signature of an API when signatures are updated as a result of a re-signing job. | Superblocks Agent Key | | `/api/v2/applications/signatures` | `PUT` | Agent | Superblocks Cloud | When Agent Signing is enabled, this route is called to update the signature on an Application when signatures are updated as a result of a re-signing job. | Superblocks Agent Key | | `/api/v2/keyrotations/claim-resources` | `POST` | Agent | Superblocks Cloud | When Agent Signing is enabled, this route is called when a re-signing job is in progress to fetch a batch of resources (APIs and Applications) for the agent to re-sign. | Superblocks Agent Key | ## Superblocks Database requests The following calls are made only when [Superblocks Database](/admin/superblocks-on-aws/database) is enabled on the data plane. Like every other call on this page they are outbound from the data plane and authenticated with the organization-specific agent key. None of them carry credentials: the control plane queues work and records outcomes, and the data plane is the only component that calls AWS or connects to a database. See the [security model](/admin/superblocks-on-aws/database-security) for how these fit together. | Path | Type | Source | Target | Description | Authentication | | - | - | - | - | - | - | | `/api/v1/database-lifecycle/dispatch/watch` | `GET` | Agent | Superblocks Cloud | Long-lived server-sent events stream (`text/event-stream`). The control plane sends an empty wake-up hint when a database task is queued for the organization. The agent always polls the claim route every 30 seconds; this stream only lets it notice new work sooner. If this route returns an error or is unavailable, the agent keeps polling and re-probes the stream periodically. An egress proxy must pass the response through unbuffered and allow a long idle connection for hints to arrive promptly; a buffered stream adds latency but does not stop work from being claimed. | Superblocks Agent Key | | `/api/v1/database-lifecycle/dispatches/claim` | `POST` | Agent | Superblocks Cloud | Route called to claim pending database tasks for this data plane. Called after each wake-up hint, on reconnect, and on the polling fallback interval. The response carries the task: operation, target database, desired settings, and the app's SQL migration files. | Superblocks Agent Key | | `/api/v1/database-lifecycle/callbacks/progress` | `POST` | Agent | Superblocks Cloud | Route called while a task runs to report non-terminal progress. | Superblocks Agent Key | | `/api/v1/database-lifecycle/callbacks/terminal` | `POST` | Agent | Superblocks Cloud | Route called once per task to report the outcome: lifecycle state and connection metadata (cluster endpoint, database and role names). The control plane rejects reports that contain credential material. | Superblocks Agent Key | | `/api/v1/database-lifecycle/physical-database-instances` | `GET` | Agent | Superblocks Cloud | Route called to list the Aurora clusters registered for this data plane's pool. | Superblocks Agent Key | | `/api/v1/database-lifecycle/physical-database-instances` | `POST` | Agent | Superblocks Cloud | Route called to register a newly provisioned Aurora cluster, with its endpoint and capacity. | Superblocks Agent Key | | `/api/v1/database-lifecycle/physical-database-instances/:id` | `GET` | Agent | Superblocks Cloud | Route called to fetch one registered Aurora cluster. | Superblocks Agent Key | | `/api/v1/database-lifecycle/physical-database-instances/:id/reserve` | `POST` | Agent | Superblocks Cloud | Route called to reserve capacity on a cluster before creating an app database on it. | Superblocks Agent Key | | `/api/v1/database-lifecycle/physical-database-instances/:id/release` | `POST` | Agent | Superblocks Cloud | Route called to release a reservation if the task fails. | Superblocks Agent Key | ## Optional Requests The following table lists the optional outgoing calls from the agent to Superblocks Cloud, that are used primarily for observability. The Superblocks Cloud host is specific to each call, and all of these calls are authenticated with the organization-specific agent key, which is loaded into the agent as the `SUPERBLOCKS_AGENT_KEY` environment variable. | Host | Type | Source | Target | Description | Authentication | | - | - | - | - | - | - | | `events.intake.superblocks.com` | `POST` | Agent | Superblocks Cloud | Route called to upload execution analytics events. | Superblocks Agent Key | | `logs.intake.superblocks.com` | `POST` | Agent | Superblocks Cloud | Route called to upload batched agent platform logs for the Observability feature. | Superblocks Agent Key | # Scaling and high availability Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/scaling_and_high_availability The agent is designed to vertically and horizontally scale to meet the needs of your Superblocks workloads. See instructions below for the relevant scaling and resource allocation settings depending on your deployment method. Recommended minimum resources
  • *CPU*: 1
  • *Memory*: 4GiB
  • *Replicas*: 1 for initial development & staging instances, 3 for production
## Kubernetes See the `autoscaling` and `resources` sections of the Helm chart `values.yaml` for the default autoscaling and resource settings. Adjust as needed depending on your workload. ```yaml theme={null} autoscaling: enabled: false minReplicas: 1 maxReplicas: 100 targetCPUUtilizationPercentage: 40 targetMemoryUtilizationPercentage: 80 customMetrics: [] # - type: External # external: # metricName: nginx.net.request_per_s # metricSelector: # matchLabels: # kube_container_name: nginx # targetAverageValue: 123 # Please adjust these values as needed depending on your workloads. We recommend allocating # minimally the following to prevent CPU throttling and Out of Memory errors under load. resources: limits: memory: 4Gi requests: cpu: 1 memory: 4Gi ``` ## ECS Fargate #### Instance Size To configure the CPU & memory limits allocated to your ECS instances use the following variables in your Terraform file. ``` container_cpu = 1024 container_memory = 4096 ``` #### Scaling AWS will automatically scale your ECS instances based on traffic. To configure the minimum and maximum number of instances the agent can scale to, set the following variables in your Terraform file. ``` container_min_capacity = 1 container_max_capacity = 10 ``` ## Google Cloud Run #### Instance Size To configure the CPU & memory limits for your Cloud Run instances, use the following variables in your Terraform file. ``` container_requests_cpu = "1" container_requests_memory = "4Gi" container_limits_memory = "4Gi" ``` #### Scaling Google will automatically scale your Cloud Run instances based on traffic. To configure the minimum and maximum number of instances the agent can scale to, set the following variables in your Terraform file. ``` container_min_capacity = "1" container_max_capacity = "5" ``` # Size and time limits Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/size_and_time_limits These are default settings that can be adjusted as needed. Contact Superblocks Support via email or in-app chat for assistance. ## gRPC message size limits The agent implements a gRPC interface with default limits on incoming and outgoing messages. These limits are governed by the following environment variables. | Environment Variable | Description | Default | | - | - | - | | `SUPERBLOCKS_ORCHESTRATOR_GRPC_MSG_REQ_MAX` | The maximum message size in bytes allowed to be received by the agent's gRPC server. | 30000000 (30 MB) | | `SUPERBLOCKS_ORCHESTRATOR_GRPC_MSG_RES_MAX` | The maximum message size in bytes allowed to be sent by the agent's gRPC server. | 100000000 (100 MB) | API steps that exceed these limits will return the following errors. ``` grpc: received message larger than max ( vs. ) ``` ``` grpc: sent message larger than max ( vs. ) ``` To adjust these limits for handling larger messages, edit the environment variables directly or use the deployment specific methods below. > [tab] Terraform > > Update your `main.tf` with the following variables set to the desired limits. > > ``` > superblocks_grpc_msg_req_max = "" > superblocks_grpc_msg_res_max = "" > ``` > [tab] Helm > > Update your Helm chart with the following variables set to the desired limits. > > ```yaml theme={null} > grpc: > maxRecvMsgSize: > maxMsgSize: > ``` ## Node.js process memory limits One of the main processes running in the agent is a Node.js worker responsible for executing API steps for integrations and custom backend JavaScript. As such, the [limits that exist in the Node.js V8 engine](https://blog.appsignal.com/2021/12/08/nodejs-memory-limits-what-you-should-know.html) also apply to the agent. One such limit is the [max memory size of V8's old memory section](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-mib). When this limit is hit, the agent logs show the following error. ``` FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory ``` To remedy this, you can increase the heap size in the agent's Node.js worker by adding an environment variable called `NODE_OPTIONS` with a value of `--max-old-space-size=`. Configure this environment variable directly or use the deployment specific settings below. > [tab] Terraform > > Add the environment variable with the `superblocks_agent_environment_variables` array in your `main.tf`. > > ``` > superblocks_agent_environment_variables = [{name = "NODE_OPTIONS", value = "--max-old-space-size="}] > ``` > [tab] Helm > > Add the environment variable to your Helm chart with the `extraEnv` config. > > ```yaml theme={null} > extraEnv: > NODE_OPTIONS: --max-old-space-size= > ``` > [tab] Docker Compose > > The agent's Docker Compose file already sets the heap size limit to 3000 MiB by default. To modify this, set `SUPERBLOCKS_AGENT_MEMORY_LIMIT` to the desired limit. > > ``` > export SUPERBLOCKS_AGENT_MEMORY_LIMIT="" > ``` ## REST API response size limit When using the REST API integration, the size of the http response cannot exceed 50,000,000 bytes (50 MB) by default. This can be configured with the `SUPERBLOCKS_WORKER_EXECUTION_REST_API_MAX_CONTENT_LENGTH_BYTES` environment variable. To increase this max size, edit the environment variable directly or use the deployment specific methods below. > [tab] Terraform > > Add the environment variable with the `superblocks_agent_environment_variables` array in your `main.tf`. > > ``` > superblocks_agent_environment_variables = [{name = "SUPERBLOCKS_WORKER_EXECUTION_REST_API_MAX_CONTENT_LENGTH_BYTES", value = ""}] > ``` > [tab] Helm > > Add the environment variable to your Helm chart with the `extraEnv` config. > > ```yaml theme={null} > extraEnv: > SUPERBLOCKS_WORKER_EXECUTION_REST_API_MAX_CONTENT_LENGTH_BYTES: > ``` ## API timeout limit APIs have a default max duration of 600,000 ms (10 minutes). This can be configured with the`SUPERBLOCKS_ORCHESTRATOR_QUOTAS_DEFAULT_API_TIMEOUT` environment variable in ms. To increase this max duration, edit the environment variable directly or use the deployment specific methods below. > [tab] Terraform > > Update your `main.tf` with the following variables set to the desired limits. > > ``` > superblocks_agent_quotas_default_api_timeout = "" > ``` > [tab] Helm > > Add the environment variable to your Helm chart with the `extraEnv` config. > > ```yaml theme={null} > extraEnv: > SUPERBLOCKS_ORCHESTRATOR_QUOTAS_DEFAULT_API_TIMEOUT: > ``` # Troubleshooting the data plane Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/troubleshooting After the data plane has been successfully deployed, check the status [in app](https://app.superblocks.com/opas). If the status is not "Active", then there may be an issue with the data plane's connection to your browser, to the Superblocks Cloud, or both. For non "Active" statuses, see the troubleshooting techniques detailed below. ![data plane showing Browser Unreachable status](https://mintcdn.com/superblocks/ohww6-Z99ndA0n1k/images/on-premise-agent/troubleshooting/opa_errors.png?fit=max\&auto=format\&n=ohww6-Z99ndA0n1k\&q=85\&s=8aca00876002c985fcdb1a1439e5a109) ## Browser Unreachable The Browser Unreachable status can indicate a number of problems with your data plane configuration, but generally means there is a network issue between your browser and the Superblocks data plane. While the data plane can connect to Superblocks Cloud, your browser cannot connect to this data plane. Some quick points to check: * For non-localhost deployments, confirm that the data plane host URL is correct and exposed via HTTPS. * If a VPN is required to access the data plane, check that you're connected to the VPN on your device. * Check the ingress and firewall configuration on your data plane deployment. * If using the [Brave browser](https://brave.com/), turn off the [Shields](https://brave.com/shields/#:~:text=Brave%20Shields%20block%20the%20stuff,Phishing.) for the Superblocks site. To debug this issue in more detail, open the **Developer Settings** for your browser and navigate to the **Network** tab. Locate failed requests made to the following endpoints, based on your data plane version: > [tab] v1.x.x > >
    >
  • `GET https:///health`
  • >
  • `POST https:///v2/execute/stream`
  • >
> [tab] v0.x.x > >
    >
  • `GET https:///agent`
  • >
  • `POST https:///agent/v1/apis/execute`
  • >
Find the error code and message returned. Common network issues and errors include: | Status | Description | | - | - | | `ENOTFOUND` | DNS lookup failed. Check that the domain you're using for your data plane is registered and you've configured a CNAME or ANAME record for any subdomains added to your data plane host url. If the domain is registered, double check that there aren't any spelling errors in the data plane host url configured for your data plane. | | `ECONNREFUSED` | Indicates that network rules are blocking your browser from accessing the data plane. If your data plane is deployed in a private network, check that you're logged into your VPN. If you are logged into your VPN and still seeing this error, have your data plane operator check that the ingress rules for your data plane's load balancer or subnets associated with the data plane are configured to allow traffic from users within your private network. | | `ECONNRESET` | Indicates that the data plane died while trying to serve a request. If you have auto-scaling configured for your data plane, this should be self-healing. If your organization is only running a single data plane replica, restart the data plane. For high-availability we recommend running at least 3 data plane replicas. Read more about [Scaling and High-Availability Deployments](/enterprise/hybrid-architecture/manage/scaling_and_high_availability). | | `400` | This status code indicates that the data plane is running, but is still starting up. Wait a few minutes and try again. If the data plane takes a very long time to start, it may not have enough memory allocated. Increase memory allocated and restart. Read more about [minimum provisioning requirements](/enterprise/hybrid-architecture/manage/scaling_and_high_availability) for the data plane. | | `408` | Requests to the data plane are timing out. This can happen when the data plane is under-provisioned. Check service health metrics provided by your cloud provider to determine if additional memory or CPU are needed. | | `500` | This status returned by the `/agent` or `/health` endpoint usually indicates the data plane is restarting. Wait a few seconds and refresh the browser. If this status is returned by the `/agent/v1/apis/execute` or `/agent/v2/execute/stream` endpoint, this can indicate your data plane is having problems communicating with the Superblocks server. View the logs for your data plane to see if errors are being returned when calling [https://app.superblocks.com](https://app.superblocks.com). Check the [Superblocks Status page](https://status.superblocks.com/) to see if Superblocks is having an incident. If the status page indicates all Superblocks services are operational and the data plane logs are showing an `ECONNREFUSED` error response, check the egress rules for your network to make sure they allow for outbound network calls. | | [CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#cors_error_messages) | See [Troubleshooting CORS issues](#troubleshooting-cors-issues) section below. | | Certificate errors | Make sure the certificate issued for your data plane domain hasn't expired. It is recommended to automate the renewal process if possible. Some examples include [AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/managed-renewal.html), [Traefik with LetsEncrypt](https://docs.aws.amazon.com/acm/latest/userguide/managed-renewal.html) (used in [VM deployment](/enterprise/hybrid-architecture/deployment/virtual_machine)) and [Kubernetes cert-manager](https://cert-manager.io/docs/usage/certificate/#renewal). | ### Troubleshooting CORS issues The data plane (OPA) handles CORS natively when `handleCors=true` (the default setting). If you are using a proxy or service mesh that also manages CORS headers, it may override the OPA's CORS handling. The recommended approach is to either let the OPA handle CORS directly, or ensure your proxy configuration includes all required origins listed below. Some infrastructure layers (e.g., AWS ALB listener header modification rules) only support static origin strings and cannot perform wildcard subdomain matching. If you are using such a layer for CORS, you should either remove the CORS configuration from that layer and let the OPA handle it, or move CORS handling to a layer that supports wildcard/dynamic origin evaluation (such as Istio, nginx, or Envoy). If you are using a proxy or service mesh in your data plane deployment, check if it's populating the following CORS headers properly: * [Access-Control-Allow-Credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials) * [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) * [Access-Control-Allow-Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods) * [Access-Control-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) Example values to add to proxy or service mesh config: ```yaml theme={null} corsPolicy: allowCredentials: true allowMethods: - GET - HEAD - PUT - PATCH - POST - DELETE allowOrigins: # Main Superblocks application domains (US) - exact: https://app.superblocks.com - exact: https://app.superblockshq.com # Main Superblocks application domain (EU) - exact: https://eu.superblocks.com # Code-mode (live edit) runs from dynamic subdomains - prefix: https://*.edit.superblocks.com - prefix: https://*.edit.eu.superblocks.com # Deployed apps run from dynamic subdomains - prefix: https://*.deployed-apps.superblocks.com allowHeaders: - x-superblocks-request-id - authorization - content-type ``` The wildcard subdomain patterns above (`*.edit.superblocks.com`, `*.edit.eu.superblocks.com`, and `*.deployed-apps.superblocks.com`) are required for code-mode editing and deployed app execution. Without these, applications in code-mode will fail to connect to the data plane, and deployed apps will not be able to execute APIs through the data plane. ## Disconnected This status means the data plane cannot connect to Superblocks Cloud. Click the status [in app](https://app.superblocks.com/opas) to see more details. If the modal shows that your *browser can* connect to this data plane, then check the egress and firewall configuration on your data plane deployment to see if something is preventing it from reaching out to Superblocks. If the modal shows that your *browser cannot* connect to this data plane, then start by making sure your data plane service is running and healthy. For example, `kubectl get pods -n superblocks` to check if the data plane pods are running in Kubernetes, or `docker ps | grep superblocks` for a Docker deployment. Further inspect the logs/events for these services if they are not healthy. ## data plane not appearing on data planepage This occurs due to similar issues as the Disconnected error. The data plane is unable to reach the Superblocks control plane or edge cache to register itself. This error can also be caused by the data plane being in an unhealthy state as well. The best way to troubleshoot this issue is to verify that the network does not impede the data plane and that the data plane is healthy. Run `nc -v -w 1 api.superblocks.com 443` from your data plane environment and run `curl -s -L data plane.superblocks.com/health | jq` from your local environment. 1. Check Superblocks can reach control plane or edge cache(run this on the data plane environment): ![Check Superblocks can reach control plane or edge cache](https://mintcdn.com/superblocks/ohww6-Z99ndA0n1k/images/on-premise-agent/troubleshooting/test_control_plane_and_cache.png?fit=max\&auto=format\&n=ohww6-Z99ndA0n1k\&q=85\&s=7c5c27d9606ca8d3972f5b92269fe2b7) If this is occurring, make sure there is a point of egress from the data plane to Superblocks Cloud. 1. Check data plane is healthy(run this locally): ![Check data plane is healthy](https://mintcdn.com/superblocks/ohww6-Z99ndA0n1k/images/on-premise-agent/troubleshooting/test_health_endpoint.png?fit=max\&auto=format\&n=ohww6-Z99ndA0n1k\&q=85\&s=86f9fb196cde79dc34e392df2be56c83) If this is occurring, make sure that there is a point of ingress from your client machines to the On Premise data plane. ## Queries timing out If a connection times out from something upstream (for instance, an ELB) you may receive an error that says `"Failed to connect"`. To fix this, ensure that the timeout set on the ELB is large enough to accommodate the queries that your applications are making. [Contact us](/enterprise/support/help) if you have any questions or need help troubleshooting the data plane. # Upgrading the data plane Source: https://docs.superblocks.com/enterprise/hybrid-architecture/manage/upgrade Superblocks periodically releases new versions of the data plane with bug fixes, performance improvements, and new features. We recommend keeping your data plane up to date to ensure compatibility with the latest Superblocks platform capabilities. See the [changelog](https://charts.superblocks.com/agent/CHANGELOG.md) for details on each release. ## Release notifications To be notified when new data plane versions are published, you can watch the [Superblocks agent repository on Docker Hub](https://hub.docker.com/r/superblocksteam/agent/tags). Available tagged versions are listed there and can be used when specifying the image version in your deployment configuration. ## Upgrade instructions Follow the instructions below to upgrade the data plane based on your deployment method. > [tab] Terraform > > Bump the version tag on the `superblocks_agent_image` variable in the service's Terraform file. > > **AWS ECS Fargate** > > ``` > superblocks_agent_image = "ghcr.io/superblocksteam/agent:" > ``` > > **Google Cloud Run** > > ``` > superblocks_agent_image = "gcr.io/superblocks-registry/superblocks/agent:" > ``` > [tab] Helm > > Fetch the latest chart. > > ``` > helm repo update > ``` > > Redeploy the chart. > > ``` > helm upgrade -i -n superblocks superblocks-agent superblocks/superblocks-agent \ > --create-namespace \ > -f values.yaml \ > --set superblocks.agentKey="" \ > ``` > [tab] Docker > > Download the latest [Docker Compose file](https://charts.superblocks.com/agent/compose.yaml) and redeploy. To specify a version, set `SUPERBLOCKS_DOCKER_AGENT_TAG`. Otherwise the `latest` version is used by default. > > ``` > curl -s https://charts.superblocks.com/agent/compose.yaml | \ > SUPERBLOCKS_AGENT_KEY="" \ > SUPERBLOCKS_AGENT_HOST_URL="" \ > SUPERBLOCKS_DOCKER_AGENT_TAG="" \ > docker compose -p superblocks -f - up > ``` # Superblocks Hybrid Source: https://docs.superblocks.com/enterprise/hybrid-architecture/overview Keep data in your network, while getting the latest features from Superblocks Cloud Superblocks Hybrid is designed for organizations that require production data and application execution to remain entirely within their AWS, GCP, or Azure environment, while offloading platform management and control plane operations to the Superblocks cloud. With Superblocks Hybrid, the Superblocks control plane and AI inference for development are hosted and managed in the Superblocks cloud, while the data plane is deployed inside your cloud provider VPC, directly colocated with your private production data. All production code executes locally within the customer network, ensuring production data never leaves customer-controlled boundaries. This model gives customers strong guarantees around production data residency, network isolation, and execution locality, while Superblocks manages the platform lifecycle—including upgrades, reliability, and operational support. The result is enterprise-grade security and control without the operational burden, slow iteration cycles, or complexity of a fully self-hosted deployment. ## Hybrid architecture - Edit mode ![](https://mintcdn.com/superblocks/9gY8R6Ph9jAsQ-Bn/images/enterprise-deployment/hybrid.png?fit=max\&auto=format\&n=9gY8R6Ph9jAsQ-Bn\&q=85\&s=75ce3ea7b557ffad015f9b29b42dca96) In the Hybrid deployment, the Superblocks control plane runs and AI inference runs the Superblocks cloud during development, while a dedicated Superblocks data plane runs inside a single customer-managed VPC in AWS, GCP, or Azure, colocated with your data. All application APIs execute locally within the customer VPC, accessing private APIs and data sources without leaving customer-controlled network boundaries and without opening up network firewall ports. The control plane remains out of the production execution path, providing configuration, orchestration, metadata, and governance from the Superblocks cloud. ## Hybrid architecture - Deployed mode ![](https://mintcdn.com/superblocks/AmKWe0YbRbizsd5G/images/enterprise-deployment/hybrid-deployed.png?fit=max\&auto=format\&n=AmKWe0YbRbizsd5G\&q=85\&s=1179998e8258982325d4cb92fa6bd66a) When apps are deployed and a user loads the application URL, the browser makes a call to the Superblocks cloud to route authentication to your SSO provider, checks user permissions and then loads in the frontend from the nearest global cache. When APIs execute the browser calls the data plane inside your VPC so production data never leaves your private network in AWS, GCP or Azure. ## How it works In the Superblocks Hybrid deployment model: * Cloud-hosted control plane and AI: The Superblocks control plane—and AI inference for development and non-production workflows—run in the Superblocks cloud and are fully managed by Superblocks. * Private, single-tenant data plane: A dedicated Superblocks data plane is deployed inside your AWS, GCP, or Azure VPC and executes all production application APIs locally. * Production data stays in your network: Deployed applications connect directly to the data plane for secure, low-latency access to private APIs, databases, and internal services, with production data never leaving the customer VPC. * Outbound-only connectivity: The data plane communicates outbound-only to the control plane, requiring no inbound network access or exposed firewall ports. * Enterprise identity and managed operations: Access is governed by your enterprise SSO and centralized Superblocks RBAC, while Superblocks operates and supports the platform end-to-end, including upgrades, reliability, and ongoing support. This model ensures that all production application execution and data access occur entirely within your network, while Superblocks manages the control plane, AI capabilities, and platform operations—without requiring you to run or maintain the full system yourself. ## Why choose Hybrid Superblocks Hybrid is best for enterprises that require private network execution and data locality, but want to avoid the operational overhead and cost a cloud-prem: * **Private, high-performance production execution:** All production application APIs, workflows, and data access execute locally inside your AWS, GCP, or Azure VPC—behind existing network controls—delivering low-latency, predictable performance with production data never leaving customer-managed boundaries. * **No inbound network exposure:** The data plane communicates outbound-only to Superblocks’ cloud, eliminating the need to open firewall ports or allow inbound connections into your VPC. * **Cloud-hosted AI for development speed:** AI inference for edit mode, previews, and non-production data runs in the Superblocks cloud, enabling fast iteration and AI-assisted development without exposing production data. * **Centralized governance without overhead:** Control plane services—including configuration, orchestration, RBAC, and audit logs—are managed centrally by Superblocks, providing enterprise-grade governance without operating control plane infrastructure. ## Next steps The diagrams above show a single data plane. Most Hybrid customers run two, one per data tag. > [card] [1. Plan](/enterprise/hybrid-architecture/plan/index) > > Data planes, data tags, and environments. > [card] [2. Deploy](/enterprise/hybrid-architecture/deployment/index) > > AWS, GCP, Azure, Kubernetes, or a VM. > [card] [3. Manage](/enterprise/hybrid-architecture/manage/monitoring) > > Monitor, scale, and upgrade. # Reference architectures Source: https://docs.superblocks.com/enterprise/hybrid-architecture/plan/architectures Recommended AWS layout for Superblocks data planes, plus the less common layouts that justify more planes or tags Examples use AWS because it is the most common target and the only one that supports [Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database), but the same shapes apply on GCP and Azure, and all of them assume you have read [Plan your data planes](/enterprise/hybrid-architecture/plan/index). ## Recommended: two AWS accounts, two data planes Most organizations already separate pre-production and production into different AWS accounts. Put one data plane in each, and give each one exactly one data tag. ```mermaid theme={null} flowchart LR EndUser["End users
deployed apps"] Builder["Builders
Edit and Preview"] subgraph prodAccount [AWS account: production VPC] ProdPlane["Production data plane
profile:production"] ProdDb[("Production database")] end subgraph devAccount [AWS account: pre-production VPC] DevPlane["Development data plane
profile:dev"] StagingDb[("Staging database")] end EndUser -->|"production tag"| ProdPlane --> ProdDb Builder -->|"dev tag"| DevPlane --> StagingDb ``` Why this is the default recommendation: * **Tag routing and the account boundary work together.** Superblocks sends a request to the data plane that serves its data tag, so Edit and Preview traffic on `dev` only ever runs on the development data plane. Because that data plane lives in the pre-production account, anything reachable only from inside the production VPC, such as the production database above, is out of reach from Edit even if an integration is misconfigured. IAM, networking, and billing are already separated, so you write no extra policy to get this. * **Two data tags are the minimum that gives you separation**, and few enough that builders rarely pick the wrong one. The built-in **Development** (`dev`) and **Production** (`production`) tags already exist for this. * **Clark stays on the development side.** Clark only runs in Edit, so with Edit on the `dev` tag it never routes through the production account or VPC. See [Clark and data access](/building-with-clark/data-access). This boundary covers data that only the production network can reach. A third-party configuration linked to both tags, such as a Salesforce or Jira tenant with no sandbox, is the same live system from either data plane; see [Sharing a third-party configuration between dev and production](/enterprise/hybrid-architecture/plan/index#sharing-a-third-party-configuration-between-dev-and-production) for how to scope what Edit can do to it. To build it, deploy each data plane with [ECS Fargate](/enterprise/hybrid-architecture/deployment/aws_ecs_fargate) or [Kubernetes](/enterprise/hybrid-architecture/deployment/kubernetes) and set its agent tags as described in [Set agent tags](/enterprise/hybrid-architecture/deployment/multiple_environments). ## Less common layouts Each layout below adds a data plane, a data tag, or both. See [Data planes and Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database) if you plan to enable databases. ### Single AWS account Some organizations run everything in one AWS account. Keep the two data planes and two data tags, and put each data plane in its own VPC, or at least its own subnets and security groups. ```mermaid theme={null} flowchart LR EndUser["End users
deployed apps"] Builder["Builders
Edit and Preview"] subgraph account [AWS account] subgraph prodVpc [VPC: production] ProdPlane["Production data plane
profile:production"] ProdDb[("Production database")] end subgraph devVpc [VPC: pre-production] DevPlane["Development data plane
profile:dev"] StagingDb[("Staging database")] end end EndUser -->|"production tag"| ProdPlane --> ProdDb Builder -->|"dev tag"| DevPlane --> StagingDb ``` Implications: * Separation now depends on security groups and IAM policies you write, not on an account boundary. * Both data planes share IAM role and resource namespaces, so each needs a distinct agent name. ### Production with a VPC-only tag and a non-VPC tag Some organizations have two kinds of production apps: a few that need private data inside the VPC, and many that only use SaaS tools or public APIs. Rather than give every production request a path into the private network, they run two production data planes with two production data tags. The second data plane runs in its own VPC with no peering, transit gateway attachment, or route to the VPC that holds private data; it still sits in private subnets and reaches SaaS and the control plane through NAT egress, like any other data plane. ```mermaid theme={null} flowchart LR AppA["Apps that need private data
production-vpc tag"] AppB["Apps that only use SaaS
production tag"] subgraph prodAccount [AWS account: production] subgraph privateVpc [VPC with private data] VpcPlane["Production data plane
profile:production-vpc"] ProdDb[("Production database")] end subgraph saasVpc [Separate VPC, not peered] SaasPlane["Production data plane
profile:production"] end end AppA --> VpcPlane --> ProdDb AppB --> SaasPlane ``` Implications: * Production has two data tags, so every app must choose the right one for its Production environment. * The private data plane's access footprint is smaller: only apps tagged `production-vpc` can reach it. * The separation is only as good as the network boundary. Two VPCs with no peering or shared routes give it to you by default; if both data planes must share one VPC, security groups and network ACLs have to deny the SaaS-only data plane every path to the private data, and you own keeping that rule set correct. The same shape applies when a single data source lives in a locked-down network segment: run a dedicated data plane inside that segment with its own tag, and only the apps that need that source use it. #### With Superblocks Database [Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database) creates one database per app per data tag, so an app whose Production environment allows both `production-vpc` and `production` would get two production databases, one in each data plane's pool. Superblocks recommends a third production tag for the apps that serve both an internal and a public audience. The SaaS-only data plane serves it alongside `production`, with agent tags `profile:production,profile:production-shared`: | Data tag | Served by | Apps | | - | - | - | | `production-vpc` | Data plane in the VPC with private data | Internal apps that need private data | | `production` | SaaS-only data plane | Apps that only use SaaS tools or public APIs | | `production-shared` | SaaS-only data plane | Apps used both internally and publicly | Each app then has exactly one production tag and one production database. The app's developer picks that tag before publishing for the first time, because the first publish creates the production database under that tag and [data tag keys are permanent once databases exist](/enterprise/hybrid-architecture/plan/superblocks-database#one-database-enabled-data-plane-per-data-tag). ### Multi-region When users or data live in more than one region, run a data plane in each region and give each region its own data tag. Apps allow several tags in Production, and end users switch regions by switching tags. ```mermaid theme={null} flowchart TB subgraph useast [AWS us-east-1] EastPlane["Data plane
profile:us-east"] EastDb[("Regional database")] end subgraph euwest [AWS eu-west-1] WestPlane["Data plane
profile:eu-west"] WestDb[("Regional database")] end Users["End users"] Users -->|"us-east tag"| EastPlane --> EastDb Users -->|"eu-west tag"| WestPlane --> WestDb ``` Implications: * You still need a pre-production data plane and tag; regional tags are usually production-only. That makes at least three data planes. * Every integration with regional instances needs a configuration per region. ### IAM-based access patterns When the data plane runs in AWS, its IAM role is the identity that AWS integrations authenticate with; see [AWS IAM](/integrations/auth/aws-iam). If different groups of apps need different AWS permissions, you can run separate data planes, each with its own IAM role and data tag, instead of granting one data plane the union of every permission. Implications: * Every app must run with the tag whose data plane holds the permissions it needs; a mismatch fails at execution time, not at build time. # Plan your data planes Source: https://docs.superblocks.com/enterprise/hybrid-architecture/plan/index Decide how many data planes to run and which data tags each one serves before you deploy Most Hybrid customers run **two data planes**: one serving the `dev` data tag for Edit and Preview, one serving `production` for Production. Decide whether that fits you before you deploy anything. Data plane, On-Premise Agent, OPA, and agent are the same thing
  • **Data plane** is the name used in these docs.
  • **On-Premise Agent** or **OPA** is the original name. The admin page that lists your data planes is still [app.superblocks.com/opas](https://app.superblocks.com/opas).
  • **Agent** is the name in configuration: `superblocks_agent_tags` in Terraform, `superblocks.agentTags` in Helm, `SUPERBLOCKS_AGENT_TAGS` in Docker.
**Data tags** were previously called **profiles**, and the agent tag format still uses the `profile:` prefix: `profile:production` serves the data tag whose key is `production`. ## Environments and data tags Every Superblocks application moves through three built-in environments: | Environment | What happens there | | - | - | | **Edit** | Developers and Clark build and test the app | | **Preview** | Changes are reviewed before going live | | **Production** | The published app runs | Environments are fixed. Data tags control which data each one can reach. A **data tag** names a segment of your data; admins create tags on the [Environments](https://app.superblocks.com/environments) page and choose which environments each tag is allowed in. Your account starts with **Development** (key `dev`) and **Production** (key `production`). A data tag is attached to two things: 1. **Integration configurations.** Each integration can have several configurations (different hosts, credentials, or databases), each linked to one or more data tags. 2. **Data planes.** Each data plane advertises the data tags it serves through its agent tags setting. When an app runs an API, its environment determines the active data tag. That tag selects both the integration configuration that supplies the credentials and the data plane that executes the code. ```mermaid theme={null} flowchart LR Edit --> DevTag["Data tag: dev"] Preview --> DevTag Production --> ProdTag["Data tag: production"] DevTag --> DevPlane["Development data plane
profile:dev"] ProdTag --> ProdPlane["Production data plane
profile:production"] ``` ## How data planes match data tags The agent tags setting is a comma-separated list of `profile:` entries: * `profile:production` serves one data tag. * `profile:dev,profile:staging` serves two. * `profile:*` serves every data tag. It is the default and fine for a first test deployment, but it gives you none of the separation described below and stops working when you enable Superblocks Database. Two rules follow: * **Every data tag you use must be served by a data plane.** Hybrid requests never fall back to Superblocks Cloud. If no active data plane serves the active tag, the API fails with `Unable to connect to on-premise agent(s)`. * **Replicas are not separate data planes.** Three instances behind one load balancer are one data plane with one set of agent tags; that is how you [scale](/enterprise/hybrid-architecture/manage/scaling_and_high_availability). Add a data plane only when you need a different network, account, or set of data tags. ## The recommended setup | Data plane | Agent tags | Serves environments | Runs in | | - | - | - | - | | Development | `profile:dev` | Edit, Preview | Your pre-production AWS account and VPC | | Production | `profile:production` | Production | Your production AWS account and VPC | This puts a hard boundary between the data builders and Clark touch while building and the data your published apps touch. For each integration, then decide: * **The data source has a pre-production instance** (a staging database, a sandbox tenant of an internal API): create one configuration for `dev` that points at it and one for `production`. * **The data source has no pre-production instance** (most SaaS tools, data warehouses): one configuration linked to both tags is enough. ### Sharing a third-party configuration between dev and production Integration configurations are stored in the control plane, not on a data plane, so a configuration linked to both `dev` and `production` is delivered to whichever data plane runs the request. Both data planes reach Salesforce, Jira, or any other SaaS over outbound HTTPS; nothing crosses the account boundary. A shared configuration is the deliberate exception to "test data never reaches production," so the decision is what builders and Clark can do to that system from Edit and Preview. Three options, from simplest to most isolated: | Option | When to use it | | - | - | | One configuration, both tags | Read-mostly integrations, or when the SaaS has no sandbox and you accept that Edit sees live data | | Two configurations, same instance, scoped user for `dev` | Same tenant, but the `dev` configuration authenticates as a read-only or limited user so building cannot create real tickets or records | | Two configurations, separate instances | The vendor offers a sandbox (Salesforce Sandbox, Jira test site); point `dev` at it | The data plane split is the same in every case. Only the credentials attached to each tag differ. ## Next steps > [card] [Reference architectures](/enterprise/hybrid-architecture/plan/architectures) > > The recommended two-account AWS layout, and when to add more data planes or tags. > [card] [Superblocks Database](/enterprise/hybrid-architecture/plan/superblocks-database) > > How data planes and data tags decide where each app's database lives. > [card] [Deploy a data plane](/enterprise/hybrid-architecture/deployment/index) > > Prerequisites and deployment methods for AWS, GCP, Azure, and Kubernetes. # Data planes and Superblocks Database Source: https://docs.superblocks.com/enterprise/hybrid-architecture/plan/superblocks-database How data planes and data tags decide where each application's Aurora PostgreSQL database is created [Superblocks Database](/admin/superblocks-on-aws/database) gives every app its own Aurora PostgreSQL database inside your AWS account. The data plane provisions and connects to those databases, and the data tag decides which data plane, and therefore which database, an app talks to. The setup procedure is in [Set up Superblocks Database](/admin/superblocks-on-aws/database-setup); this page covers the decisions that come before it. ## Database work is routed by exact data tag Ordinary API execution accepts a data plane whose agent tags are `profile:*`. Database work does not: a data plane with Superblocks Database enabled must list exact tags, such as `profile:dev`, and the data plane, Terraform module, and Helm chart all reject the wildcard. If your data planes run with `profile:*` today, decide your tags and switch to them before you enable databases. ## One database per app, per data tag Superblocks creates one logical database for each combination of application and data tag, inside the Aurora pool owned by the data plane that serves that tag. ```mermaid theme={null} flowchart TB App["Application"] subgraph prodAccount [AWS account: production] ProdPlane["Production data plane
profile:production"] ProdPool[("Aurora pool
always on")] ProdDb["App database
production"] end subgraph devAccount [AWS account: pre-production] DevPlane["Development data plane
profile:dev"] DevPool[("Aurora pool
always on")] DevDb["App database
dev"] end App -->|"Production
production tag"| ProdPlane App -->|"Edit and Preview
dev tag"| DevPlane ProdPlane --> ProdPool ProdPool --- ProdDb DevPlane --> DevPool DevPool --- DevDb ``` With the recommended two-data-plane setup, an app built in Edit gets its development database from the development data plane. Publishing creates its production database through the production data plane and applies the same migrations there; see [How it works](/admin/superblocks-on-aws/database#how-it-works). Use the same always-on capacity for both pools, including development. Setting `min_acu` to `0` on a development cluster is not recommended: an idle cluster pauses, which costs less but adds a cold start the next time an editor connects; see [Cluster autoscaling](/admin/superblocks-on-aws/database-reference#cluster-autoscaling). ## One database-enabled data plane per data tag Superblocks recommends a separate data plane for each data tag you enable databases for, each in its own VPC and ideally its own AWS account. The recommended two-account layout already satisfies this. If you run one of the [less common layouts](/enterprise/hybrid-architecture/plan/architectures#less-common-layouts), check it against these rules: * **A data plane can serve databases for more than one tag**, but every tag it serves shares that data plane's pool, capacity shape, and IAM role. Keep tags with different requirements (dev vs production, or different regions) on different data planes. * **Each data tag should be served by exactly one database-enabled data plane.** Replicas of that data plane are fine, because they share one configuration. A second, independently configured data plane serving the same tag makes routing ambiguous. * **Two data planes in one account and region** must be declared together with distinct agent names so they share a state bucket without colliding. See [Multiple data planes in one account and region](/admin/superblocks-on-aws/database-reference#multiple-data-planes-in-one-account-and-region). * **Each region needs its own tag** and its own prerequisite stack. An app's database in `us-east` and its database in `eu-west` are different databases. See [Additional AWS regions](/admin/superblocks-on-aws/database-reference#additional-aws-regions). Data tag keys are permanent once databases exist Database and role names are derived from a hash of the data tag, and the connector role's permissions are scoped to that pattern. Renaming a data tag orphans every database and role created under the old name. See [Data tag names](/admin/superblocks-on-aws/database-reference#data-tag-names). ## Why keep it simple Every layout in [Reference architectures](/enterprise/hybrid-architecture/plan/architectures) works with Superblocks Database, but each extra data tag means another database per app, and each extra database-enabled data plane means another Aurora pool with its own cost floor, capacity settings, IAM roles, and state to protect. One data tag and data plane for Edit and Preview, and one for Production, give builders a development database and a production database per app with no further decisions to make. Add more only when one of the less common layouts describes a requirement you have, and involve your Superblocks account manager before you enable databases on it. ## Next steps > [card] [Set up Superblocks Database](/admin/superblocks-on-aws/database-setup) > > The Terraform and Helm walkthrough, one data plane at a time. > [card] [Superblocks Database reference](/admin/superblocks-on-aws/database-reference) > > Naming, IAM policies, pool and autoscaling options, and multi-region setup. # Instance URLs Source: https://docs.superblocks.com/enterprise/instance-urls Your organization uses one Superblocks instance: Cloud US, Cloud EU, or your own Cloud-Prem instance. Each instance has its own URL. When a setup guide shows a URL like `https://{tenant}.superblocks.com/logout`, replace `{tenant}` with the value for your instance. | Instance | `{tenant}` | Your Superblocks URL | | - | - | - | | Cloud US | `app` | `https://app.superblocks.com` | | Cloud EU | `eu` | `https://eu.superblocks.com` | | [Cloud-Prem](/enterprise/cloud-prem/aws) | Your tenant name | `https://{tenant}.superblocks.com` | To find your instance, check the address in your browser when you're signed in to Superblocks. For example, the SCIM base URL `https://{tenant}.superblocks.com/scim/v2` becomes `https://eu.superblocks.com/scim/v2` on Cloud EU. [Hybrid](/enterprise/hybrid-architecture/overview) organizations use Cloud US or Cloud EU. Self-hosting the data plane doesn't change these URLs. # HIPAA Source: https://docs.superblocks.com/enterprise/security/hipaa Under The HIPAA Security Rule, Superblocks complies with HIPAA requirements for Protected Health Information (PHI) and will sign a Business Associate Agreement (BAA) with customers who are subject to HIPAA mandates (typically, HIPAA covered entities). For more info on our security initiatives, see the [Trust Center](https://trust.superblocks.com/). # Security guide Source: https://docs.superblocks.com/enterprise/security/overview ### Data and network security * All traffic to and from the Superblocks is encrypted using TLS 1.2, 1.3 * All data on the Superblocks platform is encrypted at rest using AES-256 encryption * Superblocks servers are hosted in AWS across US and EU regions on SOC 2 and ISO 27001 certified infrastructure * Superblocks resources (Applications, APIs, Workflows, Integrations, Audit Logs) are stored in encrypted and network-protected databases with limited internal access ### IP Addresses The following IP addresses must be added to an allowlist in order for Superblocks to connect to your configured integrations. | NAT hostname | Current DNS | Last Recorded IPs | | - | - | - | | nat.superblocks.com | [A Records](https://dnsjson.com/nat.superblocks.com/A.json) | `100.24.157.155` `34.200.73.233` `34.209.17.50` `35.155.119.178` `35.86.18.137` `44.232.244.93` `54.211.180.182` `54.243.113.90` | | nat.eu.superblocks.com | [A Records](https://dnsjson.com/nat.eu.superblocks.com/A.json) | `13.50.50.66` `13.50.81.30` `13.51.231.18` `52.17.136.219` `54.220.65.107` `99.81.159.1` | While we do our best to never change these addresses, the best way to keep an updated allowlist is to use the current A records for the NAT hostname shown above, utilizing tools such as dig: ```bash theme={null} dig +short nat.superblocks.com | sort ``` or by using an API like dnsjson.com: ```bash theme={null} curl -s https://dnsjson.com/nat.superblocks.com/A.json | jq '.results.records|sort' ``` ### Superblocks deployment options See details in the [enterprise deployment overview](/enterprise/deployment-overview). # SOC 2 Type 2 Source: https://docs.superblocks.com/enterprise/security/soc2-type2 To request a copy of Superblocks SOC 2 report, please visit our [Trust Center](https://trust.superblocks.com/). Superblocks SOC 2 Type II report verifies the existence of internal controls which have been designed and implemented to meet the requirements for the security principles set forth in the Trust Services Principles and Criteria for Security, Availability, Processing Integrity and Confidentiality. The Type II report not only concerns the policies and procedures in place at a point in time, but validates their effectiveness over a 6 month period. This independent validation of security controls is especially crucial for customers in highly regulated industries. Here are a few examples of what you can read about in the report: * Security policies * Encryption protocols for data at rest and in motion * Logical and physical access controls * Change management process * Data backup and disaster recovery strategies * System monitoring, alerts and alarms Protecting the data and privacy of our customers is a non-negotiable aspect of what we do. Our SOC 2 certification provides you with an additional assurance that we have all the right controls in place to protect your data and ensure the availability of our service. # Contact us Source: https://docs.superblocks.com/enterprise/support/help You can reach out to Superblocks Support via email at [support@superblockshq.com](mailto:help@superblocks.com). Business hours are Monday through Friday from 09:00 to 18:00 Eastern Time. Outside of business hours, we aim to respond to any tickets within 24 business hours. # Low-Code to Clark transition Source: https://docs.superblocks.com/getting-started/moving-to-clark Transition from the Superblocks Low-Code platform to building with Clark AI If you've been using the Superblocks Low-Code platform, you can now start building with Clark — The Superblocks AI coding agent for building internal enterprise apps on your company data. ## Getting started with Clark AI **1. Switch to Clark AI view** In the **top right corner of the Superblocks header**, click the product switcher and select **Clark AI** to switch from the Low-Code view. ![Low-Code to Clark AI switcher](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/low-code-clark-switch.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=3e4316bbe1c37f94fabe7d13d86e151a) **2. Create your first application** Click **Create New** to start a new React application. Describe what you want to build in natural language and Clark will generate your app, complete with UI components and data integrations. ![Create new application](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/clark-create-new.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=6f2c6e9f2d562187c2fedfbc820a523d) **3. Start building** From here, you can tag integrations, add context, and iterate on your application using Plan and Build modes. See the full guide at [Building with Clark AI](/building-with-clark/index). ![Clark AI prompt homepage](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/clark-prompt-home.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=264a7e84a10f9e2f7721eb03d840accc) ## Using your existing integrations with Clark To start using Clark on your existing integrations, you'll need to opt them in. Because Clark [accesses data in edit mode](/building-with-clark/data-access) to build and debug your apps, you'll want to review which integrations are enabled to ensure they're set up appropriately. **1. Navigate to Integrations** From the Clark AI view, go to the **Integrations** page and click **Enable Integrations**. ![Integrations page](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/clark-integrations-empty.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=2b5604f08b401a980a0628888c78123a) **2. Select integrations to enable** Review your available integrations and select the ones you'd like Clark to use. Click **Enable** to confirm. ![Enable integrations modal](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/clark-integrations-enable.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=9e87b4a5482077df905e0efbb93ee461) **3. Start building with your data** Once enabled, your integrations are ready to use. Click **Create your first app** to start building, or tag these integrations directly from the Clark prompt. ![Integrations ready](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/clark-integrations-ready.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=114c8d2a4aaf3fbe36edb50dbd06f07d) **4. Enable more integrations later** You can always opt in more Low-Code integrations using the **Enable integrations for Clark** button on the Integrations page. ![Enable integrations for Clark button](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/getting-started/clark-enable-integrations-button.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=85fb5f7a827d290b5004aa96089d4866) Any new integrations you add from the Clark view will be available for both Clark and Low-Code. ## Migrating existing Low-Code apps Once you try Clark, you'll find that building apps is significantly faster, more powerful, and more flexible. To migrate an app, download its definition with the Superblocks CLI, then give it to Clark to rebuild in React. You can also use steps 1-4 to export your apps and rebuild them outside Superblocks. You'll need to replace anything the Superblocks platform provided, such as integrations, authentication, and access control. **1. Install the Superblocks CLI** Install or upgrade the CLI: ```bash theme={null} npm install -g @superblocksteam/cli@1.14.2 ``` The CLI connects to Cloud US (`app.superblocks.com`) by default. If your organization uses Cloud EU or a Cloud-Prem instance, point the CLI at your instance first, replacing `{tenant}` with the value from [Instance URLs](/enterprise/instance-urls): ```bash theme={null} superblocks config set domain {tenant}.superblocks.com ``` **2. Log in** ```bash theme={null} superblocks login ``` When prompted, paste your API token from the **Personal settings** page in Superblocks. **3. Download your Low-Code app** In an empty folder, run: ```bash theme={null} superblocks init ``` Press **Space** to select each app you want to download, then press **Enter**. The CLI downloads each app's definition as YAML files: | File | Contains | | - | - | | `application.yaml` and `.superblocks/superblocks.json` | Routes, navigation, global state, and APIs | | `pages//page.yaml` | Each page's layout and UI components | | `pages//apis//api.yaml` | Each backend API | **4. Zip the app** Compress the app's folder into a zip file, making sure the hidden `.superblocks` folder is included. For example: ```bash theme={null} zip -r my-app.zip ``` **5. Rebuild the app with Clark** In the Clark AI view, start a new app. [Attach the zip file](/building-with-clark/adding-context#uploading-files) and send this prompt: ```text theme={null} I need you to help me rebuild the attached legacy Superblocks app (YAML based) on this new system. Here is a breakdown of the files: - application.yaml and .superblocks/superblocks.json: contain information about routes, navigation, global state, and APIs - pages//page.yaml: each page's layout and UI definition (the core components) - pages//apis//api.yaml: all the backend APIs Can you read these to understand the application structure and recreate it with equivalent components and business logic in React? Note: for any integrations used in the backend APIs, you can use the same integration IDs that are used in the existing YAML API definitions. ``` Make sure the integrations your app uses are [enabled for Clark](#using-your-existing-integrations-with-clark) first, so Clark can connect to them. **6. Iterate** Clark's first version should get you most of the way there. Depending on how complex the app is, keep iterating with Clark to close any gaps. Screenshots of your original app are useful context for matching its layout and behavior. If you get stuck migrating a complex app, [reach out to us](mailto:support@superblockshq.com). # Introduction to Superblocks Source: https://docs.superblocks.com/getting-started/what-is-superblocks Superblocks is the platform to build and govern AI-generated internal apps. Business teams generate production apps on your company data with AI, while IT manages integrations, authentication, access controls, auditing, and policies from one place. [https://www.youtube.com/embed/A-ywb9ffwcQ?si=qSVnPZPbgruEcZQN](https://www.youtube.com/embed/A-ywb9ffwcQ?si=qSVnPZPbgruEcZQN) ## The Software Factory for Business Teams. Governed by Security & IT. Import from Claude, Lovable, Replit and code. Build with the Superblocks MCP. Built on your own stack – database, security tooling, inference and more. ![Architecture diagram: import prototypes from Claude, Replit, Lovable, and code; build with MCP through Claude, Slack, Cursor, and ChatGPT; then Build, Secure, and Deploy on your stack under the governance control plane](https://mintcdn.com/superblocks/qXDRwsY7quj-PAMm/images/intro/software-factory.png?fit=max\&auto=format\&n=qXDRwsY7quj-PAMm\&q=85\&s=12719f7ea2bb52bd0e96d302c6f1ed57) ## AI Apps never access business systems directly Superblocks is your **integration control layer**. It handles authentication, access controls, secrets management across databases, SaaS applications, and your internal APIs. Every database query and API call is centrally audited, so Admins have complete visibility. This lets business teams build quickly while IT keeps a consistent security and compliance posture. Learn more in [Integrations](/integrations/overview). ![AI on enterprise data](https://mintcdn.com/superblocks/mZPrswtUW_Mluny6/images/intro/ai-on-enterprise-data.png?fit=max\&auto=format\&n=mZPrswtUW_Mluny6\&q=85\&s=abf06e4376544621f31c57d626e40267) ## Go from Claude to Prod with a single prompt [Superblocks in Claude](/building-with-clark/superblocks-in-claude) lets business users turn prototypes into production apps with a single prompt, without leaving Claude. Apps open in Claude's built-in browser, and Superblocks applies your org's skills, standards, policies, and security rules to every prompt. * **Identity-aware.** Claude acts as you. Your SSO identity maps to your Superblocks permissions, so builders only do what their role allows. * **Governed integrations.** Imported apps use your connected integrations and platform-managed authentication and RBAC instead of hardcoded credentials. * **Code Security.** Publishing runs Code Security policies before anything ships. [https://www.youtube.com/embed/rwarTWtdvRY?si=pH-s0tQNustiG-Kt](https://www.youtube.com/embed/rwarTWtdvRY?si=pH-s0tQNustiG-Kt) ## A secure, isolated database for every app [Superblocks Database](/admin/superblocks-on-aws/database) gives every app its own Aurora PostgreSQL database inside your AWS account. Clark provisions it when an app needs to store data, and the data stays on your infrastructure. * **Automatic provisioning for every app.** Builders describe what they need to store, and Clark creates the database. No tickets and no manual setup. * **Isolated databases for each app and environment.** Each app gets its own database, and development and production stay separate so test data never reaches production. * **Schema management and migrations.** Clark keeps the schema in the app, and Superblocks applies those migrations on deploy. * **Sharing with granular permissions.** Share a database and control exactly who can use it. * **Smart packing.** Apps share clusters so infrastructure costs stay low, and Superblocks adds another cluster as the pool fills. * **Automatic isolation for high-traffic databases.** A busy database is isolated so it doesn't affect the others. ## Centrally manage your skills through Knowledge Bring your skills to Superblocks and enforce your standards as **[Organization Knowledge](/admin/org-administration/knowledge)**. Clark follows your standards by default — design systems, code and security expectations, domain terminology, and more. Clark also learns **integration knowledge** — your data sources, schemas, and endpoints — so it can write accurate queries and API calls. Knowledge is centrally managed with RBAC and a full audit trail, and Clark automatically updates it over time as your team builds. ![Clark knowledge and policies](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/clark_knowledge.png) ## Secure apps, out-of-the-box Superblocks enforces code security standards at every stage of the build lifecycle. Connect to your [private registry](/admin/code-security/supply-chain/private-registries) so Clark only pulls your approved packages. Clark checks packages for vulnerabilities [on install](/admin/code-security/supply-chain/cve-detection#install-time), [before publishing](/admin/code-security/supply-chain/cve-detection#publish-time), and [across your production apps](/admin/code-security/supply-chain/cve-detection#continuous-monitoring). Users are [notified of any new vulnerabilities](/admin/code-security/supply-chain/cve-notifications), and [Clark automatically fixes](/admin/code-security/supply-chain/cve-detection#fix-or-unpublish) them. Before every publish, [Policy Agents](/admin/code-security/index) run a [native security agent](/admin/code-security/security-agent), a [static analysis scan](/admin/code-security/static-analysis), and a [CVE scan](/admin/code-security/supply-chain/cve-detection#publish-time). This ensures your builders catch all security holes before the app reaches production. You can also run your own custom agents to enforce your standards, such as privacy policies, code review, design standards, and more. ![Publish checklist showing Security Agent findings, the Security Scan, and Vulnerability Detection](https://mintcdn.com/superblocks/qXDRwsY7quj-PAMm/images/intro/security-agent-findings.png?fit=max\&auto=format\&n=qXDRwsY7quj-PAMm\&q=85\&s=20282f09fd20b6f9e39588833fbffe80) ## Manage role-based access control [Admins centrally manage](/admin/org-administration/overview) users and control access across Development, Staging, and Production environments. Sync in your users and groups from your IdP (such as Okta or Entra) and enforce permissions consistently across apps and integrations based on their roles. ![Admin roles overview](https://mintcdn.com/superblocks/7crJuJbk_a8yFfiD/images/administration/roles-overview.png?fit=max\&auto=format\&n=7crJuJbk_a8yFfiD\&q=85\&s=824c1a9a94eb7955534b7c96cb26e5af) ## Deploy the way your organization needs Choose the right deployment model for your security and compliance requirements — **Superblocks Cloud**, **Hybrid**, or **Cloud-Prem**. Learn more in [Enterprise deployment & security](/enterprise/deployment-overview). ![Superblocks deployment options](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/deployment_options.png) ## Get started * [Building with Clark](/building-with-clark/index) * [Superblocks in Claude](/building-with-clark/superblocks-in-claude) * [Integrations](/integrations/overview) * [Superblocks Database](/admin/superblocks-on-aws/database) * [Admin guide](/admin/org-administration/overview) * [Enterprise deployment & security](/enterprise/deployment-overview) # Authentication for Databricks Apps Source: https://docs.superblocks.com/hosting/databricks-apps/authentication Databricks Apps rely on Databricks for workspace authentication, then establish a Superblocks session so Superblocks can identify the user and enforce Superblocks authorization. This page explains the end to end flow and how to configure your Databricks environment to support this authentication flow. ## End to end authentication flow When a user opens a Superblocks App in a Databricks workspace: 1. Databricks authenticates the user and launches the app runtime. 2. The Databricks App backend authenticates the user with Superblocks. 3. Superblocks establishes a session for the user and evaluates Superblocks permissions. 4. When the app runs a query or calls Databricks APIs, Superblocks gets a scoped Databricks API token using token exchange that ensures all actions run with the correct Unity Catalog permissions of the app’s service principal or end-user. Databricks remains the source of truth for workspace identity and data access. ## How users are authenticated with Superblocks When a Superblocks App runs inside a Databricks workspace, Databricks is responsible for authenticating the user. Superblocks then establishes its own session so it can identify the user and enforce Superblocks authorization. To do this securely, the Databricks App backend must authenticate itself to Superblocks. This is done using a Superblocks embed token. The embed token allows Superblocks to: * Trust the Databricks App runtime * Associate the Databricks app with a Superblocks organization * Issue short-lived authorization credentials for accessing the app as a Superblocks user If the embed token is missing or invalid, Superblocks cannot authenticate the user and the app will fail to load. For a detailed explanation of the Embedded App authentication flow, see the [Embedded App Authentication](/hosting/embedded-apps/authentication) documentation. ## Creating an Embed Token To create an Embed Token for authenticating with Superblocks, a Superblocks Admin should: 1. Log in to Superblocks 2. Navigate to **Access Tokens** page in **Organization Settings** 3. Create a new **Embed Token** for Databricks Apps 4. Copy the token value securely Treat this token like a password. Do not commit it to source control or share it broadly. ## Storing the token in Databricks Secrets Once the embed token has been created, a Databricks Workspace Admin should store the token as a Databricks Secret. This will let you securely share the token with your Databricks Apps. To store the token as a Databricks Secret: 1. Create or select a Databricks secret scope 2. Add a new secret with the embed token value 3. Restrict access to the secret scope as needed Example: ``` $ databricks secrets create-scope --scope superblocks $ databricks secrets put-secret --json '{ "scope": "superblocks", "key": "embed_token", "string_value": "" }' ``` Only the secret name should be shared with developers. For full details on how to create and manage Databricks Secrets see [Databricks Secrets](https://docs.databricks.com/aws/en/security/secrets/?language=Databricks%C2%A0CLI#secrets-overview) docs. ## Reference the token in the Databricks App With the secret stored as a Databricks Secret, developers can reference the secret in their app’s `app.yaml` without ever seeing the token value. For example: ``` env: - name: SUPERBLOCKS_EMBED_ACCESS_TOKEN valueFrom: embed_token ```   To set this up, follow Databricks’s docs on how to [Add a secret resource to a Databricks app](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/secrets). ## Common issues If the embed token is misconfigured, you may see: * The app loads in Databricks but fails to render * Authentication errors during app startup * Errors indicating the app is not authorized to embed In most cases, these issues are resolved by verifying: * The embed token exists and is active * The token is stored correctly in Databricks secrets * The Databricks App references the correct secret * The token has not been revoked or rotated without updating Databricks ## Next steps * [Deploy your app to Databricks](/hosting/databricks-apps/deploy) * Review the required environment configuration in the [Environment setup](/hosting/databricks-apps/setup) guide # Deploying a Superblocks App to Databricks Source: https://docs.superblocks.com/hosting/databricks-apps/deploy This quick start shows how to deploy a Superblocks app so it runs inside Databricks as a Databricks App using the official [Superblocks template](https://github.com/superblocks-samples/databricks-superblocks-app). This guide focuses on getting your app live quickly. For advanced configuration or implementation details, refer to the template repository [README](https://github.com/superblocks-samples/superblocks-databricks-app/blob/main/README.md). ## What You’ll need Before you start, make sure you have: * A working Superblocks app * [Set up your Superblocks environment](/hosting/databricks-apps/setup) to work with Databricks runtime * A [Superblocks embed token](/hosting/databricks-apps/authentication) stored as a Databricks secret * [Databricks Apps enabled in your workspace](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configure-env#set-up-your-databricks-workspace) * [Databricks CLI installed and authenticated](https://docs.databricks.com/aws/en/dev-tools/cli/install) ## Step 1: Create the Databricks App and add the secret Create a new Databricks App in your workspace by following the official Databricks documentation:\ [**Create a Databricks App**](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/create-custom-app?utm_source=chatgpt.com) During the app creation flow, add the Superblocks embed token as an App resource: 1. In the **Configure** step, go to **App resources** 2. Click **Add resource** 3. Select **Secret** as the resource type 4. Choose the secret scope and secret key where the Superblocks embed token is stored 5. Grant the app read access to the secret 6. Assign a resource key, for example superblocks\_embed\_token ## Step 2: Clone the Databricks App template Clone the official Superblocks Databricks App template: ``` $ git clone https://github.com/superblocks-samples/superblocks-databricks-app $ cd superblocks-databricks-app $ npm install $ npm run build ``` This template is a lightweight wrapper that embeds your Superblocks app and integrates authentication inside Databricks. ## Step 3: Configure the app Open `app.yaml` and configure the required values for your Databricks workspace and Superblocks app. At a minimum, configure: * Your Superblocks instance URL, `https://{tenant}.superblocks.com`. Replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls) * Your Superblocks application ID * A reference to the **Databricks Secret resource key** you created in Step 1 For example: ``` env: - name: SUPERBLOCKS_URL value: https://{tenant}.superblocks.com - name: SUPERBLOCKS_APPLICATION_ID value: - name: SUPERBLOCKS_EMBED_ACCESS_TOKEN valueFrom: superblocks_embed_token ``` Do not hard-code secret values. Only reference the resource key. ## Step 4: Deploy to Databricks Sync the source code into your Databricks workspace and deploy your app ``` $ databricks sync . /Workspace/Users// $ databricks apps deploy \ --source-code-path /Workspace/Users// ``` Databricks builds and launches the app using the Superblocks template. ## Step 5: Open the app Once deployment completes, open your app at: `https://.cloud.databricks.com/apps/` Your Superblocks app is now running inside Databricks! ## How it works Once deployed, the Databricks App runs as a lightweight wrapper around your Superblocks application. At a high level: * Users access the app directly inside Databricks and authenticate with their Databricks identity * The app embeds the Superblocks UI and passes user context securely to Superblocks * Backend APIs generated by Clark execute through the Superblocks data plane * Those APIs issue SQL queries and Databricks REST API calls directly to Databricks services * Databricks executes all data, job, pipeline, and AI workloads * Unity Catalog enforces permissions for every query and API call Clark builds the APIs. Databricks executes the workloads. This model keeps application development fast while ensuring data access, execution, and governance remain fully Databricks-native. ## Learn more about the deployment This quick start intentionally keeps deployment simple. If you want to learn more about: * How the Databricks App wrapper works * Authentication and token exchange flows * Advanced configuration options * Customizing the wrapper app Refer to the full template repository and README: [**Superblocks Databricks App Template**](https://github.com/superblocks-samples/superblocks-databricks-app) # Superblocks on Databricks Apps Overview Source: https://docs.superblocks.com/hosting/databricks-apps/overview Databricks is where your data lives. Superblocks helps you turn that data into applications people actually use. With Superblocks, you build Databricks-powered applications by describing what you want and let **Clark** (Superblocks AI copilot) handle the rest. No custom frontend code. No backend boilerplate. No complex deployment processes or infra to manage. Just fast, intuitive app building that plugs straight into the Databricks ecosystem. Apps built with Superblocks can be deployed directly as Databricks Apps, while access to Databricks data and compute is still fully governed by Unity Catalog. ## Build apps fast with Clark Superblocks makes it easy to turn ideas into Databricks apps using AI. With Clark, teams can: * Describe the app they want to build in plain language * Generate application interfaces along with backend APIs * Automatically produce SQL queries and REST API calls to Databricks services (within the user’s permissions) * Iterate quickly without rewriting frontend code or hand-coding backend logic Clark builds the APIs and query logic. Databricks executes the SQL, jobs, pipelines, and AI workloads. ## Expand who can build while keeping governance intact Superblocks integrates directly with [Databricks OAuth Token Federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) so every generated SQL query and REST API call runs using the user’s Databricks identity. This means: * Unity Catalog permissions are enforced automatically * Access controls apply when Clark generates queries and APIs, not just at runtime * Analysts and operators can safely build apps without elevated privileges Databricks remains the authority on who can access data. ## Ship apps directly into Databricks When an app is ready to ship, Superblocks makes it easy to deploy it directly as a Databricks App. Teams get: * Fast deployment with minimal setup * Apps that execute SQL queries and Databricks API calls from a familiar Databricks surface * A consistent experience for users who already work in Databricks Users access the app directly inside Databricks, alongside their existing workflows. ## Govern app access with Unity Catalog Access to deployed apps is governed using the same Unity Catalog policies that protect Databricks resources. As a result: * SQL queries and Databricks API calls made by the app respect existing permissions * Changes to Unity Catalog policies are reflected immediately in app behavior * Governance remains centralized, consistent, and auditable From development through production, Unity Catalog stays in control of who can access the app. ## Get started Getting started with Superblocks and Databricks Apps is straightforward. Follow these guides to go from building with Clark to running a governed, production-ready Databricks App. * Set up a [Databricks SQL](/integrations/integrations-library/databricks) or [REST API](/integrations/integrations-library/rest-api) Integration for Databricks * Review the required environment configuration in the [Environment setup](/hosting/databricks-apps/setup) guide * Set up [Authentication](/hosting/databricks-apps/authentication) for Superblocks and learn how to securely manage your Superblocks Embed Token using Databricks Secrets * [Deploy your app to Databricks](/hosting/databricks-apps/deploy) # Superblocks setup for Databricks runtime Source: https://docs.superblocks.com/hosting/databricks-apps/setup Before deploying a Superblocks App to Databricks, you must configure your Superblocks environment to support the Databricks Apps runtime. This page covers all required setup steps. If any of these steps are skipped or misconfigured, the app may deploy successfully but fail at runtime. ## What you are setting up A deployed Databricks App runs inside a Databricks workspace. When the app makes Databricks SQL or REST API calls, it typically relies on **OAuth On Behalf Of Token Exchange** so Databricks can issue the correct access token for the identity accessing the app. To support this cleanly, we recommend that customers use a dedicated data tag for Databricks Apps, along with data tag specific integration configurations for Databricks SQL and Databricks REST API. ## Prerequisites To configure the environment, you’ll need the following in Superblocks: * Permission to [create and manage data tags](/admin/environments) * Permission to manage the Databricks Integrations your application uses ## Step 1: Create a dedicated Databricks Apps data tag Create a dedicated [data tag](/admin/environments) in Superblocks, typically named **Databricks Apps**. **Why this matters:** * Databricks Apps require authentication behavior that differs from Superblocks-hosted apps * Data tag isolation prevents breaking existing apps by mixing incompatible auth methods * You can change Databricks Apps specific settings without affecting other environments **Note for Hybrid customers** Creating a new data tag may require updating the tags associated with your self-hosted data-plane. Follow the tagging guide to make sure one of your containers can serve as the runtime for your Databricks App APIs. ## Step 2: Identify the Databricks token exchange endpoint Databricks Apps require Superblocks to exchange tokens using the Databricks OIDC token endpoint: ``` https:///oidc/v1/token ``` You will use this same token URL in both the Databricks SQL integration configuration and the Databricks REST API integration configuration for the **Databricks Apps** data tag. ## Step 3: Configure Databricks SQL integrations For each Databricks SQL integration used by your app: 1. Add a configuration scoped to the **Databricks Apps** data tag 2. Set the authentication type to **OAuth Token Federation** 3. Set the subject token source to **Login Identity Provider** 4. Set the **Token URL** to `https:///oidc/v1/token` This ensures SQL queries executed by the deployed app run under the expected identity when the app is running inside Databricks. ## Step 4: Configure Databricks REST API integration For each Databricks REST API integration used by your app: 1. Add a configuration scoped to the **Databricks Apps** data tag 2. Set authentication type to **OAuth 2.0: On Behalf Of Token Exchange** 3. Set subject token source to **Login Identity Provider** 4. Set **Subject Token Type** to `urn:ietf:params:oauth:token-type:access_token` 5. Set **Token URL** to `https:///oidc/v1/token` 6. Set **Scope** to `all-apis` 7. Under **Headers** add `Authorization: Bearer {{ oauth.token }}` This ensures REST API calls, including Jobs, Pipelines, Unity Catalog, and Model Serving, run under the correct identity. ## Step 5: Set the app’s Production data tag Before deploying your app to Databricks, set the app’s Production data tag to **Databricks Apps**. This is required. If the Production data tag is not set correctly, the app will run with the wrong integration configuration and token exchange will fail at runtime. Learn more about how to [set your app's Production data tag](https://docs.superblocks.com/development-lifecycle/build/data-tags). ## Step 6: Verify the environment before deployment  Before deploying, confirm the following: ### Integration verification * Databricks SQL integration has a configuration for the **Databricks Apps** data tag * Databricks REST API integration has a configuration for the **Databricks Apps** data tag * All integrations use the Databricks OIDC token endpoint * Databricks REST API integration scope is all-apis * The `Authorization` Header is configured in your Databricks REST API integration ### Data tag verification * The **Databricks Apps** data tag exists and is selected as the app’s Production data tag * If self-hosting, your agents are tagged to support the **Databricks Apps** data tag ### Access verification * The Databricks identity used at runtime has access to required SQL warehouses * The Databricks identity used at runtime has permission to call required REST APIs ## Next steps * Learn how [Authentication](/hosting/databricks-apps/authentication) works for Databricks Apps * [Deploy your app to Databricks Apps](/hosting/databricks-apps/deploy) # Authenticating embedded users Source: https://docs.superblocks.com/hosting/embedded-apps/authentication When you embed a Superblocks app into your website, you have several options for authentication: * **Public**: anyone can view your app, no login required * **Private**: users log in to Superblocks directly and must have [`apps:view`](/admin/org-administration/resource-roles#applications) permission to the application * **SSO**: use your application's existing login flow so users only have to log in once to access the embedded Superblocks app **Public** and **Private** embeds have no added set up. Follow instructions below to configure **SSO**. ## SSO authentication flow With **SSO** embedding, users access your embedded app without needing a separate Superblocks login. Instead, you'll log users in with your app's existing auth and issue them a Superblocks session token for embedded auth. Using the Superblocks session token, your user's identity, level of access, and metadata are securely transmitted to Superblocks so they can't be modified by users client-side. The following diagram illustrates the authentication flow for SSO embed users: ![Sequence diagram showing how to request a session token for an embedded user](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/custom-login.jpg?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=9a3a29db362f490f7cca5b99a79aa83a) ## Set up embedded SSO Use the following instructions to have your application authenticate users with Superblocks. ### Step 1. Generate an access token Only organization **Admins** can create Embed access tokens. To get Superblocks session tokens for your embed users, you'll need to create an **Embed** access token. Follow the instructions below to create an access token, or learn more about [Access tokens](/admin/org-administration/auth/access-tokens). 1. Click your avatar in the upper-left corner of the home page and click **Organization Settings** ![Menu for switching to settings menus](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/avatar-menu.png?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=240d71751dd82d1c6342cdd5f6871297) 2. In the left sidebar, click **Access Tokens** 3. Click **+Create token** 4. In the **Name** field give your token a descriptive name 5. Select an **Expiration** date, or use the default 90 day expiration. 6. Select **Embed** as the token type ![Interface for creating an embed access token](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/access-token.png?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=b0945b5e8d4527635ba7964c70851c1e) 7. Click **Create** Save your tokens immediately Your access token is visible one time, immediately after you create it. If you leave or refresh the page where the token is displayed, it will be obscured and no longer visible. You must copy and store new access tokens somewhere secure before you leave the creation page, or you will lose access to the token. ### Step 2. Add token endpoint to your web-server Add an endpoint to your web-server that requests user session tokens from Superblocks. You can add this as a new endpoint, or to your existing authentication flow. In the examples, replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). > [tab] Node.js (Express) > > ```javascript server.js icon="js" theme={null} > // Get user session token from Superblocks API > app.get('/api/superblocks/token', checkAuthentication, async (req, res) => { > > // Assuming getUser returns the currently authenticated user > const user = getUser(req); > > const config = { > url: `https://{tenant}.superblocks.com/api/v1/public/token`, > method: 'post', > headers: { > 'Authorization': `Bearer ${YOUR_ACCESS_TOKEN_HERE}`, > 'Content-Type': 'application/json', > }, > data: { > email: user.email, > name: `${user.firstName} ${user.lastName}`, > metadata: { > externalUserId: user.id, > externalOrgId: user.organization.id > } > } > }; > > // Call endpoint to request a Superblocks session token on-behalf-of the authenticated user > axios(config) > .then((response) => { > if (response.status === 200) { > res.json(response.data); > } else { > throw new Error('Could not authenticate user with Superblocks'); > } > }) > .catch((error) => { > res.status(401).json({ error: 'unathorized', message: error.message }); > }); > }); > ``` > [tab] Python (Flask) > > ```python app.py icon="python" theme={null} > from flask import jsonify > import requests > > @app.route('/api/superblocks/token', methods=['GET']) > def superblocks_auth(): > # Assuming getUser() returns the currently authenticated user > user = getUser() > > # Call /token endpoint to request a session on-behalf-of the authenticated user > response = requests.post( > "https://{tenant}.superblocks.com/api/v1/public/token", > headers={ > 'Authorization': f'Bearer {YOUR_ACCESS_TOKEN_HERE}', > 'Content-Type': 'application/json' > }, > json={ > 'email': user.email, > 'name': f'{user.firstName} {user.lastName}', > 'metadata': { > 'externalUserId': user.id, > 'externalOrgId': user.organization.id > } > } > ) > > if response.status_code == 200: > data = response.json() > return jsonify(data) > else: > return jsonify({ > 'error': 'unauthorized', > 'error_description': 'Could not authenticate user with Superblocks' > }, 401) > ``` > [tab] Django > > ```python views.py icon="python" theme={null} > from django.http import JsonResponse > from django.views import View > from django.contrib.auth.mixins import LoginRequiredMixin > import requests > > class SuperblocksAuth(LoginRequiredMixin, View): > def get(self, request): > user = request.user > > # Call /token endpoint to request a session on-behalf-of the authenticated user > response = requests.post( > "https://{tenant}.superblocks.com/api/v1/public/token", > headers={ > 'Authorization': f'Bearer {YOUR_ACCESS_TOKEN_HERE}', > 'Content-Type': 'application/json' > }, > json={ > 'email': user.email, > 'name': f'{user.firstName} {user.lastName}', > 'metadata': { > 'externalUserId': user.id, > 'exgernalOrgId': user.organization.id > } > } > ) > > if response.status_code == 200: > data = response.json() > return JsonResponse(data) > else: > return JsonResponse({ > 'error': 'unauthorized', > 'error_description': 'Could not authenticate user with Superblocks' > }, status=401) > ``` Make sure to replace the payload with information for the currently authenticated user. Make sure your web server has CORS enabled if it's running on a different domain than your host application. For a detailed explanation of the parameters, request format, and response format for the `/token` endpoint, please refer to the full [API specification](#token-api-specification) below. ### Step 3. Request token client-side Add code to your web application to request a session token from the token endpoint you just added to your application's web server. > [tab] React > > ```tsx src/utils.tsx icon="react" theme={null} > export const getSBToken = () => { > return fetch(`https://${YOUR_API_DOMAIN}/api/superblocks/token`).then( > res => res.json() > ).then( > data => data.access_token > ).catch( > err => { > throw new Error('Superblocks Auth Error'); > } > ); > } > ``` > [tab] JavaScript > > ```js src/utils.js icon="js" theme={null} > function getSBToken () { > return fetch(`https://${YOUR_API_DOMAIN}/api/superblocks/token`).then( > res => res.json() > ).then( > data => data.access_token > ).catch( > err => { > throw new Error('Superblocks Auth Error'); > } > ); > } > ``` ### Step 4. Pass the token to your embed > [tab] React > > ```tsx src/views/embed_page.tsx icon="react" theme={null} > import React, { useState, useEffect } from 'react'; > import { SuperblocksEmbed } from '@superblocksteam/embed-react'; > import { getSBToken } from '../utils'; > > const PageWithEmbed = () => { > const [token, setToken] = useState(null); > > useEffect(() => { > getSBToken() > .then((token) => setToken(token)) > .catch(err => console.log('Failed to get Superblocks auth token')); > }, []); > > const handleFailedAuth = (err) => { > console.log('Superblocks auth token invalid'); > } > > return <> > { token ? > src='https://{tenant}.superblocks.com/code-mode/embed/applications/' > token={token} > onAuthError={handleFailedAuth} > /> : >
Loading...
> } > ; > } > ``` > [tab] JavaScript > > ```html src/pages/embed_page.html icon="js" theme={null} > > ``` ## Manage user access Embed users must have the [`apps:view`](/admin/org-administration/resource-roles#applications) permission to the Superblocks app they're trying to access. Grant users access by associating them with a [**Group**](/admin/org-administration/groups) with the necessary access level. To associate an embed user with a group: 1. Click your avatar in the upper-left corner of the home page 2. In the menu, click **Organization Settings** 3. In the left sidebar, click **Groups** 4. Either select **+ Add group** or click into an existing group 5. On the **Permissions** tab, enable **View** access for apps you want the user(s) to have access to ![Cash App Customer user group with view access to "Credit Card Application Processing" tool](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/group-permissions.png?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=412b79ac586573a18b478e08774430f1) 6. Go back to the **Groups** page and copy the group's ID by selecting **...** → **Copy group ID** ![Groups page with options menu open showing option to copy the group's ID](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/groups-copy-id.png?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=bd9b790c199d50c9e76d9ed8ed245ca5) 7. Update your [server endpoint](#step-2-add-token-endpoint-to-your-web-server) by adding a list of `groupIds` you want users to be associated with > [tab] Node.js (Express) > > ```jsx theme={null} > fetch("https://{tenant}.superblocks.com/api/v1/public/token", { > ... > body: JSON.stringify({ > 'email': user.email, > 'name': `${user.firstName} ${user.lastName}`, > > // Superblocks Group IDs which grant view access to apps embedded in this website > 'groupIds': [ > 'cc07e026-02c7-4ab5-b33b-232d57e7c804' > ] > }) > }); > ``` > [tab] Python (Flask) > > ```python theme={null} > response = requests.post( > "https://{tenant}.superblocks.com/api/v1/public/token", > ... > json={ > 'email': user.email, > 'name': f'{user.firstName} {user.lastName}', > > # Superblocks Group IDs which grant view access to apps embedded in this website > 'groupIds': [ > 'cc07e026-02c7-4ab5-b33b-232d57e7c804' > ] > } > ) > ``` > [tab] Django > > ```python theme={null} > # Call /token endpoint to request a session on-behalf-of the authenticated user > response = requests.post( > "https://{tenant}.superblocks.com/api/v1/public/token", > ... > json={ > 'email': user.email, > 'name': f'{user.firstName} {user.lastName}', > > # Superblocks Group IDs which grant view access to apps embedded in this website > 'groupIds': [ > 'cc07e026-02c7-4ab5-b33b-232d57e7c804' > ] > } > ) > ``` Embed users aren't permanent members of groups and won't show up on the **Members** tab of groups. They are associated with the group for permissions purposes for the duration of the token's session. ## Customize user metadata User metadata lets you attach additional information to a user beyond the standard attributes. This can be useful for storing extra data relevant to your application or business logic. To customize user metadata, include a `metadata` field in your request payload with JSON representing the metadata you want to add. For example: > [tab] Node.js (Express) > > ```jsx theme={null} > fetch("https://{tenant}.superblocks.com/api/v1/public/token", { > method: 'POST', > ... > body: JSON.stringify({ > 'email': user.email, > 'name': `${user.firstName} ${user.lastName}`, > 'metadata': { > 'externalUserId': user.id, > 'externalOrgId': user.organization.id, > > // Additional user metadata to customize app behavior > 'isAdmin': user.roles.includes('Admin') > } > }) > }); > ``` > [tab] Python (Flask) > > ```python theme={null} > response = requests.post( > "https://{tenant}.superblocks.com/api/v1/public/token", > ... > json={ > 'email': user.email, > 'name': f'{user.firstName} {user.lastName}', > 'metadata': { > 'externalUserId': user.id, > 'externalOrgId': user.organization.id, > > # Additional user metadata to customize app behavior > 'isAdmin': 'Admin' in user.roles > } > } > ) > ``` > [tab] Django > > ```python theme={null} > # Call /token endpoint to request a session on-behalf-of the authenticated user > response = requests.post( > "https://{tenant}.superblocks.com/api/v1/public/token", > ... > json={ > 'email': user.Email, > 'name': f'{user.firstName} {user.lastName}', > 'metadata': { > 'externalUserId': user.id, > 'externalOrgId': user.organization.id > > # Additional user metadata to customize app behavior > 'isAdmin': 'Admin' in user.roles > } > } > ) > ``` Metadata is associated with the user's current session and encoded in the session JWT as custom claims. This ensures that the metadata cannot be modified client-side, providing an additional layer of protection against unauthorized tampering. You can [prompt Clark](/building-with-clark) to build any conditional logic based on this user metadata. For example, display, hide, or disable a certain component based on an `isAdmin` metadata attribute ![](https://mintcdn.com/superblocks/KHjvHFpLh3BONvUl/images/hosting/clark_embed_metadata.png?fit=max\&auto=format\&n=KHjvHFpLh3BONvUl\&q=85\&s=6ead28c23362ee90c33c9b981dd19740) Under the hood, Clark leverages the `useSuperblocksUser()` function to get the logged in user and check their metadata. Here is the code generated from the prompt above. ```tsx index.tsx icon="react" theme={null} import { useSuperblocksUser } from "@superblocksteam/library"; import { Button } from "@/components/ui/button"; import { Icon } from "@/components/ui/icon"; import { Tooltip } from "@/components/ui/tooltip"; export default function Page1Component() { const user = useSuperblocksUser(); const isAdmin = user?.metadata?.isAdmin === true; const deleteButton = ( ); return (
{isAdmin ? ( deleteButton ) : ( {deleteButton} )}
); } ``` If you prefer to edit and review this logic directly, see [developing apps in code](/building-with-clark/developing-apps-in-code). ## Token API specification #### POST `/api/v1/public/token` Use this endpoint to request a session token for an embedded user. Send requests to `https://{tenant}.superblocks.com/api/v1/public/token`, replacing `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). **Request parameters** `application/json` | Parameter | Required | Type | Description | | - | - | - | - | | `email` | ✓ | String | The user's email address, which uniquely identifies them in Superblocks. | | `name` | | String | The user's full display name. | | `groupIds` | | Array | Superblocks Group IDs to associate the embed user with. | | `metadata` | | Object | Object containing additional metadata about the user. | | `isSuperblocksUser` | | Boolean | If `TRUE`, the token will be associated with the Superblocks platform user with the email specified. If no platform user exists with that email, the user will get an Unauthorized error. | | `subject_token_type` | | String | The type of token being passed in `subject_token`. Required when using `subject_token`. Must be set to `urn:ietf:params:oauth:token-type:access_token`. See [On-Behalf-Of Token Exchange](/integrations/auth/oauth-20#on-behalf-of-token-exchange) for more details. | | `subject_token` | | String | An access token from an external identity provider (e.g., Okta, Auth0, your web server) that will be used in OAuth2.0 Token Exchange auth flows. See [On-Behalf-Of Token Exchange](/integrations/auth/oauth-20#on-behalf-of-token-exchange) for more details. | > [tab] cURL > > ```bash theme={null} > curl --request POST > --url 'https://{tenant}.superblocks.com/api/v1/public/token' \ > --header 'authorization: Bearer {YOUR_ACCESS_TOKEN_HERE}' \ > --header 'content-type: application/json' \ > --data-raw '{ > "email":"jane.wind@company.com", > "name": "Jane Wind", > "metadata": { > "externalUserId": "d942c6...72f362", > "externalOrgId": "c32979...acf711" > } > }' > ``` > [tab] Node.js > > ```jsx theme={null} > const axios = require('axios'); > > const config = { > url: `https://{tenant}.superblocks.com/api/v1/public/token`, > method: 'post', > headers: { > 'Authorization': `Bearer ${YOUR_ACCESS_TOKEN_HERE}`, > 'Content-Type': 'application/json', > }, > data: { > "email": "jane.wind@company.com", > "name": "Jane Wind", > "metadata": { > "externalUserId": "d942c6...72f362", > "externalOrgId": "c32979...acf711" > } > } > }; > > axios(config) > .then((response) => { > if (response.status === 200) { > res.json(response.data); > } else { > throw new Error('Could not authenticate user with Superblocks'); > } > }) > .catch((error) => { > res.status(401).json({ error: 'unathorized', message: error.message }); > }); > ``` > [tab] Python > > ```python theme={null} > import requests > import json > > url = "https://{tenant}.superblocks.com/api/v1/public/token" > > payload = { > "email": "jane.wind@company.com", > "name": "Jane Wind", > "metadata": { > "externalUserId": "d942c6...72f362", > "externalOrgId": "c32979...acf711" > } > } > > headers = { > 'authorization': 'Bearer {YOUR_ACCESS_TOKEN_HERE}', > 'content-type': 'application/json' > } > > response = requests.request("POST", url, headers=headers, json=payload) > > print(response.text) > ``` **Response Sample** ```json theme={null} HTTP/1.1 200 OK Content-Type: application/json { "access_token":"eyJz93a...k4laUWw", "token_type":"Bearer", "expires_in":86400 } ``` # Login embed users with Auth0 Source: https://docs.superblocks.com/hosting/embedded-apps/how-tos/use-auth-for-sso If your app uses Auth0 for authentication, you can easily extend your existing login flow to log users into Superblocks as well. This tutorial shows how to use [Auth0 Actions](https://auth0.com/docs/customize/actions) to configure your [Embedded App SSO](/hosting/embedded-apps/authentication) flow. ## Prerequisites To follow this guide you'll need: * An [Auth0 Account](https://auth0.com/signup?place=header\&type=button\&text=sign%20up) * A client-side app using Auth0 for user authentication. See [code examples](https://developer.auth0.com/resources/guides?type=web-app%2Cspa) to create one ## Configure login flow Use the following instructions to authenticate embedded app users with Superblocks by requesting a session token when logging users into Auth0 using [Auth0 Login Flow](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow). ### Step 1. Generate an Embed access token To get Superblocks session tokens for your Auth0 users, you'll need an **Embed** access token. See docs on Access Tokens to see how to [Create an Embed access token](/admin/org-administration/auth/access-tokens). ### Step 2. Add Superblocks Login action Add an action to get a user session token from Superblocks. 1. Navigate to **Auth0 Dashboard → Actions → Library**, then select **Create Action → Build from scratch** 2. Enter the following in the Create action form, then select **Create** | Field | Value to enter | | - | - | | Name | Superblocks Login | | Trigger | Login / Post Login | 3. Click **Add secret** and configure it as follows, then select **Create** | Field | Value to enter | | - | - | | Key | `SUPERBLOCKS_TOKEN` | | Value | Paste in the **Embed access token** you created in Step 1 | 4. Click on the **Dependency** icon in the left sidebar 5. Click **Add dependency**. In the **Name** field specify `axios`, then click **Create** 6. Copy/paste the following Action into the code editor ```js theme={null} /** * Handler that will be called during the execution of a PostLogin flow. * * @param {Event} event - Details about the user and the context in which they are logging in. * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login. */ exports.onExecutePostLogin = async (event, api) => { const axios = require("axios"); const SUPERBLOCKS_TENANT = "app" // "app" for Cloud US, "eu" for Cloud EU, or your Cloud-Prem tenant name const SUPERBLOCKS_BASE_API = `https://${SUPERBLOCKS_TENANT}.superblocks.com/api/v1/public/token`; const user = { "email": event.user.email, "name": event.user.name, "metadata": { // Additional user or organization metadata //"externalUserId": event.user.user_metadata.id, //"externalOrgId": event.organization.metadata.id }, //"groupIds": [""], }; const response = await axios.request({ method: 'post', url: SUPERBLOCKS_BASE_API, headers: { 'authorization': `Bearer ${event.secrets.SUPERBLOCKS_TOKEN}`, 'content-type': 'application/json' }, data : user }); const token = response.data; api.idToken.setCustomClaim(`superblocks_token`, token.access_token); }; ``` 7. Click on the **Test** icon in the left side panel. Test the action to make sure it runs without any errors 8. Click **Deploy** to save and deploy the action ### Step 3. Add Superblocks Login action to login flow Now that you have a Superblocks Login action, you can add it to your [Auth0 Login Flow](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow) so a session token is generated each time a user logs in using Auth0. 1. Navigate to **Auth0 Dashboard → Actions → Flows** 2. Select the **Login** flow and drop **Superblocks Login** into the flow 3. Select **Apply** ### Step 4. Pass token to your embed Your login flow is now configured to add a `superblocks_token` to the user's `idToken` each time the user logs in via Auth0. To get the `superblocks_token`, either decode the `idToken` stored by Auth0, or use an [Auth0 SDK](https://auth0.com/docs/libraries) and access the token as follows, replacing `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls): ```tsx src/views/embed_page.tsx icon="react" theme={null} import React, { useState, useEffect } from 'react'; import { SuperblocksEmbed } from '@superblocksteam/embed-react'; import { useAuth0 } from "@auth0/auth0-react"; const PageWithEmbed = () = { const { user } = useAuth0(); return <> { user.superblocks_token ? :
User not authenticated
} } ``` For more code examples from Auth0, check out [Auth0's code samples](https://developer.auth0.com/resources/code-samples) library. Your user is now authenticated with Superblocks! Go further with SSO by reading the full docs on [Embedded App Authentication](/hosting/embedded-apps/authentication). # Interactive embedding Source: https://docs.superblocks.com/hosting/embedded-apps/interactivity Once you have a basic embed set up, you can add interactive communication between the host app and Superblocks embedded app using **properties** and **events**: * [**Properties**](#properties-pass-data-from-host-to-embed) - Send *reactive data* from the host app to the embedded app to update its state (e.g., pass search terms or selected filters, set dark or light mode) * [**Events**](#events-two-way-communication) - Trigger *actions* bidirectionally from events in the host app or embedded app (e.g. scroll page of host app when button in embedded app is clicked, sync the URL path anytime page navigation happens in either the host or embedded app) To implement any of these features, you'll need to add the necessary logic in your host app, and then prompt Clark to set up the embed interface in your Superblocks app. In the examples, replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). ## Properties - Pass data from host to embed Send data to your embedded app to customize what users see based on properties of the host application. Properties are reactive—when they change in the host app, the embedded app automatically receives the updated values. Follow the steps below to get started working with properties. **1. Set properties in host app** In the host app, add logic for setting properties and passing them to the embed component. For example, here the host app sets a `searchQuery` property to customize what the embed displays, along with `theme` property to toggle dark/light mode. > [accordion] View code example > > ```tsx React theme={null} > import React, { useState } from 'react'; > import { SuperblocksEmbed } from '@superblocksteam/embed-react'; > > const AppWithEmbed = () => { > const [theme, setTheme] = useState('light'); > const [searchQuery, setSearchQuery] = useState(''); > > const toggleTheme = () => { > setTheme(theme === 'light' ? 'dark' : 'light'); > }; > > const properties = { theme, searchQuery }; > > return ( >
> {/* Theme toggle button */} > > > {/* Search input */} > type="text" > placeholder="Search..." > value={searchQuery} > onChange={(e) => setSearchQuery(e.target.value)} > /> > > {/* Embedded app receives properties reactively */} > src='https://{tenant}.superblocks.com/code-mode/embed/applications/' > properties={properties} > /> >
> ); > }; > ``` > > ```js JavaScript theme={null} > let theme = 'light'; > let searchQuery = ''; > > const sbApp = Superblocks.createSuperblocksEmbed({ > id: "sb-app", > src: "https://{tenant}.superblocks.com/code-mode/embed/applications/", > properties: { theme, searchQuery }, > }); > document.body.appendChild(sbApp); > > // Toggle theme when button is clicked > document.getElementById('theme-toggle').addEventListener('click', () => { > theme = theme === 'light' ? 'dark' : 'light'; > sbApp.properties = { ...sbApp.properties, theme }; > }); > > // Update search when input changes > document.getElementById('search-input').addEventListener('input', (e) => { > searchQuery = e.target.value; > sbApp.properties = { ...sbApp.properties, searchQuery }; > }); > ``` **2. Prompt Clark to use properties in embedded app** Once you've set up properties in your host app, prompt Clark to use them in your Superblocks app. For example: > *This app will be embedded - Add support to accept a `searchQuery` property from the host app to filter the table, along with a `theme` property for toggling dark/light mode.* In the underlying code, Clark will import `useEmbedProperties` to read the specified properties and use them in the component logic (filtering, theming, etc.). > [accordion] View code example > > ```tsx App.tsx (theme) theme={null} > // Apply theme at the root level to affect the entire app > import { App as AppProvider, useEmbedProperties } from "@superblocksteam/library"; > import { Outlet } from "react-router"; > import { cn } from "./lib/utils"; > > export default function AppComponent() { > const embedProperties = useEmbedProperties(); > const theme = (embedProperties.theme as string) || "light"; > > return ( > >
> >
>
> ); > } > ``` > > ```tsx Page.tsx (searchQuery) theme={null} > // Use in individual pages for filtering > import { useEmbedProperties } from "@superblocksteam/library"; > > export default function OrdersPage() { > const embedProperties = useEmbedProperties(); > const searchQuery = (embedProperties.searchQuery as string) || ""; > > // Filter data based on searchQuery from host app > const filteredData = data.filter(item => > item.name.toLowerCase().includes(searchQuery.toLowerCase()) > ); > > return ; > } > ``` ## Events - Two-way communication Use events for bidirectional communication between the host app and embedded Superblocks app. | Direction | Description | Examples | | - | - | - | | **Embed → Host** | Notify the host application when something happens inside the embedded Superblocks app | • Notify the host when a user selects a row in a table • Report errors or validation failures to the host • Trigger navigation in the host app based on embed actions | | **Host → Embed** | Trigger actions inside the embedded Superblocks app from your host application | • Trigger a data refresh when the user clicks a button in the host app • Navigate to a specific view or record in the embedded app • Open a modal or form in the embedded app | Follow the steps below to get started working with events. ### Embed → Host **1. Add event listener in host app** Superblocks apps emit the following built-in events, which host apps can listen for: | Event Name | Handler | Description | | - | - | - | | `AppLoadedEvent` | `onAppLoaded` | Triggered when the application finishes loading and becomes interactive. | | `AuthErrorEvent` | `onAuthError` | Triggered when the user's session expires or upon login if there is an authentication error. Will also trigger if the user clicks on a link that tries to bring them to a Superblocks Application they're not allowed to access. | | `NavigationEvent` | `onNavigation` | Triggered on cross application navigation events. | To respond to these events, register the relevant callback handler above in your host app's embed component. > [accordion] View built-in event example > > ```tsx React theme={null} > import React from 'react'; > import { SuperblocksEmbed } from '@superblocksteam/embed-react'; > > const AppWithEmbed = () => { > const handleAuthError = (event) => { > console.log('User authentication with Superblocks failed'); > }; > > return ( > src='https://{tenant}.superblocks.com/code-mode/embed/applications/' > onAuthError={handleAuthError} > /> > ); > }; > ``` > > ```js JavaScript theme={null} > async function handleAuthError(event) { > console.log('User authentication with Superblocks failed'); > } > > const sbApp = document.getElementById("sb-app"); > sbApp.onAuthError = handleAuthError; > ``` For any custom events emitted by your Superblocks app (see step 2), use the `onEvent` handler to listen and respond to these in your host app. Note, the `eventName` parameter is the name of the event emitted from Superblocks. > [accordion] View custom event example > > ```tsx React theme={null} > import React from 'react'; > import { SuperblocksEmbed } from '@superblocksteam/embed-react'; > > const AppWithEmbed = () => { > const handleEvents = (eventName, payload) => { > switch (eventName) { > case 'removeCustomer': // Custom event name > console.log('Customer removed', payload.id); > } > }; > > return ( > src='https://{tenant}.superblocks.com/code-mode/embed/applications/' > onEvent={handleEvents} > /> > ); > }; > ``` > > ```js JavaScript theme={null} > // Handler for host app to respond to Superblocks events > function handleEvent(eventName, payload) { > if (eventName === "removeCustomer") { > console.log('Customer removed', payload.id); > } > } > > // Embed initialization > const sbApp = Superblocks.createSuperblocksEmbed({ > id: "sb-app", > src: "https://{tenant}.superblocks.com/code-mode/embed/applications/", > onEvent: handleEvent > }); > > document.body.appendChild(sbApp); > ``` **2. Prompt Clark to emit custom events** For built-in events (`AppLoadedEvent`, `AuthErrorEvent`, `NavigationEvent`), no additional prompting is needed—your app emits these automatically. For custom events, prompt Clark to emit events for any actions in your app. For example: * *"Emit an orderSelected event when a user clicks a table row"* * *"Send a formSubmitted event to the host when the form is saved"* * *"Notify the host with an error event if the API call fails"* Clark will import `useEmitEmbedEvent` to call the emit function at the appropriate trigger point and include relevant payload data. > [accordion] View code example > > ```tsx Superblocks App theme={null} > // Inside your Superblocks app > import { useEmitEmbedEvent } from '@superblocksteam/embed-react'; > > const OrderTable = () => { > const emitEvent = useEmitEmbedEvent(); > > const handleRowClick = (order) => { > // Emit event to the host app > emitEvent('orderSelected', { > orderId: order.id, > orderTotal: order.total, > }); > }; > > const handleFormSubmit = async (formData) => { > try { > await saveOrder(formData); > emitEvent('formSubmitted', { success: true }); > } catch (error) { > emitEvent('error', { message: error.message }); > } > }; > > return ( >
> {orders.map(order => ( > handleRowClick(order)}> > > > > ))} >
{order.id}{order.total}
> ); > }; > ``` ### Host → Embed **1. Emit event from host app** Use a ref to access the embed component and call `emit()` to send events to your Superblocks app. > [accordion] View code example > > ```tsx React theme={null} > import { SuperblocksEmbed } from '@superblocksteam/embed-react'; > import { useRef } from 'react'; > > const HostApp = () => { > const embedRef = useRef(null); > > const handleRefreshClick = () => { > // Emit event to the embedded app > embedRef.current?.emit('refreshData', { timestamp: Date.now() }); > }; > > const handleSelectOrder = (orderId) => { > embedRef.current?.emit('selectOrder', { orderId }); > }; > > return ( > <> > > > ref={embedRef} > src='https://{tenant}.superblocks.com/code-mode/embed/applications/' > /> > > ); > }; > ``` > > ```js JavaScript theme={null} > const sbApp = Superblocks.createSuperblocksEmbed({ > id: "sb-app", > src: "https://{tenant}.superblocks.com/code-mode/embed/applications/", > }); > document.body.appendChild(sbApp); > > // Emit event to the embedded app > document.getElementById('refresh-btn').addEventListener('click', () => { > sbApp.emit('refreshData', { timestamp: Date.now() }); > }); > > document.getElementById('select-btn').addEventListener('click', () => { > sbApp.emit('selectOrder', { orderId: 'order_456' }); > }); > ``` **2. Prompt Clark to listen for host events** Prompt Clark to add event listeners for any events you emit from the host app. For example: * *"Listen for a refreshData event from the host and refetch the API"* * *"When the host triggers selectOrder, highlight that row in the table"* * *"Add a listener for navigate\_to events to handle host-driven navigation"* Clark will import `useEmbedEvent`, register an event handler, and implement the action (refetch, select, navigate, etc.). > [accordion] View code example > > ```tsx Superblocks App theme={null} > // Inside your Superblocks app > import { useEmbedEvent } from '@superblocksteam/embed-react'; > > const MyComponent = () => { > const [selectedOrderId, setSelectedOrderId] = useState(null); > > // Listen for events from the host > useEmbedEvent('refreshData', (payload) => { > console.log('Refreshing data...', payload.timestamp); > // Trigger API refetch > fetchData(); > }); > > useEmbedEvent('selectOrder', (payload) => { > setSelectedOrderId(payload.orderId); > }); > > return
Selected: {selectedOrderId}
; > }; > ``` ## Working with embedded apps in the Superblocks editor Since embedded apps often rely on host app information like properties, events, and logged-in user metadata, it can be helpful to simulate these in the Superblocks editor to review the app's look and functionality independent of embedding. You can do this by prompting Clark to create a testing interface in the Superblocks editor—Clark is aware of the three modes of a Superblocks app (EDIT, PREVIEW, and PUBLISHED), so it is capable of writing conditional logic to show different components or execute different logic based on the mode of the app. For example: > *Since this app is going to be embedded, I'd like to set up a way to simulate certain functionality directly in the Superblocks editor as follows:* > > *In EDIT mode:* > > * *Show a dropdown that allows me to select / assume a role (agent or manager)* to be used in the backend API > * *Add a switch for toggling light / dark mode* > > *In PREVIEW and PUBLISHED modes:* > > * *Don't show the dropdown—instead, get the role based on the logged-in user's `metadata.role`.* > * *Don't show the toggle—instead get the mode based on a `theme` property passed from the host app* # Embedded applications Source: https://docs.superblocks.com/hosting/embedded-apps/overview Bring your app to where your users are. Accelerate time-to-market for new features while delivering a cohesive user-experience that fits your app's look and feel perfectly. ![Square application with dashboard containing Superblocks embed](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/cover.png?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=534e4f3c1c686fe8c478e8dcc6da2d75) Empower stakeholders inside and outside your organization with Embedded Apps. * **Business Leaders** get a fast way for their teams to deliver new applications to market * **CTOs** & Engineering Leaders get a cost-effective low-code solution for enhancing existing tools and portals, without the maintenance burden of legacy * **Developers** are empowered to build new features quickly for customers and internal teams without parsing through legacy code using a modern SDK * **Business users & customers** enjoy a seamless white-labeled experience with access to new features and functionality, improving satisfaction and productivity ## Embed anywhere with Superblocks SDKs Superblocks Embed SDKs make it quick and simple to embed Superblocks apps into any JavaScript enabled website. Match your app's framework with SDKs for [React](https://www.npmjs.com/package/@superblocksteam/embed-react) and [JavaScript](https://www.npmjs.com/package/@superblocksteam/embed). Simply install the SDK and copy/paste a short code snippet. ## Integrate with your existing authentication Say goodbye to multiple logins. With Superblocks Embedded Apps, users enjoy a single sign-on experience that's integrated into your app's existing authentication flow. [Learn how](/hosting/embedded-apps/authentication) to configure authentication. ![Login screen for Acme Inc parent application](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/authentication.png?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=c7e20e4e2af8fa0e6fb139627f7a084b) ## Effortless 2-way communication Build dynamic and responsive user experiences. With custom events and properties, apps respond instantly to user actions, creating engaging experiences every time. [Learn how](/hosting/embedded-apps/interactivity) to use bidirectional communication. ![Illustration of bidirectional communication between parent app and Superblocks](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/communication.jpeg?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=ef4d5fdf7ba45648ead8ec90e1b843c3) ## Securely manage permissions for any user Manage access with ease while infinitely customizing to fit your needs. Control access to features and functionality in Superblocks with your app's existing permissions system. [Learn how](/hosting/embedded-apps/authentication#manage-user-access) to manage user access. ![Code showing how to customize access with user metadata](https://mintcdn.com/superblocks/gv-69CnRrBMTuWPu/images/applications/embedding/embed-user-metadata.jpeg?fit=max\&auto=format\&n=gv-69CnRrBMTuWPu\&q=85\&s=1d3ef5b9f5400b7e7ae0a4082e798d28) ## Get started Get started with Embedded Apps with the following guides: # Embedded app quickstart Source: https://docs.superblocks.com/hosting/embedded-apps/quickstart Embedding a Superblocks application on a web page is straight-forward and only involves a few steps. ## Step 1. Create an application Before you start embedding a Superblocks app in your website, you'll need an application to embed. Learn how to build a Superblocks application in [Building with Clark](/building-with-clark). Once you have an initial version of your app ready, [**commit & deploy**](/development-lifecycle/version-control/superblocks-sdlc) your app. ## Step 2. Install the SDK Install either Superblocks' [React](https://www.npmjs.com/package/@superblocksteam/embed-react) or [Javascript](https://www.npmjs.com/package/@superblocksteam/embed) SDK into your web application's client-side code. > [tab] React > > ```bash theme={null} > npm install --save @superblocksteam/embed-react > ``` > [tab] JavaScript > > ```bash theme={null} > npm install --save @superblocksteam/embed > ``` > > Alternatively, add the following ` > ``` ## Step 3. Add the embed component Add the embed component to your HTML on the page you want the app to appear on. In the examples, replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). > [tab] React > > Get your app's `` component by clicking the **Share application** icon in the app editor's header, followed by **Setup embed** in the share modal. > > ```tsx theme={null} > import React from 'react'; > import { SuperblocksEmbed } from '@superblocksteam/embed-react'; > > const AppWithEmbed = () => { > > return <> > src='https://{tenant}.superblocks.com/code-mode/embed/applications/' > /> > ; > } > ``` > [tab] JavaScript > > Get your app's `createSuperblocksEmbed` snippet by clicking the **Share application** icon in the app editor's header, followed by **Setup embed** in the share modal. > > ```js theme={null} > const sbApp = Superblocks.createSuperblocksEmbed({ > id: "sb-app", > src: "https://{tenant}.superblocks.com/code-mode/embed/applications/" > }); > > document.body.appendChild(sbApp); > ``` ## Step 4. View your embedded app Run your web app in development mode to view and test the embedded app on your site. You've now successfully embedded your application! Customize and extend your embed's behavior by exploring the docs below. ## What's next? With a basic embedded app on your website, you're ready to [**authenticate external users**](/hosting/embedded-apps/authentication) with your Superblocks app. # Overview Source: https://docs.superblocks.com/hosting/overview Choose where and how your Superblocks applications are made available to end users. Whether you're building internal tools, embedding functionality into existing products, or deploying data applications to Databricks, Superblocks offers flexible hosting options that fit your organization's needs. ## What is hosting in Superblocks? Hosting defines how users access a Superblocks app and how their identity is established when they do. It determines: * The URL or surface where users open the app * How users authenticate and are authorized * How the app fits into your existing product or platform experience The hosting model you choose shapes the user entry point, authentication flow, and permission model, while allowing you to deliver the same app in different contexts. ## Hosting options Superblocks supports three hosting models. ### Superblocks-hosted apps Apps are accessed directly through Superblocks. Key characteristics: * Launched from the Superblocks UI or a direct app URL * Authentication and permissions managed by Superblocks * Minimal setup required to make apps available to users Best for: * Internal tools * Administrative workflows * Operational dashboards ### Embedded apps Apps are accessed from within your product or website. Key characteristics: * Launched inside an iframe or embed component * User access integrated into an existing product experience * Authentication coordinated between your app and Superblocks Best for: * Customer-facing tools * Self-service workflows * Extending SaaS products with custom functionality Learn more about [Embedded apps](/hosting/embedded-apps/overview) ### Databricks apps Apps are accessed from within a Databricks workspace. Key characteristics: * Launched as Databricks-native applications * User identity and permissions derived from Databricks * Access controlled by Databricks workspace settings Best for: * Data applications * Analytics and operational tooling * Teams building directly on Databricks Learn more about [Superblocks Apps in Databricks](/hosting/databricks-apps/overview) ## **Choosing a hosting option** | **Hosting option** | **Primary advantage** | **Authentication** | **Integration effort** | **Best use case** | | :- | :- | :- | :- | :- | | **Superblocks-managed** | Fastest deployment with no infrastructure | Superblocks SSO (Okta, Entra, Google, etc.) | None | Internal tools and dashboards | | **Embedded apps** | Runs inside existing applications | Custom (provided by parent app) | Medium | SaaS products and customer portals | | **Databricks apps** | Native Databricks workspace experience | Databricks authentication | Low | Databricks-centric data applications | As a general guideline: * Use **Superblocks-managed hosting** for most internal applications * Use **Embedded apps** when Superblocks must run inside an existing product or portal * Use **Databricks apps** when users primarily work in Databricks and expect applications to live there # App AI Source: https://docs.superblocks.com/integrations/app-ai Set the default AI provider for all AI-powered features inside the apps your builders create ## Overview Builders use AI across every type of app they create. For example, drafting justifications for approval workflows, summarizing support tickets, generating images for product catalogs, transcribing call recordings, classifying inbound requests, and more. App AI lets administrators set the provider and model that powers all of these features across the entire organization, so builders get instant access without configuring anything themselves. This is separate from [Clark's inference](/admin/superblocks-on-aws/inference), which controls the AI that **Clark** uses to build apps during development. App AI controls where **apps** run inference when end users interact with AI-powered features in production. | Setting | Controls | Who is affected | | - | - | - | | **Inference** | Clark's inference during app development | Builders prompting Clark | | **App AI** | Runtime AI inside deployed apps | End users of published apps | ## Supported AI integrations App AI can route each modality through any of your connected AI integrations. Connect one in the [Integrations library](/integrations/integrations-library/index), then select it as the default provider for a modality. ## How it works ### 1. Admin sets the default provider In **Organization Settings**, an administrator configures the AI integration and model that all apps should use by default. This includes the provider endpoint and authentication credentials. ### 2. Configure per modality Administrators can select a different integration and model for each AI modality: | Modality | Example use cases | | - | - | | **Text generation** | Drafting content, summarization, classification, chat | | **Voice** | Transcription, text-to-speech | | **Image generation** | Creating visuals, diagrams, thumbnails | This lets you optimize for cost and capability - for example, routing text generation through a cost-efficient model on your AI gateway while using a specialized provider for image generation. You can also connect to your own custom AI gateway for centralized policy and model management. ### 3. Builders get AI capabilities automatically When a builder adds an AI-powered feature to their app — for example, a "Generate with AI" button that drafts a rationale or summarizes data — the feature automatically uses the organization's default for that modality. The builder does not need to select a model or configure credentials. ### 4. End users trigger inference at runtime When an end user clicks a button or triggers a feature that calls the AI provider, the request goes directly to the configured provider. For example, if the text generation default is set to Amazon Bedrock running Claude, every text AI interaction in every published app routes through Bedrock. ## What this means for your organization * **One configuration, every app**: Set the provider once per modality and every AI-powered feature across all apps inherits it * **Cost control per modality**: Choose cost-efficient models for high-volume text generation and specialized models for image or voice * **Builders stay focused**: No need for individual builders to manage API keys or select models * **Inference on your terms**: Runtime AI calls go to your provider, burning down your existing commitment * **Consistent governance**: All AI features in all apps are routed through governed endpoints you control # API authentication types Source: https://docs.superblocks.com/integrations/auth/authentication-types Superblocks supports several types of authentication methods for APIs. Select a type from the **Authentication** dropdown in your integration's configuration page. ## None Superblocks won't send authentication details with a request unless you select an authentication method. If your request doesn't require authentication, set the **Authentication** dropdown to **None**. ## Basic authentication Basic authentication involves sending a verified username and password with your request. On the integration configuration page, set **Authentication** to **Basic Authentication**. Check **Share username/password across all users** and enter your API username and password, or uncheck this option to have end users provide their own credentials. ![A prompt to the user to log in with their username and password for basic authentication](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/login.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=2a02192e2f8d30aed9ef9548bd84d191) If end users are providing their credentials, they will be stored as an HTTP-Only Secure cookie in the user's browser and sent to the Superblocks Agent. The Superblocks Agent sends your API a **Header** containing a Base64 encoded string representing your username and password values, appended to the text `Basic` as follows: ``` Basic ``` ## API key **API Key** authentication sends a key-value pair to the API either as a request header or query parameter. To authenticate using an API key, set the **Authentication** dropdown to **API key** in your integration configuration. Enter your key name and value, and select either **Header** or **Query parameter** from the **Add to** dropdown list. Superblocks will append the relevant information to your request headers or the URL query string. ![API key authentication for REST and GraphQL APIs](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/api-key.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=549d2866e39bf44540600ae4d7e1fa58) ## Bearer token Bearer tokens enable requests to authenticate using an access key, such as a JSON Web Token (JWT). The token is a text string included in the request header. On the integration configuration page, set **Authentication** to **Bearer Token** to use this auth method. In the **Token** field, enter your token value. The Superblocks Agent will append the token value to the text `Bearer` in the required format to the request Authorization header as follows: ``` Bearer ``` ## OAuth 2.0 Superblocks supports multiple OAuth 2.0 flows. For a full list of supported OAuth 2.0 flows and how to use them see the [OAuth 2.0](/integrations/auth/oauth-20) docs. ## Firebase Learn more about [Firebase authentication](/integrations/auth/firebase) for [REST APIs](/integrations/integrations-library/rest-api). # Connect to AWS services with IAM roles Source: https://docs.superblocks.com/integrations/auth/aws-iam Connecting by assuming an IAM role is only available when using Superblocks [Hybrid or Cloud-Prem architectures](/enterprise/deployment-overview) When running the Superblocks data plane on AWS ([ECS Fargate](/enterprise/hybrid-architecture/deployment/aws_ecs_fargate), [EKS](/enterprise/hybrid-architecture/deployment/kubernetes), or [EC2 instances](/enterprise/hybrid-architecture/deployment/virtual_machine)), the container can access AWS services with an [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), instead of requiring long-term access keys. This can be used in: * Superblocks integrations like [DynamoDB](/integrations/integrations-library/aws-dynamodb) and [S3](/integrations/integrations-library/aws-s3) * Backend API steps using the Python [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) library or JavaScript [AWS SDK](https://www.npmjs.com/package/aws-sdk) ## Auth types ### ECS task role Assign an IAM role to the agent's ECS task. If using the Superblocks Terraform module, this can be set via the `superblocks_agent_role_arn` [variable](https://github.com/superblocksteam/terraform-aws-superblocks/blob/c86beb31f119538dd9d1e97ae2ad72d0ea70a458/examples/complete/main.tf#L33). ``` superblocks_agent_role_arn = "arn:aws:iam::111111111111:role/my-iam-role" ``` Once this is set up, create AWS integrations with only the region specified (leave the default auth type set to **Access Key**, though this will not be used). The agent will use its assigned role to retrieve temporary credentials when APIs are executed. ![s3 integration using iam role with data plane on ECS](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/opa_iam_role_s3.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=db4f817129fb90a75624f5a6de523c59) ### Kubernetes service account Follow the steps in the EKS docs on [IAM roles for service accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to associate an IAM role with a Kubernetes service account. Specify this service account in the agent's Helm chart `values.yaml` file, along with the annotation for the IAM role. ```yaml theme={null} #(...) serviceAccount: name: data-plane-service-account annotations: eks.amazonaws.com/role-arn: arn:aws:iam::111111111111:role/my-iam-role #(...) ``` Once this is set up, create AWS integrations with the **Token File** auth type. This will authorize the agent to connect to the AWS service using Service Account Token Volume Projection. ![s3 integration using iam role with data plane on EKS](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/authentication/opa_irsa_s3.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=af8dfa59da2d9705204c6d76f0afeddd) ### EC2 instance metadata Create an IAM role that allows EC2 instances to call AWS services and associate this role with the EC2 instance where the Superblocks agent runs (IAM instance profile). Once this is set up, create AWS integrations with the **EC2 Instance Metadata** auth type. This will authorize the agent to connect to the AWS service using the instance's IAM role credentials, retrieved through the EC2 instance metadata endpoint ([IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html)). ![s3 integration using iam role with data plane on EC2](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/opa_iam_ec2_instance_s3.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=f0207daae7ab18d05301d6c48cfe4cff) ## Connect to AWS in Python and JavaScript The agent can also use IAM roles to connect to AWS services in backend Python ([Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)) and JavaScript ([AWS SDK](https://www.npmjs.com/package/aws-sdk)) steps. If you're using [ECS task role auth](#ecs-task-role), you must additionally set the environment variable `SB_EXECUTION_ENV_INCLUSION_LIST` to a value of `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI`. For example, in the agent's Terraform module: ``` superblocks_agent_environment_variables = [ { "name" : "SB_EXECUTION_ENV_INCLUSION_LIST", "value" : "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI" } ] ``` No additional configuration is required if your agent is using a [Kubernetes service account](#kubernetes-service-account) or [EC2 instance metadata](#ec2-instance-metadata) for IAM role auth. You can then write code in Superblocks to interact with AWS services that the agent's role has permission to access. ![iam role auth for boto3](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/authentication/python_boto3.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=591a3a7aec1ac0cc7c72d47db2c119c4) # Credentials and session management Source: https://docs.superblocks.com/integrations/auth/credential-and-session-management ## Integration credentials Superblocks offers several ways of setting credentials to use when connecting to integrations. This method balances ease of use and security by allowing you to decide how your credentials are stored and managed. * **Enter value directly**: You can enter credentials directly into integration configuration forms. Credentials entered this way are stored securely by Superblocks Cloud and only retrieved by the Superblocks Agent when it needs to connect to your data sources. * **Reference secret**: Using [Secrets Management](/admin/secrets-management) you can reference secrets in connected secret stores using the `sb_secrets` object. When the Superblocks Agent needs to connect to your data source, it will fetch secrets values from the connected secret manager or from cached secrets. This option makes it easy to centrally manage all of your secrets using Superblocks. * **Data plane environment variables**: Customers self-hosting the Superblocks data plane can configure [environment variables](/enterprise/hybrid-architecture/extend/storing-environment-variables) and reference them in integration configuration forms using the `Env` object. This approach lets you easily manage and updated environment credentials through your usual infra deployment process, however does require restarting the service to update secrets. * **Custom workflow (fetch credentials dynamically)**: For ultimate flexibility, run custom workflows to dynamically fetch credentials for your integration. When using this approach you'll create a workflow to fetch your integration credentials. When the Superblocks Agent needs to connect to your data source, it will first execute this workflow, then use the returned credentials to connect. ## Session management Superblocks simplifies the process of managing API sessions by handling token caching and refresh for you. We also provide various ways to log users out of integration and revoke session tokens, both centrally for all users of your Integration or in code. ### Credential/Token caching Many API authentication methods in Superblocks either collect credentials from your application end-users or fetch short lived access tokens from an authorization server. To improve the user experience and API performance, credentials and non-expired tokens are cached for future use. Credentials or tokens are cached either client-side or server-side, depending on the auth method. #### Client-side caching Credentials cached client-side are stored in HTTP-Only Secure cookies in the user's browser. These cookies are not accessible to JavaScript and are only used to forward the credentials to the Superblocks Agent when executing APIs. Credentials are only cached client-side if an auth flow already exposes the credentials/token to the client. Authorization methods that use client-side caching include: * [Basic authentication](/integrations/auth/authentication-types#basic-authentication) * [OAuth 2.0 - Implicit](/integrations/auth/oauth-20#implicit) * [OAuth 2.0 - Password Grant (Legacy)](/integrations/auth/oauth-20#password-grant-legacy) when end-users are prompted for their credentials * [Firebase authentication](/integrations/auth/firebase) #### Server-side caching OAuth 2.0 flows result in a short-lived access token being issued to Superblocks. Access tokens issued as a part of these flows are cached in Superblocks Cloud. These tokens are never directly exposed to end-users by instead accessed behind the scenes by the Superblockcs Agent when required for authorization. Authorization methods that use server-side caching include: * [OAuth 2.0 - Authorization Code Flow](/integrations/auth/oauth-20#authorization-code) * [OAuth 2.0 - On-Behalf-Of Token Exchange Flow](/integrations/auth/oauth-20#on-behalf-of-token-exchange) * [OAuth 2.0 - Client Credential Flow](/integrations/auth/oauth-20#client-credential) * [OAuth 2.0 - Password Grant (Legacy) Flow](/integrations/auth/oauth-20#password-grant-legacy) when using a shared username/password Learn more about [OAuth 2.0 Token Caching](/integrations/auth/oauth-20#token-caching-and-refresh) ### Ending sessions From time to time you may find it necessary to clear cached credentials or access tokens. Sessions are ended and cached credentials are cleared when: * **The integration is updated**: When an integration configuration is edited in a way that makes the currently cached credentials invalid, Superblocks will automatically clear cached credentials. For example, if the Authorization/Token URL, Audience, or Scopes of an OAuth 2.0 client changes. * **Clicking Revoke token**: You can clear the cached tokens for all users logged into an integration by clicking the **Revoke token** button in the Integration configuration. # Database connections Source: https://docs.superblocks.com/integrations/auth/database-connections/index Superblocks facilitates seamless integrations with popular databases so you team can easily access and build tools right on top of your company's data. By leveraging various authentication methods and network settings, you can centrally manage how developers connect to your data ensuring reliable access and secure access to data. ## Connection method When connecting to databases in Superblocks, you will typically have two options: ### Connection form This method lets you connect by filling out a simple form with your database credentials. This user-friendly interface is designed for ease of use, enabling you to connect to your database quickly without needing extensive technical knowledge. Connection forms usually limit you to connecting via `username/password` authentication. If you need to connect using a more advanced authentication method provided by your database, you may want to explore using a [connection string](#connection-string). ### Connection string Alternatively, you can connect using a connection string, which lets you enter an arbitrary connection URI. This method provides greater flexibility, letting you specify additional parameters, making it suitable for advanced configurations or custom setups. The format required for the connection string and options available varies by database. The following databases support connection strings and have the following expected forms. | Database | String format | Docs | | - | - | - | | Amazon Redshift | `redshift://[:username]:[:password]@[:host]:[:port]/[:database]` | [Docs](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-build-connection-url.html) **Note**: Exclude the `jdbc` prefix from the connection string | | CockroachDB | `postgres://:@:/?` | [Docs](https://www.cockroachlabs.com/docs/v24.1/connection-parameters#connect-using-a-url) | | MariaDB | `mariadb://[[:]@][:]/[[?=[&=]]]` | [Docs](https://github.com/mariadb-corporation/mariadb-connector-nodejs/blob/master/documentation/connection-options.md) | | Microsoft SQL | `Server=[:serverName],[:port];Database=[:database];User Id=[user];Password=[:password];Encrypt=[true/false]` | [Docs](https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/connection-string-syntax) | | MongoDB | `mongodb+srv://:@/?retryWrites=true&w=majority` | [Docs](https://www.mongodb.com/docs/manual/reference/connection-string/) | | MySQL | `mysql://[:username]:[:password]@[:host]:[:port]/[:database]` | [Docs](https://dev.mysql.com/doc/refman/8.4/en/connecting-using-uri-or-key-value-pairs.html) | | PostgreSQL | `postgres://[:user]:[:password]@[:host]:[:port]/[:database]` | [Docs](https://github.com/brianc/node-postgres/tree/master/packages/pg-connection-string) | | Redis | `redis://[:password@]host[:port][/db-number]` | [Docs](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md) | ## Networking For Superblocks to connect to your database the Superblocks Agent will need network access. If your database is available on public subnets or allows any IP to connect, you should have no problems. For security purposes, many databases are configured to limit who can connect to them. In this case, you'll need to configure you database to accept inbound traffic from the Superblocks Agent. ### IP allowlist To let Superblocks Cloud connect to your database, update your database's ingress allowlist to include the following: > [tab] US Region > > * **NAT hostname**: `nat.superblocks.com` > * **Current DNS**: [A Records](https://dnsjson.com/nat.superblocks.com/A.json) > * **Last recorded IPs**: > > ``` > 100.24.157.155 > 34.200.73.233 > 34.209.17.50 > 35.155.119.178 > 35.86.18.137 > 44.232.244.93 > 54.211.180.182 > 54.243.113.90 > ``` > [tab] EU Region > > * **NAT hostname**: `nat.eu.superblocks.com` > * **Current DNS**: [A Records](https://dnsjson.com/nat.eu.superblocks.com/A.json) > * **Last recorded IPs**: > > ``` > 13.50.50.66 > 13.50.81.30 > 13.51.231.18 > 52.17.136.219 > 54.220.65.107 > 99.81.159.1 > ``` ### In-network Agent Alternatively, you can access in-network resources by deploying the [Superblocks data plane](/enterprise/hybrid-architecture/overview) inside the same network as your database. The data plane service will execute your APIs and connect directly to your databases, ensuring all your data is kept securely within your corporate firewall. ## Network settings ### SSL configuration Superblocks supports the ability to establish connections using Secure Socket Layer (SSL), a protocol for creating authenticated and encrypted links between networked computers. #### Configuring SSL SSL can be configured using the Integration configuration form for [supported integrations](#support-by-integration). ![SSL Certificate Authentication From](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/authentication/ssl_certificates.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=0dad32a757bde7fdab2322b19fe9c9a2) 1. On the Integration configuration form for your DB, select **Enable SSL** 2. Optionally, select **Use a self-signed SSL certificate**. If selected, provide the following: * **Server CA**: Database server's Certificate Authority (CA) certificate * **Client key**: Client's private key * **Client cert**: Client's public key certificate ### SSH configuration SSH Tunneling is only available when using **Superblocks Cloud** Sometimes databases can't be accessed directly and require SSH tunneling to access. SSH or Secure Shell is a network communication protocol that allows two computers to communicate and encrypts shared data, letting you connect to DBs on private subnets securely from Superblocks Cloud. #### SSH authentication methods Superblocks supports the following SSH Authentication methods: * Username/password * Private key authentication * Public key authentication (RSA or Ed25519) #### Configuring SSH tunnels SSH tunneling can be configured using the Integration configuration form for [supported integrations](#support-by-integration). ![SSH Tunneling Configuration Form](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/authentication/ssh_tunnel.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=c4b27d069f0d25c26f931ea7e5062854) 1. Configure your SSH server to allow connections from [Superblocks's IPs](#ip-allowlist) 2. On the Integration configuration form for you DB, select **Use SSH Tunnel** 3. Select an **Authentication method** 4. Specify the following shared configuration values: * **Bastion host**: The name or IP address of the SSH server * **Bastion port**: The port number used for the SSH connection * **Bastion username**: The username required for SSH authentication 5. Follow instructions based on the selected **Authentication method** > [tab] Password > > Enter the following configuration values: > > * **Password**: The SSH account password for the **Bastion user** > [tab] Private key > > Enter the following configuration values: > > * **Public key**: The public key of your SSH server's public/private key pair > * **Private key**: The private key of your SSH server's public/private key > [tab] Public key (RSA or Ed25519) > > Copy the Superblocks provided **Public key** to your SSH server's `~/.ssh/authorized_keys` file ### Support by Integration The following network settings are supported by each database integration. | Integration | SSL | SSL Certificate | SSH Tunneling | | - | - | - | - | | [Amazon Redshift](/integrations/integrations-library/aws-redshift) | ✓ | ✗ | ✗ | | [CockroachDB](/integrations/integrations-library/cockroachdb) | ✓ | ✓ | ✗ | | [MariaDB](/integrations/integrations-library/mariadb) | ✓ | ✓ | ✗ | | [Microsoft SQL Server](/integrations/integrations-library/mssql) | ✓ | ✗ | ✗ | | [MongoDB](/integrations/integrations-library/mongodb) | ✓ | ✓ | ✗ | | [MySQL](/integrations/integrations-library/mysql) | ✓ | ✓ | ✓ | | [Postgres](/integrations/integrations-library/postgres) | ✓ | ✓ | ✓ | # Firebase authentication Source: https://docs.superblocks.com/integrations/auth/firebase Firebase authentication is a service for securely signing users into applications. It supports authentication using passwords, phone numbers, popular federated identity providers like Google, Facebook, Twitter, and more. Use the Firebase authentication method to quickly integrate with your existing Firebase user base and manage access to Firebase functions without complex custom authentication setups. The official Firebase auth documentation provides more detail: * [Firebase authentication](https://firebase.google.com/docs/auth) ## Using Firebase authentication Since a user must log in when using Firebase auth, integrations that use this auth method can't be used in Workflows or Scheduled Jobs Use the following instructions to set up Firebase authentication. ### Get Firebase auth config 1. Navigate to your project in the [Firebase console](https://console.firebase.google.com) 2. In the console, go to the **Authentication** section 3. Click on the **Settings** tab followed by **Authorized domains** 4. Click **Add domain** and add your instance's domain, `{tenant}.superblocks.com`. Replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls) ![Add Superblocks to authorized domains](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/firebase-domains.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=92cf609804e09813f7f340904bb97164) 5. From the **Project overview** page, click **Add app** and select **Web** as your app's platform ![Create a new Firebase web application](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/firebase-addapp.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=7de1097e07de851de00924ab27f57ad9) 6. Name your new web app and click **Register app** 7. Copy the `firebaseConfig` object in the SDK code snippet. Make sure you **don't** copy the semicolon at the end of the line ![Copy SDK config firebaseConfig](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/firebase-sdkconfig.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=b28dc6e16ed76901d95394d5e011a7f1) ### Configure Integration 1. In the web app, navigate to the [Integrations](https://app.superblocks.com/integrations) page 2. Click into an existing REST integration, or create a new one 3. Select **Firebase** in the **Authentication method** dropdown 4. Paste the `firebaseConfig` object you copied previously into the **API config** field 5. Choose the sign-in methods you want to support 6. Use the [`firebase` object](#the-firebase-object) in **Headers** or **Params** to define how the firebase token will be used when calling your API. For example, to send the access token as an Authorization header, set: ![firebase.token referenced in Authorization header](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/firebase-object-reference.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=65033846d4335e012d206176ef1e258e) Authentication with Firebase will be initiated in the user's browser when an API using this integration executes. ## The **`firebase`** object The results of a Firebase exchange can be referenced in your integration configuration using the `firebase` object. The `firebase` object has the following properties. | Property | Datatype | Description | Full Path | | - | - | - | - | | `token` | `STRING` | The access token returned by the OAuth flow | `firebase.token` | ## Token caching and refresh This section includes specifics on how Firebase access tokens are handled. For more information on sessions management see our guide on [Credential & Session Management](/integrations/auth/credential-and-session-management) ### Cache location After your Firebase authentication flow returns an access token, it is saved as an HTTP-Only Secure cookie in the user's browser. The token is cached in the browser since it is already exposed to the browser as a part of the authentication flow. The cookie cannot be accessed using JavaScript so is safe from exfiltration. ### Refreshing access tokens Superblocks Firebase authentication does not support token refresh. Once the user's access token has expired, Superblocks will reprompt the user to log in. # Azure managed identity authentication to SQL Server Source: https://docs.superblocks.com/integrations/auth/guides/azure-msi-sql-server Connect the Superblocks On-Premise Agent on Azure Container Apps to SQL Server on an Azure VM using a user-assigned managed identity. This guide applies to the Superblocks [Hybrid or Cloud-Prem (On-Premise Agent)](/enterprise/deployment-overview) deployment on Azure Container Apps connecting to SQL Server on an Azure VM. It does not apply to Superblocks Cloud executing queries from Superblocks-hosted infrastructure. ## Overview This document describes how to connect a Superblocks On-Premise Agent (OPA) running on **Azure Container Apps (ACA)** to **SQL Server on an Azure VM** using a **user-assigned managed identity**, without storing database credentials in Superblocks. ### Authentication flow 1. The OPA container has a **user-assigned managed identity** attached. 2. When a query runs, the OPA obtains an access token from Azure’s managed identity endpoint, scoped for **SQL Server**. 3. The token is supplied to the MSSQL connector via the **connection string** (no SQL username or password). 4. SQL Server validates the token using its own **system-assigned** identity to call **Microsoft Graph**. 5. Access succeeds because the managed identity is provisioned as a **database user** in SQL Server. ### What you will configure * **Steps 1–4**: One-time setup per SQL Server VM (identity, Graph permissions, Entra auth on the SQL VM resource, database user). * **Steps 5–7**: Azure Container App running the OPA (attach identity, `identitySettings`, execution environment allowlist). * **Step 8**: MSSQL datasource in Superblocks using the connection string. ## Prerequisites ### Access and permissions * [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) installed and signed in (`az login`). * **Owner** or **Contributor** on the subscription or resource group that contains the container app. * A **Global Administrator** in Microsoft Entra ID available to grant Microsoft Graph permissions ([Step 2](#step-2-grant-microsoft-graph-permissions)). ### Azure resources * A running **SQL Server VM** with **TCP 1433** allowed in the network security group (and any internal firewall rules). * A Superblocks **OPA** deployed as an **Azure Container App**. * A **user-assigned managed identity** in Azure (use **one identity per SQL Server** if you want separate identities per server). ### Tools | Tool | Notes | | - | - | | [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) (`az`) | Required for Container Apps and identity commands | | [`sqlcmd`](https://learn.microsoft.com/en-us/sql/tools/sqlcmd-utility) | Install per OS; see [Step 4](#step-4-provision-the-managed-identity-as-a-database-user) | | PowerShell with [Microsoft Graph PowerShell SDK](https://learn.microsoft.com/en-us/powershell/microsoftgraph/get-started) | Required for Step 2 (Global Admin) | ## Part 1: Setup steps ### Step 1: Enable system-assigned managed identity on the SQL VM SQL Server needs its **own** identity to call Microsoft Graph when validating incoming Microsoft Entra tokens. This is **separate** from the user-assigned identity used by the OPA. 1. In the [Azure portal](https://portal.azure.com), open the **virtual machine** resource that runs SQL Server (not the **SQL virtual machine** blade only—use the VM resource). 2. Go to **Security** → **Identity**. 3. Open the **System assigned** tab. 4. Set **Status** to **On** and save. ### Step 2: Grant Microsoft Graph permissions Both the VM’s **system-assigned** identity and the OPA’s **user-assigned** identity need permission to query Microsoft Graph so SQL Server can resolve and validate Entra principals. A **Global Administrator** should run the following PowerShell **twice**: once with the VM system-assigned identity’s **object (principal) ID**, and once with the OPA user-assigned identity’s **principal ID**. **Find principal IDs** * **VM (system assigned)**: VM resource → **Security** → **Identity** → **System assigned** → copy **Object (principal) ID**. * **User-assigned identity**:\ `az identity show --name --resource-group --query principalId -o tsv` ```powershell theme={null} Connect-MgGraph -Scopes "AppRoleAssignment.ReadWrite.All","Application.Read.All" $principalId = "" $graph = Get-MgServicePrincipal -Filter "appId eq '00000003-0000-0000-c000-000000000000'" $roles = @("User.Read.All", "GroupMember.Read.All", "Application.Read.All") foreach ($role in $roles) { $roleId = ($graph.AppRoles | Where-Object {$_.Value -eq $role}).Id New-MgServicePrincipalAppRoleAssignment ` -ServicePrincipalId $principalId ` -PrincipalId $principalId ` -ResourceId $graph.Id ` -AppRoleId $roleId } ``` If the Global Admin cannot find the managed identity under **Enterprise applications** by name, search by **principal ID**. Set the **Application type** filter to **All applications**. This workflow is the supported alternative when **Directory Readers** cannot be assigned directly; see [Troubleshooting](#directory-readers-role-cannot-be-assigned). ### Step 3: Configure Microsoft Entra authentication on the SQL VM This enables SQL Server to accept Microsoft Entra tokens and selects which managed identity SQL uses when validating them. 1. In the Azure portal, open the **SQL virtual machine** resource (the SQL VM **resource**, not only the generic VM blade). 2. Go to **Security** → **Security configuration**. 3. Under **Microsoft Entra authentication**, select **Enable**. 4. Set **Managed identity type** to **User-assigned managed identity**. 5. Select the OPA’s **user-assigned** identity from the dropdown. 6. Click **Apply**. If the portal warns that the identity lacks permissions, Graph assignments from Step 2 may not have replicated yet. Wait a few minutes, refresh, and try **Apply** again. ### Step 4: Provision the managed identity as a database user Install `sqlcmd` on the machine you will use to run the script: * **macOS**: `brew install sqlcmd` * **Windows**: Download and install from Microsoft’s [sqlcmd utility](https://learn.microsoft.com/en-us/sql/tools/sqlcmd-utility) documentation. * **Linux**: Follow [Install the SQL Server command-line tools on Linux](https://learn.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools). Then connect as a SQL administrator and create the Entra principal as a user, then grant roles (adjust roles to your least-privilege needs): ```bash theme={null} sqlcmd -S -U -P '' \ -Q "USE ; CREATE USER [] FROM EXTERNAL PROVIDER; ALTER ROLE db_datareader ADD MEMBER []; ALTER ROLE db_datawriter ADD MEMBER [];" ``` `CREATE USER ... FROM EXTERNAL PROVIDER` maps the Entra identity to a database user so token-based logins are allowed. ### Step 5: Attach the managed identity to the OPA container app **Portal** 1. Open the **Container App** → **Settings** → **Identity** → **User assigned**. 2. Select **+ Add**, choose the managed identity, and confirm. **Azure CLI** ```bash theme={null} az containerapp update --name \ --resource-group \ --user-assigned /subscriptions//resourcegroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/ ``` ### Step 6: Register the identity with `identitySettings` (CLI) On Azure Container Apps **Consumption** plan, attaching a user-assigned identity to the app is not enough: until you apply this configuration, the managed identity sidecar **will not** inject `IDENTITY_ENDPOINT` and `IDENTITY_HEADER` into the workload container, so the OPA cannot acquire tokens. Use API version **`2026-01-01`** (earlier API versions may not support `identitySettings`). **`az rest` syntax depends on your shell.** Bash on macOS and Linux supports line continuation with a trailing backslash (`\`). **PowerShell** and **Command Prompt** on Windows do not use that pattern for Azure CLI—run the command on **one line**, still with the JSON body wrapped in **single quotes** as shown below. **macOS / Linux (bash)** — line continuation with `\`, single-quoted `--body`: ```bash theme={null} az rest --method PATCH \ --url "https://management.azure.com/subscriptions//resourceGroups//providers/Microsoft.App/containerApps/?api-version=2026-01-01" \ --body '{"properties":{"configuration":{"identitySettings":[{"identity":"","lifecycle":"All"}]}}}' ``` **Windows (PowerShell or Command Prompt)** — single line, single-quoted `--body`: ```text theme={null} az rest --method PATCH --url "https://management.azure.com/subscriptions//resourceGroups//providers/Microsoft.App/containerApps/?api-version=2026-01-01" --body '{"properties":{"configuration":{"identitySettings":[{"identity":"","lifecycle":"All"}]}}}' ``` `` is the full resource ID, for example: `/subscriptions//resourcegroups//providers/Microsoft.ManagedIdentity/userAssignedIdentities/` The PATCH **replaces** the entire `identitySettings` array. If the container app has **multiple** user-assigned identities, include **every** identity in the array each time you run this command. Verify: ```bash theme={null} az containerapp show --name --resource-group --query "properties.configuration.identitySettings" ``` You should see an entry similar to: ```json theme={null} [ { "identity": "/subscriptions/.../userAssignedIdentities/", "lifecycle": "All" } ] ``` ### Step 7: Update `SUPERBLOCKS_EXECUTION_ENV_INCLUSION_LIST` By default the OPA image allows a fixed set of environment variables into worker execution contexts (see the agent image defaults). Azure MSI variables **`IDENTITY_ENDPOINT`** and **`IDENTITY_HEADER`** must be **explicitly allowlisted** so the OPA process can read them. Append them to the existing comma-separated list **without removing** AWS variables if you still use AWS integrations from the same agent: ```bash theme={null} az containerapp update --name \ --resource-group \ --set-env-vars "SUPERBLOCKS_EXECUTION_ENV_INCLUSION_LIST=AWS_DEFAULT_REGION,AWS_ROLE_ARN,AWS_WEB_IDENTITY_TOKEN_FILE,AWS_REGION,IDENTITY_ENDPOINT,IDENTITY_HEADER" ``` Some deployments also honor `SB_EXECUTION_ENV_INCLUSION_LIST` as an alias when wiring workers. Use the variable names your Terraform or platform team standardizes on; the OPA Dockerfile default is `SUPERBLOCKS_EXECUTION_ENV_INCLUSION_LIST`. Restart the container app so replicas pick up changes: 1. **Azure portal** → Container App → **Application** → **Revisions and replicas**. 2. **Stop** the active revision, then **Start** it (or use your standard revision rollout process). ### Step 8: Create the datasource in Superblocks Create an [Microsoft SQL Server](/integrations/integrations-library/mssql) integration using a **connection string** with this shape: ``` Server=,1433;Database=;Authentication=Active Directory Integrated;Client Id= ``` * **`Client Id`** is the managed identity’s **client (application) ID**, not the object/principal ID: ```bash theme={null} az identity show --name --resource-group --query clientId -o tsv ``` ## Part 2: Adding more SQL servers For each additional SQL Server (and optional **separate** user-assigned identity per server): 1. Repeat **Steps 1–4** for that server and identity. 2. Attach the new identity to the same Container App (**User assigned** → **+ Add**). 3. Re-run the **Step 6** `identitySettings` PATCH with **all** identities in the array (not only the new one). 4. Restart the container app. 5. Create a new Superblocks MSSQL datasource with a connection string that uses that identity’s **Client Id**. ## Part 3: Common errors and troubleshooting ### `Login failed for user ''` The connection reached SQL Server but authentication failed. Most often the managed identity is **not** created as a user in the **target database**. Fix (run as admin): ```sql theme={null} USE ; CREATE USER [] FROM EXTERNAL PROVIDER; ALTER ROLE db_datareader ADD MEMBER []; ALTER ROLE db_datawriter ADD MEMBER []; ``` ### `Connection failure: (code undefined) (code undefined)` Usually a **malformed** connection string or an **unsupported** parameter before authentication runs. Confirm the string matches [Step 8](#step-8-create-the-datasource-in-superblocks). Check Container App logs: ```bash theme={null} az containerapp logs show --name --resource-group --follow ``` ### `ManagedIdentityCredential authentication unavailable` The OPA cannot reach the MSI endpoint. Typical causes: * **`identitySettings`** was never applied or was cleared — re-run [Step 6](#step-6-register-the-identity-with-identitysettings-cli) and verify with `az containerapp show ... --query "properties.configuration.identitySettings"`. * **`SUPERBLOCKS_EXECUTION_ENV_INCLUSION_LIST`** omits **`IDENTITY_ENDPOINT`** and **`IDENTITY_HEADER`** — fix [Step 7](#step-7-update-superblocksexecutionenvinclusionlist), then restart. ### `Unknown properties identitySettings in ContainerAppContainer` The REST body targeted the wrong path. Use **`properties.configuration.identitySettings`**, not `properties.template.containers[].identitySettings`: ```json theme={null} {"properties":{"configuration":{"identitySettings":[{"identity":"","lifecycle":"All"}]}}} ``` ### `identitySettings` PATCH removed other identities Each PATCH **replaces** the full array. Always send **every** managed identity: ```json theme={null} {"properties":{"configuration":{"identitySettings":[ {"identity":"","lifecycle":"All"}, {"identity":"","lifecycle":"All"} ]}}} ``` ### Security configuration page is grayed out / SQL VM shows **Offline** The **SQL IaaS extension** may still be initializing. After the VM is **Running**, wait **10–20 minutes**, refresh the **SQL virtual machine** resource until status is healthy. ### Directory Readers role cannot be assigned Assigning **Directory Readers** in Entra ID requires **Privileged Role Administrator** or **Global Administrator**. If that is not available, use the **Microsoft Graph application roles** approach in [Step 2](#step-2-grant-microsoft-graph-permissions) for **both** the VM system-assigned identity and the OPA user-assigned identity. ## Related documentation * [Database connections](/integrations/auth/database-connections/index) — networking and connection strings * [Microsoft SQL Server integration](/integrations/integrations-library/mssql) — Superblocks UI setup * [AWS IAM with the agent](/integrations/auth/aws-iam) — execution environment allowlist pattern for cloud workloads # Configure IP allowlist for databases Source: https://docs.superblocks.com/integrations/auth/guides/configure-ip-allowlist-for-databases This guide explains how to allow Superblocks to connect to databases on AWS and GCP ## Amazon Web Services (AWS) * Log in to the [AWS Console](https://aws.amazon.com/console/) * Navigate to the resource that you would like Superblocks to connect to * If you are applying an allowlist to an RDS instance, the instance must be set to `Publicly accessible` (this is found under **Connectivity -> Additional configuration**) ![Ensure your RDS instance is publicly accessible](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/allowlist-aws-publicly-accessible.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=4907d9b4e771bded900dcff27a1c8853) * Select an existing Security Group or create a new one * Select the **Inbound rules** tab at the bottom and click **Edit inbound rules** ![Update inbound rules to ensure that Superblocks IP addresses are allowed](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/allowlist-inbound-rules.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=ef689f5d3237efb10d378bc856dce007) * Choose the port (defaults: Postgres: 5432, MySQL: 3306, MSSQL: 1433) * Set **Source** to "Custom" and enter the following IP addresses: \ `100.24.157.155/32, 34.200.73.233/32, 34.209.17.50/32, 35.155.119.178/32, 35.86.18.137/32, 44.232.244.93/32, 54.211.180.182/32, 54.243.113.90/32` ![Add Superblocks IP addresses to the allow list](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/allowlist-edit-inbound-rules.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=233bfe0afecaa4eecdce02ca7f9ed15b) * Click **Save rules** ## Google Cloud Platform (GCP) ### Self hosted database * Log in to the [GCP Console](https://console.cloud.google.com/) * Navigate to [VPC Network -> Firewall](https://console.cloud.google.com/networking/firewalls) * Select an existing Firewall Rule or create a new one * Set the following: * **Direction of traffic**: Ingress * **Action on match**: Allow * **Targets**: All instances on network * **Source filter**: IPv4 ranges * **Source IPv4 ranges**: Add the following IP addresses: \ `100.24.157.155/32, 34.200.73.233/32, 34.209.17.50/32, 35.155.119.178/32, 35.86.18.137/32, 44.232.244.93/32, 54.211.180.182/32, 54.243.113.90/32` * **Protocols and ports**: Specified protocols and ports, TCP Ports (defaults: Postgres: 5432, MySQL: 3306, MSSQL: 1433) ![Add Superblocks IP addresses to the allow list in GCP](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/gcp_firewall_rule.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=4ca44570abd830ff06d449376037d1e9) * Click Create/Save ### Cloud SQL * Select a GCP [SQL instance](https://console.cloud.google.com/sql/instances) * Navigate to Connections -> Networking * In the Networking tab, make sure to add all IP addresses in the "Authorized Network" section found in the [IP Allowlist](/integrations/auth/database-connections#networking) by clicking "Add a Network" ![Add Superblocks IP addresses to GCP SQL cloud instance](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/gcp.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=799b8032852dcb2483ca03585ed5d662) * Click Done/Save # Authenticate with Google OAuth 2.0 Source: https://docs.superblocks.com/integrations/auth/guides/guide-authenticating-with-google-oauth-2.0 Google provides many public APIs that you can use in Superblocks. Some, like [Google Analytics](/integrations/integrations-library/google-analytics) and [Google Drive](/integrations/integrations-library/google-drive) are available as Superblocks integrations. Others you can connect to using Superblocks [REST API](/integrations/integrations-library/rest-api) Integration. Google's APIs are authenticated and require that you configure OAuth to connect to them. This guide walks through how to configure an OAuth 2.0 client in Google, and use it in Superblocks to connect to APIs. ## Prerequisites ## Set up ### Create Google OAuth Client 1. In Google Cloud Console search for the Credentials Page: [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) ![The Credentials page on Google Cloud Platform's Dashboard](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/google1.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=42bb9a103300b0308a5a03cd9a58e9a4) 2. Click on **Create Credentials** and select **OAuth client ID** 3. Configure your credentials: 1. Select the **Web application** application type 2. Choose a name for your credentials 3. Add `https://{tenant}.superblocks.com` as an "Authorized JavaScript origin" 4. Add `https://{tenant}.superblocks.com/oauth/callback` as an "Authorized redirect URI" Replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). ![Specify Superblocks as authorized JavaScript origin and authorized redirect URI in Google](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/google2.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=be6dd43bda9234d5805d5d6b7452a7fe) 4. Click **Create** and copy the `Client ID` and `Client secret` ### Configure Superblocks integration 1. Create a [REST API integration](https://app.superblocks.com/integrations/restapiintegration) in Superblocks (notice the added header). Replace the Client ID and Client Secret with the ones obtained in the previous step: ![Superblocks Authenticated REST API Configuration](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/google3.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=3dea157ea2cffc9bbcc1ff5c8fbbc606) 2. Now you can use the integration in a Superblocks App to access your Google Sheets data using Google's Sheets REST API: ![A successful call to Google's Spreadsheet API in Superblocks](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/google4.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=97a69594dabac44e205a5ccd3e0ebb58) # Connect to Microsoft 365 with the Microsoft Graph API Source: https://docs.superblocks.com/integrations/auth/guides/microsoft-365-graph-api Register an app in Microsoft Entra ID and connect Superblocks to Outlook, SharePoint, and Teams through the Microsoft Graph API ## Overview Microsoft 365 services like Outlook (Exchange), OneDrive, SharePoint, and Teams are all accessed through the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview). In Superblocks, you connect to Microsoft Graph with a [REST API](/integrations/integrations-library/rest-api) integration that authenticates using [OAuth 2.0](/integrations/auth/oauth-20). Each integration is backed by an **app registration** in Microsoft Entra ID. The app registration provides the client ID and secret Superblocks uses to request tokens, and its **API permissions** control what Superblocks can do in Microsoft 365. This guide walks through: 1. Creating an app registration in Microsoft Entra ID 2. Granting Microsoft Graph permissions 3. Creating the integration in Superblocks 4. Building an app with Clark using your Microsoft 365 integrations ## Prerequisites * Access to the [Microsoft Entra admin center](https://entra.microsoft.com) or [Azure portal](https://portal.azure.com) with permission to create app registrations * A Microsoft Entra admin available to grant admin consent, if your tenant requires it for the permissions you choose * Permission to create integrations in Superblocks ## Choose a permission type When you add Microsoft Graph permissions to an app registration, you choose between two types: | Permission type | Acts as | Superblocks auth method | Use when | | - | - | - | - | | **Delegated** | The user logged in to Superblocks | [OAuth2 - Authorization Code](/integrations/auth/oauth-20#authorization-code) | Users should only see and act on data they already have access to in Microsoft 365, such as their own inbox or the Teams channels they belong to | | **Application** | The app itself, like a service account | [OAuth2 - Client Credentials Grant](/integrations/auth/oauth-20#client-credential) | Background processes, such as Workflows or Scheduled Jobs, that need access without a user present | This guide uses **delegated** permissions with the Authorization Code flow, so each user authorizes with their own Microsoft identity and Microsoft 365 enforces their existing access. Integrations that use Authorization Code without a shared token prompt each user to log in, so they can't be used in Workflows or Scheduled Jobs. For background use, configure application permissions and the Client Credentials flow instead. ## Setup **1. Create an app registration** 1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity** → **Applications** → **App registrations** and click **New registration**. 2. Give the app a descriptive name, such as `Superblocks - Outlook`. 3. Under **Supported account types**, select **Accounts in this organizational directory only**. 4. Under **Redirect URI**, select the **Web** platform and enter: ```text theme={null} https://{tenant}.superblocks.com/oauth/callback ``` Replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). You can also copy the exact **Callback URL** from the Superblocks integration form in a later step. 5. Click **Register**. 6. From the app's **Overview** page, copy the **Application (client) ID** and **Directory (tenant) ID**. Create a separate app registration for each Microsoft 365 service you connect, such as one for mail, one for SharePoint, and one for Teams. This keeps each integration scoped to only the permissions it needs. **2. Create a client secret** 1. In the app registration, go to **Certificates & secrets** → **Client secrets** and click **New client secret**. 2. Add a description, choose an expiration, and click **Add**. 3. Copy the secret's **Value** right away. It's only shown once. When the client secret expires, the integration stops working. Track the expiration date and rotate the secret in Superblocks before it expires. **3. Add Microsoft Graph API permissions** 1. In the app registration, go to **API permissions** and click **Add a permission**. 2. Select **Microsoft Graph**, then **Delegated permissions**. 3. Add the permissions for the service this integration connects to. For example: | Service | Example delegated permissions | | - | - | | **Outlook / Exchange mail** | `User.Read`, `Mail.ReadWrite`, `Mail.Send` | | **OneDrive** | `User.Read`, `Files.ReadWrite` | | **SharePoint** | `User.Read`, `Files.ReadWrite.All`, `Sites.ReadWrite.All` | | **Teams** | `User.Read`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`, `ChannelMessage.Send` | 4. If any permission shows **Admin consent required**, ask a Microsoft Entra admin to click **Grant admin consent** for your organization. Grant only the permissions your app needs. See Microsoft's [permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for the full list and what each one allows. **4. Create the integration in Superblocks** 1. Create a [REST API integration](/integrations/integrations-library/rest-api) in Superblocks and give it a name that identifies the service, such as `Microsoft Graph - Outlook`. 2. Set **Base URL** to `https://graph.microsoft.com/v1.0`. 3. Under **Authentication**, select **OAuth2 - Authorization Code** and fill in: | Field | Value | | - | - | | **Authorization URL** | `https://login.microsoftonline.com/{directory-tenant-id}/oauth2/v2.0/authorize` | | **Token URL** | `https://login.microsoftonline.com/{directory-tenant-id}/oauth2/v2.0/token` | | **Client ID** | The **Application (client) ID** from your app registration | | **Client secret** | The client secret **Value** you copied | | **Scopes** | `https://graph.microsoft.com/.default offline_access` | | **Prompt** | `select_account` | Replace `{directory-tenant-id}` with the **Directory (tenant) ID** from your app registration. The `.default` scope requests all of the Microsoft Graph permissions configured on your app registration, so you don't need to list them individually. `offline_access` must be requested explicitly so Superblocks receives a refresh token and can renew access without prompting users to sign in again. Don't add individual Graph permissions alongside `.default`; Microsoft rejects requests that combine them. Don't set **Prompt** to `consent`. Because of a [known Microsoft Entra ID issue](https://learn.microsoft.com/en-us/answers/questions/5847660/bug-report-prompt-consent-blocks-non-admin-users-e), `prompt=consent` blocks non-admin users with a "Need admin approval" (`AADSTS90094`) error, even after an admin has granted tenant-wide consent. `select_account` honors the existing admin consent and lets users sign in. 4. Confirm the **Callback URL** shown in the form matches the redirect URI on your app registration. If it doesn't, add it under **Authentication** in the app registration. 5. Under **Headers**, add an `Authorization` header with the value `Bearer {{ oauth.token }}`. 6. Click **Create** to save the integration. Repeat this step for each Microsoft 365 service, using that service's app registration and scopes. ## Build with Clark ### Teach Clark about your integrations Clark already knows Microsoft Graph from its public documentation, but it doesn't know the specifics of your tenant, like which SharePoint site and drive to use, which Teams channel to post to, or how your mailboxes are organized. Capture these details as [integration knowledge](/integrations/knowledge) so Clark looks them up whenever it works with that integration. The easiest way to build this knowledge is to have Clark explore your integrations first: 1. Create a new app so the exploration doesn't affect an existing one. 2. [Tag your integrations](/building-with-clark/tagging-integrations) with `@` and ask Clark to explore them. For example: ```text theme={null} Explore @Microsoft Graph - SharePoint and @Microsoft Graph - Teams. Find our SharePoint sites and their document libraries, and the Teams channels I have access to. Note the IDs and request patterns you'd need to upload files and post messages. ``` 3. Review what Clark finds, then ask it to save the insights to integration knowledge: ```text theme={null} Save what you learned about each integration to its integration knowledge. ``` Clark drafts an entry for each integration and presents it for your review before saving. Useful details to capture include site, drive, team, and channel IDs, the endpoints and request shapes that worked, and any quirks Clark ran into, such as pagination or required headers. Anyone who builds with these integrations later benefits from the same knowledge. ### Build an app Once your integrations are set up, you can have Clark build apps on top of them. Tag your integrations in your prompt with `@` so Clark uses them as data sources. For example: ```text theme={null} Build an AP invoice audit desk that reads invoice emails from @Microsoft Graph - Outlook, archives each invoice and an audit record to our SharePoint drive using @Microsoft Graph - SharePoint, and posts a confirmation to our finance channel with @Microsoft Graph - Teams. ``` Because these integrations use the Authorization Code flow, you're prompted to sign in with your Microsoft account when Clark first queries them. Clark then runs sample requests against Microsoft Graph to understand your data, such as pulling recent messages from your inbox, listing files in your SharePoint drive, and finding the Teams channels you have access to. It uses what it learns to ask clarifying questions and propose a plan before building. See [Plan & Build modes](/building-with-clark/plan-and-build-modes) for how planning works. When users run the finished app, each user signs in with their own Microsoft account and only sees the mail, files, and channels they have access to in Microsoft 365. ## Troubleshooting ### Users see "Need admin approval" (AADSTS90094) If non-admin users are blocked with a "Need admin approval" screen when they sign in: 1. Confirm a Microsoft Entra admin has clicked **Grant admin consent** on the app registration's **API permissions** page, and that each permission shows a **Granted** status. 2. In the Superblocks integration, set **Prompt** to `select_account`. If **Prompt** is set to `consent`, Microsoft Entra ID ignores the existing admin consent and asks each user to consent for themselves, which your tenant's consent policy blocks. See Microsoft's [bug report](https://learn.microsoft.com/en-us/answers/questions/5847660/bug-report-prompt-consent-blocks-non-admin-users-e) for details. ## Related documentation * [OAuth 2.0](/integrations/auth/oauth-20): details on each OAuth flow, token caching, and refresh * [REST API integration](/integrations/integrations-library/rest-api): REST API integration settings, including uploading OpenAPI specs * [Tagging integrations](/building-with-clark/tagging-integrations): reference integrations in your Clark prompts * [Integration knowledge](/integrations/knowledge): teach Clark how to work with each integration # Microsoft Fabric SQL Database with managed identity Source: https://docs.superblocks.com/integrations/auth/guides/microsoft-fabric-sql-database This guide applies to the Superblocks [Hybrid](/enterprise/deployment-overview) deployment on [Azure Container Apps](/enterprise/hybrid-architecture/deployment/azure_container_apps). It does not apply to customers on Superblocks Cloud. ## Overview This guide describes how to connect the Superblocks data plane running on **Azure Container Apps (ACA)** to a [**Microsoft Fabric SQL Database**](https://learn.microsoft.com/en-us/fabric/database/sql/overview) using the ACA's **system-assigned managed identity** and **Microsoft Entra authentication**. ### Authentication flow 1. The Superblocks data plane container app has a **system-assigned managed identity** enabled. 2. When a query runs, the container obtains an Entra access token from Azure's managed identity endpoint. 3. The token is supplied to the Microsoft SQL Server connector via the **connection string** (no SQL username or password). 4. Microsoft Fabric validates the token and authorizes the request based on workspace and database permissions granted to the identity. ```mermaid theme={null} sequenceDiagram autonumber participant App as Superblocks app participant DP as Data plane (ACA) participant MI as Azure Managed Identity endpoint participant Fabric as Fabric SQL Database Note over DP: System-assigned managed identity
attached to the container app App->>DP: Run query against Fabric integration rect rgb(232, 240, 254) Note right of DP: Identity / token flow DP->>MI: Request Entra access token
(resource=https://database.windows.net/) MI-->>DP: Access token end rect rgb(232, 247, 233) Note right of DP: Data flow DP->>Fabric: Open Fabric SQL connection
using Entra token (no username/password) Fabric->>Fabric: Validate Entra token Fabric->>Fabric: Authorize via Fabric workspace
+ item permissions Fabric->>Fabric: Authorize via SQL database roles
(db_datareader / db_datawriter) Fabric-->>DP: Query results end DP-->>App: Return data ``` ## Prerequisites * An [Azure Container App](/enterprise/hybrid-architecture/deployment/azure_container_apps) running the Superblocks data plane. * **Owner** or **Contributor** on the resource group containing the container app. * A **Microsoft Fabric SQL Database** in a workspace you can administer. * A **Fabric / Power BI tenant administrator** available if service principal access is not yet enabled at the tenant level. ## Setup **1. Set managed identity variables on the container app** If not previously configured, add the following environment variable to the container app: | Name | Value | | - | - | | `SB_EXECUTION_ENV_INCLUSION_LIST` | `IDENTITY_ENDPOINT,IDENTITY_HEADER` | **2. Enable system-assigned managed identity on the container app** 1. In the [Azure portal](https://portal.azure.com), open your **Container App**. 2. Go to **Security** → **Identity**. 3. Open the **System assigned** tab. 4. Set **Status** to **On** and click **Save**. 5. Redeploy the container app revision if prompted. This automatically creates an Entra identity tied to the container app's lifecycle. ![Azure Container App Identity page with System assigned tab selected and Status toggled On](https://mintcdn.com/superblocks/qF6UPF93YwEP2OW9/images/enterprise-deployment/aca-system-identity.png?fit=max\&auto=format\&n=qF6UPF93YwEP2OW9\&q=85\&s=53fdf05804274d1d4b2f234e9b933658) **3. Confirm Fabric tenant settings** A **Fabric / Power BI tenant administrator** must enable service principal access before managed identities can use the Fabric APIs. Fabric gates this behind a **Microsoft Entra security group**: only identities that are members of an allowed group can use the APIs. Follow Microsoft's [Enable service principal authentication for admin APIs](https://learn.microsoft.com/en-us/fabric/admin/enable-service-principal-admin-apis) guide for the authoritative reference; the steps below summarize what is required for this setup. Microsoft Fabric treats managed identities the same as service principals for API and database access. 1. **Create (or reuse) a Microsoft Entra security group** In the [Azure portal](https://portal.azure.com), go to **Microsoft Entra ID** → **Groups** → **New group**. Set **Group type** to **Security**, give it a name (for example, `superblocks-fabric-access`), and create it. 2. **Add the managed identity to the security group** Open the security group → **Members** → **Add members** and add the container app's system-assigned identity. You can search by the container app's name — the identity's display name matches the container app's resource name. 3. **Enable the tenant setting in the Fabric admin portal** Sign in to the [Fabric admin portal](https://app.fabric.microsoft.com/admin-portal) as a **Fabric admin**, go to **Tenant settings**, and enable **Service principals can use Fabric APIs**: * Set the toggle to **Enabled**. * Select **Specific security groups**. * Add the security group from the previous sub-step. * Click **Apply**. **4. Grant Fabric SQL Database permissions** In the Fabric workspace that contains your SQL Database: 1. Click **Manage access** → **Add people or group**. 2. Add the ACA's system-assigned identity (search by the container app's name). 3. Grant at minimum **Viewer** permissions for reading data, or **Contributor** for reading / writing data. More on roles and permissions [here](https://learn.microsoft.com/en-us/fabric/database/sql/authorization#item-permissions). This allows the identity to reach the Fabric SQL Database endpoint. ![Adding the Superblocks managed identity as a Contributor in Fabric workspace Manage access](https://superblocks-docs.s3.us-east-2.amazonaws.com/assets/fabric_manage_access.gif) **5. Create the identity as a database user** Connect to the Fabric SQL Database from VS Code, Azure Data Studio, or another SQL client **as yourself** (an admin), then run: ```sql theme={null} USE ; CREATE USER [] FROM EXTERNAL PROVIDER; ALTER ROLE db_datareader ADD MEMBER []; ALTER ROLE db_datawriter ADD MEMBER []; ``` Replace `` with the name of the container app whose system-assigned identity you enabled in the first step. The system-assigned identity's display name matches the container app's resource name. `CREATE USER ... FROM EXTERNAL PROVIDER` maps the Entra identity to a database user so token-based logins are allowed. Adjust the roles to your least-privilege needs. **6. Create the integration in Superblocks** Create a [Microsoft SQL Server](/integrations/integrations-library/mssql) integration in Superblocks using a **connection string** that targets the **SQL Database endpoint** (not the SQL analytics endpoint): ```text wrap theme={null} Data Source=.database.fabric.microsoft.com,1433; Initial Catalog=; Connect Timeout=30; Authentication=Active Directory Integrated; Encrypt=True; TrustServerCertificate=False; ``` Because we are using a **system-assigned** identity (only one identity per container app), no `Client Id` is needed in the connection string. The MSSQL connector picks up the system-assigned identity automatically from the container app's MSI environment. You can [find connection string details](https://learn.microsoft.com/en-us/fabric/database/sql/connect#find-sql-connection-string) like `` and `` under the Fabric SQL Database item's **Settings** → **Connection strings**. ## Related documentation * [Azure managed identity authentication to SQL Server](/integrations/auth/guides/azure-msi-sql-server) — equivalent guide for SQL Server on an Azure VM using a user-assigned identity * [Database connections](/integrations/auth/database-connections/index) — networking and connection strings * [Microsoft SQL Server integration](/integrations/integrations-library/mssql) — Superblocks UI setup # Set up OAuth 2.0 On-Behalf-Of token exchange with Okta as your IdP Source: https://docs.superblocks.com/integrations/auth/guides/on-behalf-of-token-exchange-backend-api This guide describes how to configure Okta as an authorization server for your [REST](/integrations/integrations-library/rest-api) or [GraphQL](/integrations/integrations-library/graphql) based backend API. With this auth method, Superblocks will be able to perform a machine-to-machine token exchange to get an access token for your backend API without losing context who is making the request in your Superblocks app. This lets your API perform auth checks using the user's permissions without forcing your user through a second login flow for your backend API. ## Prerequisites To follow this guide, you'll need: * An Okta account with the following permissions: * [API Access Management Administrator](https://help.okta.com/okta_help.htm?type=\&locale=en\&id=csh-administrators-api-access-mgmt-admin) * [Application Administrator](https://help.okta.com/en-us/content/topics/security/administrators-app-admin.htm?cshid=csh-administrators-app-admin) * An existing Superblocks SSO configuration using [Okta OIDC](/admin/org-administration/auth/single-sign-on/okta#create-an-oidc-integration) * A REST or GraphQL-based backend API If your Superblocks SSO currently uses a SAML-based flow, please reach out to our [support team](/enterprise/support/help) for assistance migrating to an OIDC-based log-in flow ## Token exchange flow ![On-Behalf-Of Token Exchange flow sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/obh-token-exchange-okta.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=d60a2785927de0189d97a5a3a66b30be) **Note**: This flow assumes the user is already logged into Superblocks When using this flow: 1. Your user will log in to Superblocks using your [Okta OIDC app](/admin/org-administration/auth/single-sign-on/okta#create-an-oidc-integration) 2. When the user executes an API, a request is sent from the browser to the Superblocks Agent that includes the user's Okta JWT 3. The API includes a step to make a request to your backend API. The Superblocks Agent will make a request to your [Okta authorization server](#create-an-authorization-server) to exchange the user’s Okta JWT for a new token intended for your backend API 4. The Okta authorization server validates the user’s JWT and then grants a new access token with scopes that allow Superblocks to make requests to your backend API. The new access token retains the user context so your backend API knows on whose behalf the request is made. 5. The Superblocks Agent makes a request to your backend API and includes the new access token For more details on this token exchange in Superblocks, see our docs on the [OAuth 2.0 - On-Behalf-Of Token Exchange](/integrations/auth/oauth-20#on-behalf-of-token-exchange) auth method. ## Setup instructions The following instructions show how to configure Okta & Superblocks to perform the token exchange. ### Create an API in Okta To perform the token exchange, you'll need to create an API application that the Superblocks Agent will use to act as an OAuth client for your backend API. 1. Log in to Okta and go to the **Admin Console** 2. Navigate to **Applications** → **Applications** 3. Click **Create App Integration** 4. Select **API Services** followed by **Next** 5. Name the app something like **Superblocks Integration** and click **Save** 6. Click **Edit** in the **General Settings** section of the **General** tab 7. Uncheck the checkbox for **Require Demonstrating Proof of Possession (DPoP) header in token requests** 8. Check the checkbox for **Token Exchange** and click **Save** 9. Make a note of the `Client ID` in the **Client Credentials** section and the `Client Secret` in the **CLIENT SECRETS** section ### Create an authorization server During the token exchange, the Superblocks Agent exchanges the user's OpenID access token granted during log in with an [Okta Authorization Server](https://developer.okta.com/docs/guides/customize-authz-server/main) configured to issue tokens for our backend API. #### Create the authorization server 1. In the Admin Console, go to **Security** → **API** 2. On the **Authorization Servers** tab, click **Add Authorization Server** 3. Enter a **Name**, **Audience**, and **Description** for the authorization server **Note**: The **Audience** value specified will be set as the `aud` claim of the access token sent to your backend API. The **Audience** property should be set to the URI expected by your API. #### Add custom scopes & claims 1. From the authorization server, select the **Scopes** tab 2. Click **Add scopes** and add any custom scopes your backend API requires 3. Click on the **Claims** tab 4. Click **Add claim** and configure any custom claims you want to include on the access token #### Create access policies and rules 1. From the authorization server, select the **Access Policies** tab and click **Add Policy** 2. In the **Add Policy** dialog that appears, enter the following: * **Name**: Access Superblocks * **Description**: Enter a description * **Assign to**: Select **The following clients** and search for your organization's Superblocks SSO application 3. Click **Create Policy** 4. Click **Add Rule** and in the dialog that appears, enter the following: * **Name**: Superblocks App to Agent * **AND Scopes requested**: Select **The following scopes** and enter `openid` 5. Click **Create rule** 6. Repeat steps 1 - 5 to create a policy and a rule that lets the Superblocks Agent talk to your backend API.\ Use the following values for the **policy**: * **Name**: Access Backend API * **Assign to**: Select **The following clients**, start typing the name of the [API](#create-an-api-in-okta) that you created earlier Use the following values for the **rule**: * **Name**: Agent to Backend API * **AND Scopes requested**: Select **The following scopes**, and select any of the [custom scopes](#add-custom-scopes--claims) you configured previously * **AND Refresh token lifetime is**: Unlimited (this is recommmended but not required) Learn more about how to [Create an Okta Authorization Server](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-an-authorization-server) ### Update SSO metadata Superblocks SSO by default uses your Okta [Org Authorization Server](https://developer.okta.com/docs/concepts/auth-servers/#org-authorization-server). To use token exchange, we'll need to update your SSO configuration to use a Custom Authorization Server. To do this, we will need the `.well-known/openid-configuration` URL of your Authorization Server. To locate this URL: 1. Go to the **Settings** tab of your Authorization Server 2. Copy the **Metadata URI** shown in the **Settings** section 3. Replace `oauth-authorization-server` with `openid-configuration` 4. Send this link to [support@superblocks.com](mailto:support@superblocks.com) with the Subject **Update Okta SSO to use Token Exchange** If your backend uses a micro-services architecture that has multiple APIs, or you plan on using token exchange for your backend API as well as services like [Snowflake](/integrations/integrations-library/snowflake), make sure you've added this server as a [trusted server](https://help.okta.com/en-us/content/topics/security/api-add-trusted-servers.htm) to all other auth servers you'll use in Superblocks. ### Update your integration Once you've gotten confirmation from Superblocks that we've updated your SSO to use the new Authorization Server, you're ready to configure your Integration. To do so: 1. Navigate to the **Integrations** page and search for your [REST](/integrations/integrations-library/rest-api) or [GraphQL](/integrations/integrations-library/graphql) API 2. Select **OAuth2 - On-Behalf-Of Token Exchange** as the **Authentication** method 3. Choose **Login Identity Provider** as the **Subject token source** 4. Specifying the following configuration values: | Field | Required | Description | | - | - | - | | **Token URL** | ✓ | The `token_endpoint` found in your [Authorization Server](#create-an-authorization-server)'s `{SERVER}/.well-known/oauth-authorization-server` metadata file | | **Client ID** | ✓ | The `client_id` of the [API](#create-an-api-in-okta) created earlier | | **Client secret** | ✓ | The `client_secret` of the [API](#create-an-api-in-okta) created earlier | | **Audience** | ✗ | Your [Authorization Server](#create-an-authorization-server)'s **Audience** | | **Scopes** | ✗ | Any custom scopes you configured for your authorization server | 5. Use the [`oauth` object](/integrations/auth/oauth-20#the-oauth-object) in **Headers** or **Params** to define how the access token returned by the authorization server should be sent to your API Okta Authorization Servers can only return an `access_token`, not an `id_token`. For this reason, `oauth.idToken` and `oauth.tokenDecoded` aren't available when using this auth method. ## Testing & troubleshooting ### Test your integration With your integration updated to use your Okta authorization server to issue access tokens, you're ready to test it in a Backend API. 1. In an Application create a new Backend API 2. Add a step that uses your Integration 3. Configure the step to make a request to your API 4. Click **Run API** If everything is working properly, you should see the step respond as it would if you made a cURL request with your own access token to the API. ### Troubleshooting The easiest way to troubleshoot authorization issues is by inspecting the access token that Superblocks is sending to your API. To do this: 1. Make a copy of your Integration 2. Replace the **Base URL** with an API testing service like [webhook.site](https://webhook.site/) or [Postman Echo](https://learning.postman.com/docs/developer/echo-api/) 3. Add an **Authorization** header with the value `{{ oauth.token }}` 4. Save the Integration 5. Build a Backend API that uses this "echo" integration 6. Run the API and copy the access token from the authorization header 7. Use a tool like [JWT](https://jwt.io/) to inspect the token ### Common errors See the below guide for known error conditions, why they happen, and how to address them. | Error message | Why it's happening | Resolution | | - | - | - | | `Could not find identity provider token` | Your organization either doesn't use SSO or it's configured in a way that doesn't support token exchange | Follow docs to set up [Okta SSO](/admin/org-administration/auth/single-sign-on/okta) or contact [support@superblocks.com](mailto:support@superblocks.com) to update your configuration | | `Identity provider token expired` | Your Okta session has expired so the authorization server won't issue an access token | Refresh your browser, you should be prompted to reauthenticate. If you're not, log out and back in. | | `Could not find a user JWT` | The Superblocks Agent doesn't have a user JWT so can't extract a `subject_token` to send to Okta. It most likely is occurring because the integration is being used in a Workflow, Scheduled Job, or public App. | Refactor your code to use the Integration in a Backend API | | `Token exchange failed` | Superblocks couldn't successfully complete the token exchange with the Okta authorization server. | See the additional error details provided by Okta. You may also be able to find additional error information in your Okta system logs. | # Set up OAuth 2.0 Token Exchange for Salesforce Source: https://docs.superblocks.com/integrations/auth/guides/salesforce-token-exchange This guide describes how to configure Salesforce to accept OAuth 2.0 Token Exchange authentication from Superblocks. With this auth method, Superblocks performs a machine-to-machine token exchange to obtain a Salesforce access token on behalf of the current user without requiring the user to log in to Salesforce separately and without storing long-lived Salesforce credentials in Superblocks. Once configured, every Salesforce API call made through Superblocks will be executed as the specific user who is running the application, allowing Salesforce to enforce its existing record-level visibility rules, field-level security, and sharing settings. ## Prerequisites To follow this guide, you'll need: * A Superblocks organization with enterprise SSO configured using an OIDC-based identity provider (for example, [Okta OIDC](/admin/org-administration/auth/single-sign-on/okta#create-an-oidc-integration) or Microsoft Entra ID) * A Salesforce org (production or sandbox) with API access enabled * Salesforce **System Administrator** profile or a profile with the following permissions: * **Manage External Client Apps** * **View Setup and Configuration** * **Customize Application** * **Author Apex** This flow requires an OIDC-based SSO connection. If your Superblocks SSO uses a SAML-only flow that does not issue an OIDC access token, please contact [support@superblocks.com](mailto:support@superblocks.com) before proceeding. ## Token exchange flow When using this auth method: 1. Your user logs in to Superblocks using your enterprise SSO identity provider (for example, Okta) 2. When the user runs a Superblocks API that includes a Salesforce step, a request is sent from the browser to the Superblocks Data Plane, including the user's identity provider (IDP) JWT 3. The Superblocks Agent extracts the user's IDP access token and sends a token exchange request to Salesforce's OAuth token endpoint using the `urn:ietf:params:oauth:grant-type:token-exchange` grant type as defined in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) 4. Salesforce invokes the custom [APEX Token Exchange Handler](#step-2-write-the-apex-token-exchange-handler) you deploy, which validates the IDP token, extracts the user's email, and maps it to a Salesforce user 5. Salesforce returns a scoped access token for that user 6. The Superblocks Data Plane uses the access token to execute the Salesforce API call on behalf of the user The IDP access token used as the `subject_token` in the exchange is only available when the user has authenticated via an enterprise SSO connection. It is not available for username/password logins. ## Setup instructions ### Step 1: Create a Salesforce External Client App An External Client App registers Superblocks as an OAuth client in your Salesforce org and enables the Token Exchange grant type. 1. Log in to Salesforce and navigate to **Setup** 2. In the Quick Find box, search for **External Client Apps Manager** 3. Click **New External Client App** 4. Fill in the **Basic Information** section: * **External Client App Name**: `Superblocks` * **API Name**: `Superblocks` (auto-populated) * **Contact Email**: your administrator email 5. In the **OAuth Settings** section, check **Enable OAuth Settings** 6. Set **Callback URL** to `https://login.salesforce.com/services/oauth2/success` The Callback URL is required by the form but is not used by the Token Exchange flow. Any valid HTTPS URL works. 7. Under **OAuth Scopes**, add the following scopes: * `Manage user data via APIs (api)` * `Perform requests on your behalf at any time (refresh_token, offline_access)` — optional, only needed if your use case requires offline access 8. Scroll down to the **OAuth 2.0 Token Exchange Flows** section and check **Enable Token Exchange Flow** 9. Click **Save**, then click **Continue** After saving, Salesforce takes a few minutes to provision the app. Once available: 1. From External Client App Manager, click the arrow next to your app and select **Edit Settings** 2. Click the **Settings** tab, scroll down and open the **OAuth Settings** dropwdown 3. Click on **Consumer Key and Secret** (you may need to verify via email) 4. Copy and save the **Consumer Key** (Client ID) and **Consumer Secret** (Client Secret) — you will need these when configuring the Superblocks integration 5. Go back to External Client App Manager, click the arrow next to your app and select **Edit Policies** 6. Under **OAuth Policies** → **Permitted Users**, select **Admin approved users are pre-authorized** You must assign profiles to the app after creation. If you do not, token exchange requests will fail with "user hasn't approved this consumer". ### Step 2: Write the APEX Token Exchange Handler Salesforce requires a custom APEX class that extends Auth.Oauth2TokenExchangeHandler. This handler is responsible for validating the incoming JWT and mapping it to a Salesforce user. When Salesforce receives a token exchange request, it invokes this handler, which is responsible for validating the incoming IDP access token and mapping the incoming identity provider token to the Salesforce user for whom Salesforce should issue the exchanged access token. The handler below decodes the IDP access token (a JWT), extracts the `email` claim, and looks up the matching active Salesforce user. #### Deploy the handler class 1. In Salesforce Setup, search for **Developer Console** and open it (or use the Salesforce CLI / VS Code Salesforce Extension) 2. Go to **File** → **New** → **Apex Class** 3. Name the class `SuperblocksTokenExchangeHandler` 4. Replace the default content with the following: ```apex theme={null} global class SuperblocksTokenExchangeHandler extends Auth.Oauth2TokenExchangeHandler { global override Auth.TokenValidationResult validateIncomingToken( String appDeveloperName, Auth.IntegratingAppType appType, String incomingToken, Auth.OAuth2TokenExchangeType tokenType ) { try { List jwtParts = incomingToken.split('\\.'); if (jwtParts.size() < 2) { return new Auth.TokenValidationResult(false); } String payload = jwtParts[1]; Integer remainder = Math.mod(payload.length(), 4); if (remainder > 0) { payload = payload + '===='.substring(0, 4 - remainder); } payload = payload.replace('-', '+').replace('_', '/'); String payloadJson = EncodingUtil.base64Decode(payload).toString(); Map claims = (Map) JSON.deserializeUntyped(payloadJson); String identityValue = (String) claims.get('sub'); if (String.isBlank(identityValue)) { identityValue = (String) claims.get('email'); } if (String.isBlank(identityValue)) { identityValue = (String) claims.get('upn'); } if (String.isBlank(identityValue)) { return new Auth.TokenValidationResult(false); } Auth.UserData userData = new Auth.UserData( (String) claims.get('sub'), null, null, null, identityValue, null, identityValue, null, null, null, null ); return new Auth.TokenValidationResult( true, null, userData, incomingToken, tokenType, null ); } catch (Exception e) { return new Auth.TokenValidationResult(false); } } global override User getUserForTokenSubject( Id networkId, Auth.TokenValidationResult result, Boolean canCreateUser, String appDeveloperName, Auth.IntegratingAppType appType ) { String identityValue = result.getUserData().email; List users = [ SELECT Id, Email, Username FROM User WHERE IsActive = true AND (Email = :identityValue OR Username = :identityValue) LIMIT 1 ]; if (!users.isEmpty()) { return users[0]; } return null; } } ``` 5. Click **Save** **Customizing the email claim**: The claim name used to look up the user (`sub` in the example above) must match the claim included in your IDP's access tokens. Common alternatives are `email`, `preferred_username`, or `upn`. Check your IDP's access token format to confirm the correct claim name. **Test the handler in a sandbox first.** The handler runs with the permissions of the System Administrator who owns the External Client App. Verify that user lookup works correctly before deploying to production. #### Optional: validate the token signature The example above decodes the JWT payload without verifying the signature. For production environments, you may want to add signature validation using your IDP's public JWKS endpoint. Salesforce provides the `Auth.JWTUtil` class for this purpose, or you can make a callout to your IDP's `jwks_uri` endpoint to retrieve the public key. If you implement signature validation, you will need to add your IDP's JWKS endpoint to the Salesforce **Remote Site Settings** (Setup → Remote Site Settings → New Remote Site). ### Step 3: Create and Configure the Token Exchange Handler Salesforce requires a Token Exchange Handler record to link your Apex class to your External Client App. 1. In Salesforce Setup, search for **Token Exchange Handlers** 2. Click **New** 3. Configure the following: * **Name**: Superblocks Token Exchange Handler * **Apex Class**: SuperblocksTokenExchangeHandler * **Supported Token Types**: JWT 4. Save ### Link the handler to your app 1. Open the Token Exchange Handler you just created 2. Click **Enable New App** 3. Select your External Client App 4. Configure: * **Run As User**: Select a valid Salesforce user that the handler should run as. This user provides the execution context for the handler itself and must have sufficient permissions to perform user lookup and validation logic. The Salesforce user for whom the access token is issued is still determined dynamically by the handler based on the incoming token. 5. Save If the handler is not linked to the app, Salesforce will return: "token handler not found" ### Step 4: Configure the Superblocks integration Once your Salesforce External Client App and APEX handler are in place and the Token Exchange Handler is linked, configure the Salesforce integration in Superblocks. 1. In Superblocks, navigate to the **Integrations** page 2. Search for **Salesforce** and click **New Integration** (or edit an existing one) 3. In the **Authentication** dropdown, select **OAuth 2.0 Token Exchange** 4. Set **Subject token source** to **Login Identity Provider** 5. Fill in the remaining fields using the values from your External Client App: | Field | Required | Description | | - | - | - | | **Token URL** | ✓ | `https://login.salesforce.com/services/oauth2/token` for production orgs. Use `https://test.salesforce.com/services/oauth2/token` for sandbox orgs. | | **Client ID** | ✓ | The **Consumer Key** from your External Client App | | **Client secret** | ✓ | The **Consumer Secret** from your External Client App | | **Scope** | ✗ | `api` — required to make Salesforce REST API calls. Add additional scopes separated by spaces as needed. | 6. Click **Test Connection** to verify the configuration, then click **Save** The **Subject token type** field defaults to `urn:ietf:params:oauth:token-type:access_token`, which is the correct value for IDP access tokens. You do not need to change this. ## Testing & troubleshooting ### Test the integration With the integration configured, verify that it works end-to-end: 1. In a Superblocks application, create a new **Backend API** 2. Add a step that uses your Salesforce integration 3. Add a SOQL query step, for example: ```sql theme={null} SELECT Id, Name, Username FROM User WHERE Id = :$userId LIMIT 1 ``` Where `$userId` resolves to the current Salesforce user 4. Click **Run API** If everything is working, the step should return data for the Salesforce user that corresponds to the logged-in Superblocks user. ### Common errors | Error message | Why it's happening | Resolution | | - | - | - | | `Could not find identity provider token` | The user is not logged in via an enterprise SSO connection, or the SSO connection is not configured to issue OIDC access tokens | Confirm that your Superblocks SSO uses an OIDC-based flow. Contact [support@superblocks.com](mailto:support@superblocks.com) if you need assistance. | | `Identity provider token expired` | The user's IDP session has expired | Ask the user to refresh the browser or log out and back in to obtain a fresh IDP token | | `Could not find a user JWT` | The integration is being used in a Workflow, Scheduled Job, or public App where there is no logged-in user context | Token Exchange requires an active user session. Use this integration type in Backend APIs only, not in Workflows or Scheduled Jobs. | | `Token exchange failed` | Superblocks received an error from the Salesforce token endpoint | Check the error details returned by Salesforce. Common causes: the External Client App is not yet provisioned (wait a few minutes after creation), the Token Exchange Flow is not enabled on the External Client App, or the handler class is not linked. | | `MISSING_EMAIL_CLAIM` (from your APEX handler) | The IDP access token does not include an `email` claim | Update the `SuperblocksTokenExchangeHandler` to use the claim name your IDP includes. Check the IDP access token using [jwt.io](https://jwt.io) to confirm the correct claim. | | `USER_NOT_FOUND` (from your APEX handler) | No active Salesforce user was found with the email from the IDP token | Verify that the user exists in Salesforce with an exactly matching email address (case-insensitive) and that their account is active. | # Set up Snowflake External OAuth with Okta as your IdP Source: https://docs.superblocks.com/integrations/auth/guides/snowflake-external-oauth-with-okta This guide describes how to use the **External OAuth** auth method of the [Snowflake Integration](/integrations/integrations-library/snowflake). It includes instructions for configuring Snowflake as an OAuth Resource and Okta as an External OAuth authorization server to use with Superblocks. Once configured, you'll be able to connect to Snowflake on behalf of the current Superblocks user and enforce data access using your already defined roles and permissions in Snowflake. ![](https://mintcdn.com/superblocks/4CaXR9yMYhYSXJSi/images/integrations/authentication/superblocks-snowflake-architecture.png?fit=max\&auto=format\&n=4CaXR9yMYhYSXJSi\&q=85\&s=6dd06234e301ae798220798e303533d1) ## Prerequisites To follow this guide, you'll need: * An Okta account with the following permissions: * [API Access Management Administrator](https://help.okta.com/okta_help.htm?type=\&locale=en\&id=csh-administrators-api-access-mgmt-admin) * [Application Administrator](https://help.okta.com/en-us/content/topics/security/administrators-app-admin.htm?cshid=csh-administrators-app-admin) * An existing Superblocks SSO configuration using [Okta OIDC](/admin/org-administration/auth/single-sign-on/okta#create-an-oidc-integration) * A Snowflake account with `ACCOUNTADMIN` permission If your Superblocks SSO currently uses a SAML-based flow, please reach out to our [support team](/enterprise/support/help) for assistance migrating to an OIDC-based log-in flow ## External OAuth flow ![On-Behalf-Of Token Exchange flow sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/obh-token-exchange-snowflake.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=da32509f2ed427526d987cd2361bde03) **Note**: This flow assumes the user is already logged into Superblocks When using this flow: 1. Your user will log in to Superblocks using your [Okta OIDC app](/admin/org-administration/auth/single-sign-on/okta#create-an-oidc-integration) 2. When the user executes an API, a request is sent from the browser to the Superblocks Agent that includes the user's Okta JWT 3. If the API includes a step to query Snowflake, the Superblocks Agent will make a request to your [Okta authorization server](#create-an-authorization-server) to exchange the user’s Okta JWT for a new access token intended for Snowflake 4. The Okta authorization server will validate the user’s JWT and grants a new access token with the necessary `sub`, `aud`, and `scp` to access Snowflake 5. The Superblocks Agent connects to Snowflake using this access token 6. Your Snowflake instance validates the JWT and decodes it to authenticate the user to Snowflake 7. Provided the user is authenticated, Superblocks executes their query and returns data to the browser For more resources on this auth flow, see: * Snowflake's docs to [Configure Okta for External OAuth](https://docs.snowflake.com/en/user-guide/oauth-okta) * Okta's docs on [Authorization Servers](https://developer.okta.com/docs/concepts/auth-servers/) * Superblocks docs on [OAuth 2.0 - On-Behalf-Of Token Exchange](/integrations/auth/oauth-20#on-behalf-of-token-exchange) ## Setup instructions The following instructions show how to configure Okta, Snowflake, and Superblocks to perform the token exchange. ### Create an API in Okta To perform the token exchange, you'll need to create an API application that the Superblocks Agent will use to act as an OAuth client. 1. Log in to Okta and go to the **Admin Console** 2. Navigate to **Applications** → **Applications** 3. Click **Create App Integration** 4. Select **API Services** followed by **Next** 5. Name the app something like **Superblocks Integration** and click **Save** 6. Click **Edit** in the **General Settings** section of the **General** tab 7. Uncheck the checkbox for **Require Demonstrating Proof of Possession (DPoP) header in token requests** 8. Check the checkbox for **Token Exchange** and click **Save** 9. Make a note of the `Client ID` in the **Client Credentials** section and the `Client Secret` in the **CLIENT SECRETS** section ### Create an authorization server During the token exchange, the Superblocks Agent exchanges the user's OpenID access token granted during log in with an [Okta Authorization Server](https://developer.okta.com/docs/guides/customize-authz-server/main) configured to issue tokens for Snowflakes. #### Create the authorization server 1. In the Admin Console, go to **Security** → **API** 2. On the **Authorization Servers** tab 3. Click **Add Authorization Server** and in the dialog enter the following: * **Name**: Snowflake Authorization Server * **Description**: Issue access tokens for Snowflake * **Audience**: The URL of the Snowflake account you want to connect to. For example `https://.snowflakecomputing.com` 4. Click **Save** > [accordion] Finding your Snowflake Account URL > > If you don't know your Snowflake account URL, log into Snowflake and click on the profile icon, as shown below, to copy the URL. > > ![Click profile and open organization and account menu to find Account URL](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/authentication/snowflake-account-url.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=3cbb984859821c03dd8e5bd2dd978b44) #### Add `session:role-any` scope 1. From the authorization server, select the **Scopes** tab 2. Click **Add scopes** 3. In the dialog, enter the following: * **Name**: `session:role-any` * **Display phrase**: `session:role-any` * **Description**: Ask Snowflake to let Superblocks assume the user's roles * **User consent**: Implicit * **Metadata**: Include in public metadata 4. Click **Save** ![Snowflake Okta Auth Server session:role-any scope configuration](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/authentication/snowflake-token-exchange-scopes.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=fe40d0ccd0470a2470b823076a4a3f21) #### Create access policies and rules 1. From the authorization server, select the **Access Policies** tab and click **Add Policy** 2. In the **Add Policy** dialog that appears, enter the following: * **Name**: Access Superblocks * **Description**: Enter a description * **Assign to**: Select **The following clients** and search for your organization's Superblocks SSO application 3. Click **Create Policy** 4. Click **Add Rule** and in the dialog that appears, enter the following: * **Name**: Superblocks App to Agent * **AND Scopes requested**: Select **The following scopes** and enter `openid` 5. Click **Create rule** 6. Repeat steps 1 - 5 to create a policy and a rule that lets the Superblocks Agent talk to Snowflake. Use the following values for the **policy**: * **Name**: Access Snowflake * **Assign to**: Select **The following clients**, start typing the name of the [API](#create-an-api-in-okta) that you created earlier Use the following values for the **rule**: * **Name**: Agent to Snowflake * **AND Scopes requested**: Select **The following scopes**, and select the `session:role-any` scope * **AND Refresh token lifetime is**: Unlimited (this is recommmended but not required) Learn more about how to [Create an Okta Authorization Servers](https://developer.okta.com/docs/guides/customize-authz-server/main/#create-an-authorization-server) ### Collect Okta information 1. From the authorization server, select the **Settings** tab 2. Click on the **Metadata URI** link to open the metadata document 3. In this document, locate the following values:
Metadata Value Example Snowflake Reference Value
`issuer` [https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7](https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7) `OKTA_ISSUER`
`jwks_uri` [https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/keys](https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/keys) `OKTA_JWS_KEY_ENDPOINT`
`token_endpoint` [https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/token](https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/token) `OKTA_OAUTH_TOKEN_ENDPOINT`
### Create Snowflake security integration With the information you've gathered from your Okta Authorization Server, you'll now create a security integration in Snowflake. The security integration ensures that Snowflake can communicate with Okta securely, validates the tokens from Okta, and provides the appropriate Snowflake data access to users based on the user role associated with the OAuth token. For more information, see Snowflake's docs on [CREATE SECURITY INTEGRATION](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration-oauth-external) 1. Log in to your Snowflake account 2. Change your current role to `ACCOUNTADMIN` or to a role with the global `CREATE INTEGRATION` privilege 3. Run the following SQL command ```sql theme={null} create security integration Superblocks_Okta_Security_Integration type = external_oauth enabled = true external_oauth_type = okta external_oauth_issuer = '' external_oauth_jws_keys_url = '' external_oauth_audience_list = ('') external_oauth_token_user_mapping_claim = 'sub' external_oauth_snowflake_user_mapping_attribute = 'login_name'; ``` ### Update SSO metadata Superblocks SSO by default uses your Okta [Org Authorization Server](https://developer.okta.com/docs/concepts/auth-servers/#org-authorization-server). To use token exchange flows, we'll need to update your SSO configuration to a Custom Authorization Server. To do this, we will need to know the `.well-known/openid-configuration` URL of the Snowflake Authorization Server you just created. To locate this URL: 1. Go to the **Settings** tab of your Snowflake Authorization Server 2. Copy the **Metadata URI** shown in the **Settings** section 3. Replace `oauth-authorization-server` with `openid-configuration` 4. Send this link to [support@superblocks.com](mailto:support@superblocks.com) with the Subject **Update Okta SSO to us Token Exchange** If you want to use the [token exchange flow with you backend APIs](/integrations/auth/guides/on-behalf-of-token-exchange-backend-api) as well as Snowflake, make sure you've added this server as a [trusted server](https://help.okta.com/en-us/content/topics/security/api-add-trusted-servers.htm) to all other auth server you'll use in Superblocks. ### Configure Snowflake integration Once you've gotten confirmation from Superblocks that we've updated your SSO to use the new Authorization Server, you're ready to configure your Snowflake integration. To do so: 1. Navigate to the **Integrations** page and locate your Snowflake integration or create a new one 2. In the **Connection method** dropdown, select **External OAuth** 3. Choose **Login Identity Provider** as the **Subject token source** 4. Specifying the following configuration values: | Field | Required | Description | | - | - | - | | **Account identifier** | ✓ | [Snowflake Account Identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier#non-vps-account-locator-formats-by-cloud-platform-and-region) | | **Token URL** | ✓ | Set to the `OKTA_OAUTH_TOKEN_ENDPOINT` value | | **Client ID** | ✓ | The `client_id` of the [API](#create-an-api-in-okta) created earlier | | **Client secret** | ✓ | The `client_secret` of the [API](#create-an-api-in-okta) created earlier | | **Audience** | ✓ | `SNOWFLAKE_ACCOUNT_URL` | | **Scopes** | ✓ | `session:role-any` | You can choose to set a default warehouse, schema, and role for the integration. If none are set, we will assume the defaults set by the user executing the query. ## Testing & troubleshooting ### Test your integration With your integration updated to use your Okta authorization server, you're ready to start writing queries. 1. In an Application create a new Backend API 2. Add a step that uses your Snowflake Integration 3. Run the SQL comment `SELECT CURRENT_USER();` 4. Click **Run API** If everything is working properly, you should see YOUR Snowflake user name returned. ### Common errors There are several common errors you may see when using token exchange. The table below include error messages, why they happen, and how to address them. | Error message | Why it's happening | Resolution | | - | - | - | | `Could not find identity provider token` | Your organization either doesn't use SSO or it's configured in a way that doesn't support token exchange | Follow docs to set up [Okta SSO](/admin/org-administration/auth/single-sign-on/okta) or contact [support@superblocks.com](mailto:support@superblocks.com) to update your configuration | | `Identity provider token expired` | Your Okta session has expired so the authorization server won't issue an access token | Refresh your browser, you should be prompted to reauthenticate. If you're not, log out and back in. | | `Could not find a user JWT` | The Superblocks Agent doesn't have a user JWT so can't extract a `subject_token` to send to Okta. It most likely is occurring because the integration is being used in a Workflow, Scheduled Job, or public App. | Refactor your code to use the integration in a Backend API | | `Token exchange failed` | Superblocks couldn't successfully complete the token exchange with the Okta authorization server. | See the additional error details provided by Okta. You may also be able to find additional error information in your Okta system logs. | # OAuth 2.0 authentication / authorization Source: https://docs.superblocks.com/integrations/auth/oauth-20 Superblocks supports many [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) flows. OAuth 2.0 is most commonly used by [REST APIs](/integrations/integrations-library/rest-api) and [GraphQL](/integrations/integrations-library/graphql), but can also be used by some cloud databases. ## OAuth 2.0 overview OAuth 2.0 is an industry standard protocol for user authentication and authorization. Using OAuth 2.0, a remote API server can grant access to a client securely by issuing a short-lived access token. ### Glossary The OAuth 2.0 spec, and it's usage in Superblocks, comes with some important terms: * **Client**: The app that wants to access data * **App type**: The type of Superblocks tool trying to access the data (App, Workflow, Scheduled Job) * **Resource server**: The API that stores the data the client wants to access * **Resource owner**: The owner of the data in the server * **Authorization server**: The server that manages access and issues access tokens * **Access token**: The token issued by the authorization server in exchange for the grant * **ID token**: An optional token that contains information about the end user in the form of claims * **Refresh token**: An optional token that is exchanged for a new access token if the access token has expired ### OAuth 2.0 flows OAuth 2.0 flows are often called "multi-legged" authorization flows because they involve multiple requests exchanged between the client, user, and server. For example, a usual OAuth 2.0 Authorization Code flow runs as follows: 1. A client makes a request for the user to authorize access to their data 2. If the user grants access, the client requests an access token by passing the authorization grant to an authorization server 3. If the grant is valid, the authorization server returns an access token, possibly alongside a refresh and/or ID token 4. The client uses the access token in requests to the API server 5. When the token expires, the client uses the refresh token to automatically request a new access token In Superblocks, OAuth 2.0 flows are performed by exchanging requests between the user's browser, the Superblocks Agent, and resource server. Once an access token is received, it is always sent to the resource server by the Superblocks Agent when steps are executed. ## Choosing an OAuth 2.0 flow The OAuth 2.0 flow you use depends on your use case and flows supported by your API server. Reference API documentation to determine the flows supported by the API you intend to use. If your API supports multiple flows, use the following table to help decide which flow to use: | App type | Resource owner | Shared token | User prompt | OAuth 2.0 flow | | - | - | - | - | - | | Workflow/Job | Server | ✓ | ✗ | [Client credentials](#client-credential) | | Workflow/Job | User | ✓ | ✗ | [Authorization Code](#authorization-code) w/ shared token [Password Grant (Legacy)](#password-grant-legacy) w/ shared token [On-Behalf-Of Token Exchange](#on-behalf-of-token-exchange) w/ static token | | Application | Server | ✓ | ✗ | [Client credentials](#client-credential) | | Application | User | ✓ | ✗ | [Authorization Code](#authorization-code) w/ shared token [Password Grant (Legacy)](#password-grant-legacy) w/ shared token [On-Behalf-Of Token Exchange](#on-behalf-of-token-exchange) w/ static token | | Application | User | ✗ | ✗ | [On-Behalf-Of Token Exchange](#on-behalf-of-token-exchange) w/ IdP token | | Application | User | ✗ | ✓ | [Authorization Code](#authorization-code), [Implicit](#implicit), or [Password Grant (Legacy)](#password-grant-legacy) | ## Using OAuth 2.0 ### Authorization Code Authorization Code grants require a user to authenticate with the authorization server before an access token can be issued. After authenticating and granting access, an authorization code is sent back to Superblocks. The Superblocks Agent sends this token to the `/token` endpoint of the auth server to get an access token. ![Authorization code flow sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-auth-code.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=15a5bf8341b4499107c8d3f4a52d9256) To use the authorization code flow: 1. In the Integration configuration select **OAuth2 - Authorization Code** 2. Copy the **Callback URL** provided and add it to the **Allowed Callback URLs** of your OAuth client 3. Specify the following configuration values: | Field | Required | Description | | - | - | - | | **Authorization URL** | ✓ | The endpoint users will be redirected to in order to log in and authorize access. **Note**: this value is not required for public APIs and is set by Superblocks | | **Token URL** | ✓ | The token endpoint of the authorization server, used to exchange an authorization code for an access token. **Note**: this value is not required for public APIs and is set by Superblocks | | **Client ID** | ✓ | The ID issued to your OAuth client during registration. | | **Client secret** | ✓ | The secret issued to your OAuth client during registration. | | **Audience** | ✗ | The intended recipient of the token, usually in a format like `https://api-a.example.com`. Check API docs for the format. | | **Prompt** | ✗ | Determines if the user is prompted for consent. To skip the prompt and perform silent authentication, set to `none` | | **Scopes** | ✗ | The scopes that you want to request authorization for. These must be separated by spaces. | | **Client authentication** | ✗ | If the `Client ID` and `Client secret` will be sent to the `Token URL` in the body or as a basic auth header. | | **Send state** | ✗ | When checked, an opaque value will be added to the Authorization URL call and used on redirect to prevent CSRF attacks. | 4. If available, select **Share access token across all users** to use the same access token for all clients. If selected, click the **Connect** button to initiate the authorization flow. If the shared token option is not selected, integrations with this auth method cannot be used in Workflows or Scheduled Jobs 5. Use the [`oauth` object](#the-oauth-object) in **Headers** or **Params** to define how the token response is used. For example, to send the access token to subsequent requests in the Authorization header, set: ![oauth.token referenced in Authorization header](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-object-reference.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=8485edb48dd3879c090c49fd4159bb2e) If you're not using the shared token option, this flow will be initiated in the user's browser when an API using this Integration executes. After an access token is retrieved it is cached for future use. If a refresh token is provided, Superblocks will refresh the token when it expires without reprompting the user to authenticate. Learn more about [token caching and refresh](#token-caching-and-refresh) > [accordion] Full specification > > In these examples, replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). > > #### 1. `GET` Authorization URL > > Prompt user to log in and get an authorization code\ > \\ > > ##### Request > > ```bash theme={null} > GET {authorization_url}? > client_id={client_id}& > audience={audience}& > scope={scopes}& > response_type=code& > redirect_uri=https%3A%2F%2F{tenant}.superblocks.com%2Foauth%2Fcallback& > state=STATE > ``` > > ##### Expected Response > > ```bash theme={null} > HTTP/1.1 302 Found > Location: https://{tenant}.superblocks.com/oauth/callback?code=AUTHORIZATION_CODE&state=STATE > ``` > > #### 2. `POST` Token URL > > Exchange authorization code with authorization server for an access token\ > \\ > > ##### Request > > If **Client authentication** is set to **Send client credentials in body** > > ```bash theme={null} > curl --request POST \ > --url '{token_url}' \ > --header 'Accept: application/json' \ > --header 'Content-Type: application/x-www-form-urlencoded' \ > --data-urlencoded 'grant_type=authorization_code' \ > --data-urlencoded 'client_id={client_id}' \ > --data-urlencoded 'client_secret={client_secret}' \ > --data-urlencoded 'code=AUTHORIZATION_CODE' \ > --data-urlencoded 'redirect_uri=https://{tenant}.superblocks.com/oauth/callback' > ``` > > If **Client authentication** is set to **Send as basic auth header** > > ```bash theme={null} > curl --request POST \ > --url '{token_url}' \ > --header 'Accept: application/json' \ > --header 'Authorization: Basic {Base64-encoded client_id and client_secret}' \ > --header 'Content-Type: application/x-www-form-urlencoded' \ > --data-urlencoded 'grant_type=authorization_code' \ > --data-urlencoded 'code=AUTHORIZATION_CODE' \ > --data-urlencoded 'redirect_uri=https://{tenant}.superblocks.com/oauth/callback' > ``` > > ##### Expected Response > > ```bash theme={null} > HTTP/1.1 200 OK > Content-Type: application/json > { > "token_type": "Bearer", > "expires_in": 86400, > "access_token": "eyJz93a...k4laUWw", > "refresh_token": "GEbRxBN...edjnXbL", > "id_token": "eyJ0XAi...4faeEoQ" > } > ``` ### On-Behalf-Of Token Exchange This flow can only be used by organizations with an OIDC-based [Single Sign-On](/admin/org-administration/auth/single-sign-on) flow configured. If you're not sure how you SSO provider is configured, contact support for assistance. The On-Behalf-Of Token Exchange is a delegated access flow that lets a client exchange an access token received from an upstream client for a new token by interacting with an authorization server. In the case of Superblocks, this flows lets Superblocks exchange access tokens issued when a user logs in via an IdP, with an authorization server to get an access token to send to downstream servers. For example, let's say your backend API is secured using tokens issued by Okta. This flow allows you to exchange a user's Superblocks access token with an Okta authorization server to obtain access tokens for your backend API without requiring the user to log in again. ![On-Behalf-Of Token Exchange flow sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/on-behalf-of-token-exchange.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=eca8c57895f0f9ca07ba92ca9e9aa00a) To use the on-behalf-of token exchange flow: 1. In the Integration configuration select **OAuth2 - On-Behalf-Of Token Exchange** 2. Select a **Subject token source** * **Login Identity Provider**: Use the token issued to Superblocks when users logged in as the `subject_token` * **Static Token**: Provide a static token to use as the `subject_token` If you choose **Login Identity Provider**, this integration can't be used in Workflows or Scheduled Jobs since it will require a user's JWT to authenticate 3. Specifying the following configuration values: | Field | Required | Description | | - | - | - | | **Subject token type** | ✗ | The type of security token provided in the **Static token** field or by your IdP when logging into Superblocks. Defaults to `urn:ietf:params:oauth:token-type:access_token` | | **Token URL** | ✓ | The token endpoint of the authorization server, used to exchange an authorization code for an access token | | **Client ID** | ✓ | The ID issued to your OAuth client during registration. | | **Client secret** | ✓ | The secret issued to your OAuth client during registration. | | **Audience** | ✗ | The intended recipient of the token, usually in a format like `https://api-a.example.com`. Check API docs for the format. | | **Scopes** | ✗ | The scopes that you want to request authorization for. These must be separated by spaces. | 4. Use the [`oauth` object](#the-oauth-object) in **Headers** or **Params** to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set: ![oauth.token referenced in Authorization header](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-object-reference.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=8485edb48dd3879c090c49fd4159bb2e) When an API with this auth type executes, the Superblocks Agent will send a request to the `/token` endpoint of the authorization server, including in the request a `subject_token` based on the source selected. After an access token is returned, it is cached to improve future API performance. Once the token expires, Superblocks reinitiates the token exchange for you. If you use your IdP as the source of the subject token and the IdP token has expired, the user will be prompted to log in again to obtain a new subject token. Learn more about [token caching and refresh](#token-caching-and-refresh) > [accordion] Full specification > > #### `POST` Token URL > > Exchanging user's JWT issued at login or static token for new access token\ > \\ > > ##### Request > > ```bash theme={null} > curl --location --request POST \ > --url '{token_url}' \ > --header 'Accept: application/json' \ > --header 'Content-Type: application/x-www-form-urlencoded' \ > --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \ > --data-urlencode 'client_id={client_id}' \ > --data-urlencode 'client_secret={client_secret}' \ > --data-urlencode 'subject_token_type={subject_token_type or urn:ietf:params:oauth:token-type:access_token}' \ > --data-urlencode 'subject_token={current user JWT issued at login or static token}' \ > --data-urlencode 'scope={scopes}' \ > --data-urlencode 'audience={audience}' > ``` > > ##### Expected Response > > ```bash theme={null} > HTTP/1.1 200 OK > Content-Type: application/json > { > "token_type": "Bearer", > "expires_in": 3600, > "access_token": "eyJraWQiOiJR.....ajXZIk3GryDPC8OIhLsQ", > "scope": "customScope", > "issued_token_type": "urn:ietf:params:oauth:token-type:access_token" > } > ``` ### Client Credential Client credential grant types are typically not used to access user data but instead for machine-to-machine communication. When an API executes, Superblocks exchanges OAuth client information with the authorization server to get an access token. That token is then used in the subsequent request. ![Client credential flow sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-client-creds.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=c305e969076b503c56b19f1ad6da5b1f) To use the client credential flow: 1. In the Integration configuration select **OAuth2 - Client Credentials Grant** 2. Specify the following configuration values: | Field | Required | Description | | - | - | - | | **Token URL** | ✓ | The token endpoint of the authorization server, used to exchange an authorization code for an access token. **Note**: this value is not required for public APIs and is set by Superblocks | | **Client ID** | ✓ | The ID issued to your OAuth client during registration. | | **Client secret** | ✓ | The secret issued to your OAuth client during registration. | | **Audience** | ✗ | The intended recipient of the token, usually in a format like `https://api-a.example.com`. Check API docs for the format. | | **Scopes** | ✗ | The scopes that you want to request authorization for. These must be separated by spaces. | 3. Use the [`oauth` object](#the-oauth-object) in **Headers** or **Params** to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set: ![oauth.token referenced in Authorization header](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-object-reference.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=8485edb48dd3879c090c49fd4159bb2e) After an access token is retrieved it is cached to improve future API performance. Once the token expires, Superblocks reinitiates the token exchange to get a new token. Learn more in [token caching and refresh](#token-caching-and-refresh). > [accordion] Full specification > > #### `POST` Token URL > > Get an access token using the client ID and client secret\ > \\ > > ##### Request > > ```bash theme={null} > curl --request POST \ > --url {token_url} \ > --header 'Accept: application/json' \ > --header 'Authorization: Basic {Base64-encoded client_id and client_secret}' \ > --header 'Cache-Control: no-cache' \ > --header 'Content-Type: application/x-www-form-urlencoded' \ > --data-urlencoded 'grant_type=client_credentials' \ > --data-urlencoded 'scope={scopes}' \ > --data-urlencoded 'audience={audience}' > ``` > > ##### Expected Response > > ```bash theme={null} > HTTP/1.1 200 OK > Content-Type: application/json > { > "token_type": "Bearer", > "expires_in": 86400, > "access_token": "eyJhbG[...]1LQ", > "scope": "customScope" > } > ``` ### Implicit Implicit flows are primarily intended for browser-based apps that don't support Cross-Origin Resource Sharing (CORS) or lack modern cryptography APIs. In this flow, the client doesn't make a request to a `/token` endpoint, but instead receives the access token in the redirect from the `/authorize` endpoint. This flow is less secure, it's recommended to use [Authorization Code](#authorization-code) if available. Because it is intended for less-trusted clients, it doesn't support refresh tokens. ![Implicit flow sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-implicit.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=b19194b0807e4da23144d6bfc414740a) To use the implicit flow: 1. In the Integration configuration select **OAuth2 - Implicit Grant** 2. Copy the **Callback URL** provided and add it to the **Allowed Callback URLs** of your OAuth client 3. Specify the following configuration values: | Field | Required | Description | | - | - | - | | **Authorization URL** | ✓ | The endpoint users will be redirected to in order to log in and authorize access. **Note**: this value is not required for public APIs and is set by Superblocks | | **Client ID** | ✓ | The ID issued to your OAuth client during registration. | | **Audience** | ✗ | The intended recipient of the token, usually in a format like `https://api-a.example.com`. Check API docs for the format. | | **Prompt** | ✗ | Determines if user is prompted for consent. To skip the prompt and perform silent authentication, set to `none` | | **Scopes** | ✗ | The scopes that you want to request authorization for. These must be separated by spaces. | 4. Use the [`oauth` object](#the-oauth-object) in **Headers** or **Params** to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set: ![oauth.token referenced in Authorization header](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-object-reference.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=8485edb48dd3879c090c49fd4159bb2e) This flow is initiated in the user's browser when an API using this Integration executes. After an access token is returned, it is saved as an HTTP-Only secure cookie in the user's browser. Once the token expires, Superblocks will reprompt the user to log in. Learn more about [token caching](#token-caching-and-refresh). Since a user must log in, integrations that use this auth method can't be used in Workflows or Scheduled Jobs > [accordion] Full specification > > In these examples, replace `{tenant}` with the value for your instance from [Instance URLs](/enterprise/instance-urls). > > #### `GET` Authorization URL > > ##### Request > > ```bash theme={null} > GET {authorization_url}? > client_id={client_id}& > scope={scopes}}& > audience={audience}& > response_type=token& > redirect_uri=https%3A%2F%2F{tenant}.superblocks.com%2Foauth%2Fcallback& > state=STATE& > nonce=NONCE > ``` > > ##### Expected Response > > ```bash theme={null} > HTTP/1.1 302 Found > Location: https://{tenant}.superblocks.com/oauth/callback#access_token=TOKEN& > state=STATE& > token_type=Bearer& > scope={scopes}& > expires_in=SECONDS > ``` ### Password Grant (Legacy) The Password Grant (Legacy) flow, sometimes referred to as a Resource Owner Password flow, is an OAuth flow intended for highly-trusted apps that can't do redirects. With this flow, either the Integration Configurer or an end-user will provide a username and password. These credentials will be sent to the `/token` endpoint, which then responds with a short-lived access token. ![Password grant sequence diagram](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-resource-owner-password.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=4695e165fb3df0cbf02c82034065819a) To use the password grant (legacy) flow: 1. In the Integration configuration select **OAuth2 - Password Grant (Legacy)** 2. Specify the following configuration values: | Field | Required | Description | | - | - | - | | **Token URL** | ✓ | The token endpoint of the authorization server, used to exchange an authorization code for an access token. **Note**: this value is not required for public APIs and is set by Superblocks | | **Client ID** | ✓ | The ID issued to your OAuth client during registration. | | **Client secret** | ✓ | The secret issued to your OAuth client during registration. | | **Audience** | ✗ | The intended recipient of the token, usually in a format like `https://api-a.example.com`. Check API docs for the format. | 3. If you want to use shared credentials, check **Share username/password across all users** and provide the shared username & password If the shared credentials option is not selected, integrations with this auth method cannot be used in Workflows or Scheduled Jobs 4. Use the [`oauth` object](#the-oauth-object) in **Headers** or **Params** to define how the token response should be sent to the resource server. For example, to send the access token as an Authorization header, set: ![oauth.token referenced in Authorization header](https://mintcdn.com/superblocks/TqcwM8ac6ozIt6Fv/images/integrations/authentication/oauth-object-reference.png?fit=max\&auto=format\&n=TqcwM8ac6ozIt6Fv\&q=85\&s=8485edb48dd3879c090c49fd4159bb2e) If shared credentials aren't used, users will be prompted for a username/password before APIs can execute. Once an access token is returned, it is saved as an HTTP-Only secure cookie in the browser. Superblocks will prompt the user to log back in when the token expires. Learn more about [token caching](#token-caching-and-refresh). > [accordion] Full specification > > #### `POST` Token URL > > ###### Request > > ```bash theme={null} > curl --request POST \ > --url {token_url} \ > --header 'Accept: application/json' \ > --header 'Content-Type: application/x-www-form-urlencoded' \ > --data-urlencoded 'grant_type=password' \ > --data-urlencoded 'client_id={client_id}' \ > --data-urlencoded 'client_secret={client_secret}' \ > --data-urlencoded 'username=USERNAME' \ > --data-urlencoded 'password=PASSWORD' \ > --data-urlencoded 'scope={scopes}' \ > --data-urlencoded 'audience={audience} \ > ``` > > ##### Expected Response > > ```bash theme={null} > HTTP/1.1 200 OK > Content-Type: application/json > { > "token_type": "Bearer", > "expires_in": 86400, > "access_token": "eyJz93a...k4laUWw", > "id_token": "eyJhb[...]yosFQ", > "scope": "customScope" > } > ``` ## The **`oauth`** object The results of an OAuth 2.0 exchange can be referenced in your Integration configuration using the `oauth` object. The `oauth` object has the following properties. | Property | Datatype | Description | Full Path | | - | - | - | - | | `token` | `STRING` | The access token returned by the OAuth flow | `oauth.token` | | `idToken` | `STRING` | The ID token returned by the OAuth flow if available | `oauth.idToken` | | `tokenDecoded ` | `OBJECT` | A JSON object of the decoded ID token claims | `oauth.tokenDecoded` | ## Token caching and refresh This section includes specifics on how OAuth 2.0 access tokens are handled. For more information on sessions management see our guide on [Credential & Session Management](/integrations/auth/credential-and-session-management) ### How tokens are cached OAuth 2.0 flows result in an access token that is used when making requests to a service. Once an access token is obtained through an OAuth flow, it is cached by Superblocks based on both the OAuth client generating the token (`client_id`, `audience`, `scopes`, etc) and the user for whom the token was issued. Because tokens are cached based on the OAuth client, you can use the same OAuth client across integrations. If a user already has a cached token for the OAuth client from a different integration, Superblocks will use that cached token, even when executing requests with integrations the user has never used. Caching reduces the need for repeated authentication requests, improving performance and the user experience of your Superblocks app. ### Cache locations Tokens are either cached in the user's browser or Superblocks Cloud server depending on the nature of the token generated. See the table below to understand where tokens are cached based on the OAuth 2.0 flow. Tokens are only ever cached in the browser if the OAuth 2.0 flow is a high-trust flow that exposes tokens to the client. These tokens are stored in HTTP-Only Secure cookies that are not accessible to client-side JavaScript. | OAuth 2.0 Flow | Shared Credentials | Cache location | | - | - | - | | [Authorization Code](#authorization-code) | ✗ | Server-side | | [Authorization Code](#authorization-code) | ✓ | Server-side | | [On-Behalf-Of Token Exchange](#on-behalf-of-token-exchange) | ✗ | Server-side | | [On-Behalf-Of Token Exchange](#on-behalf-of-token-exchange) | ✓ | Server-side | | [Client Credential](#client-credential) | | Server-side | | [Implicit](#implicit) | | Client-side | | [Password Grant (Legacy)](#password-grant-legacy) | ✗ | Client-side | | [Password Grant (Legacy)](#password-grant-legacy) | ✓ | Server-side | ### Refreshing access tokens During certain OAuth 2.0 flows, the authorization server returns a long-lived refresh token. When refresh token is present, Superblocks will automatically use it to refresh expired access tokens in the background before executing requests. The refreshed access token is then [cached](#how-tokens-are-cached) for future use. The following OAuth methods support token refresh flows: * [Authorization Code](#authorization-code) * [Password Grant (Legacy)](#password-grant-legacy) # Airtable Source: https://docs.superblocks.com/integrations/integrations-library/airtable ## Setting up Airtable **Airtable** **Airtable connected!** You can now use [Clark to build](/building-with-clark) with Airtable. ## Use Airtable in APIs Once your Airtable integration is created, you can start calling Airtable actions in Superblocks APIs. In addition to generic HTTP requests, Airtable supports the following actions. ### Supported actions ### Example usage Airtable's API returns embedded fields for each record. To flatten the response so each field is a top level key to be used as a table column header in Superblocks, add the following JavaScript step after a call to `List records`: ```js theme={null} return .output.records.map(item => item.fields); ``` # Anthropic Source: https://docs.superblocks.com/integrations/integrations-library/anthropic ## Setting up Anthropic **Anthropic** **Anthropic connected!** You can now use [Clark to build](/building-with-clark) with Anthropic. ## Use Anthropic in APIs Once your Anthropic integration is created, you can start calling Anthropic actions in Superblocks APIs. In addition to generic HTTP requests, Anthropic supports the following actions. ### Supported actions # Asana Source: https://docs.superblocks.com/integrations/integrations-library/asana ## Setting up Asana **Asana** **Asana connected!** You can now use [Clark to build](/building-with-clark) with Asana. ## Use Asana in APIs Once your Asana integration is created, you can start calling Asana actions in Superblocks APIs. In addition to generic HTTP requests, Asana supports the following actions. ### Supported actions # Amazon Athena Source: https://docs.superblocks.com/integrations/integrations-library/aws-athena Amazon Athena serves as an interactive query service, facilitating fast analysis of data directly within Amazon S3. Connect Superblocks to your Athena instance to access your S3 data and harness the power of SQL to execute ad-hoc queries with speed. ## Setting up Amazon Athena ### 1. Add integration Select **Amazon Athena** from the [integrations page](https://app.superblocks.com/integrations/athena). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Database Name | ✓ | Name of the database in Amazon Athena to interact with | | Region | ✓ | AWS region where the database is hosted, e.g. *us-east-1* | | Access Key ID | ✓ | [Access key ID](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | | Secret Key | ✓ | [Secret access key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | | Workgroup Name | ✗ | Name of the [Workgroup](https://docs.aws.amazon.com/athena/latest/ug/workgroups-create-update-delete.html) used for permissions | | S3 Output Location | ✗ | The [query result location](https://docs.aws.amazon.com/athena/latest/ug/querying.html#query-results-specify-location) to use in Athena | | IAM Role ARN | ✗ | ARN of the role for Superblocks to assume for accessing Athena resources | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Amazon Athena connected!** You can now use [Clark to build](/building-with-clark) with Amazon Athena. ## Creating Amazon Athena steps Connect to your Athena integration from Superblocks by creating steps in Application APIs, Workflows and Scheduled Jobs. You can configure a Superblocks Athena integration with read only, read/write, or write only IAM Users. You can then configure a Superblocks Athena step to read from a database, as well as modify/delete data. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Amazon DynamoDB Source: https://docs.superblocks.com/integrations/integrations-library/aws-dynamodb Build apps with read and write access to a DynamoDB database ## Setting up Amazon DynamoDB ### 1. Add integration Select **DynamoDB** from the [integrations page](https://app.superblocks.com/integrations/dynamodb). ### 2. Configure settings Fill out the form with the following settings: > [tab] Cloud > > | Setting | Required | Description | > | - | - | - | > | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | > | Region | ✓ | [AWS region](https://docs.aws.amazon.com/general/latest/gr/ddb.html) where DynamoDB is hosted, e.g. *us-east-1* | > | Access Key ID | ✓ | [Access key ID](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | Secret Key | ✓ | [Secret access key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | IAM Role ARN | ✗ | ARN of the role for Superblocks to assume for accessing DynamoDB resources | > [tab] Hybrid or Cloud-Prem > > | Setting | Required | Description | > | - | - | - | > | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | > | Auth Type | ✓ | Choose between:
  • **Access Key** - Use access key ID and secret access key authorization
  • **Token File** - Use [Service Account Token Volume Projection](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to authorize your data plane to connect to your DynamoDB databases.
  • **EC2 Instance Metadata** - Use [EC2 Instance Metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) to authorize your data plane to connect to your DynamoDB databases. If you are using [Kube2Iam](https://github.com/jtblin/kube2iam), you would select this option.
| > | Region | ✓ | If **Auth Type** is Access Key: [AWS region](https://docs.aws.amazon.com/general/latest/gr/ddb.html) where DynamoDB is hosted, e.g. *us-east-1* | > | Access Key ID | ✓ | If **Auth Type** is Access Key: [Access key ID](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | Secret Key | ✓ | If **Auth Type** is Access Key: [Secret access key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | IAM Role ARN | ✗ | ARN of the role for Superblocks to assume for accessing DynamoDB resources | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Amazon DynamoDB connected!** You can now use [Clark to build](/building-with-clark) with Amazon DynamoDB. ## Creating Amazon DynamoDB steps Connect to your DynamoDB integration from Superblocks by creating steps in Application APIs, Workflows and Scheduled Jobs. Steps can be configured to perform any of the actions below. Configure your IAM policy for the integration accordingly depending on the desired permissions. ``` "dynamodb:BatchWriteItem", "dynamodb:CreateTable", "dynamodb:DeleteItem", "dynamodb:DeleteTable", "dynamodb:DescribeTable", "dynamodb:ExecuteStatement", "dynamodb:ExecuteTransaction", "dynamodb:GetItem", "dynamodb:ListTables", "dynamodb:ListTagsOfResource", "dynamodb:PutItem", "dynamodb:Query", "dynamodb:Scan", "dynamodb:TagResource", "dynamodb:UpdateItem", "dynamodb:UpdateTable" ``` ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Amazon Redshift Source: https://docs.superblocks.com/integrations/integrations-library/aws-redshift Build apps with read and write access to a Redshift database ## Setting up Amazon Redshift ### 1. Add integration Select **Redshift** from the [integrations page](https://app.superblocks.com/integrations/redshift). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Domain name of Redshift instance to connect to | | Port | ✓ | Port to use when connecting to Redshift | | Schema | ✗ | The schema to connect to | | Database Name | ✓ | Name of database to connect to | | Database Username | ✓ | Username to use to connect | | Database Password | ✓ | Password for database username | | Enable SSL | ✗ | Connect via SSL if selected | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Amazon Redshift connected!** You can now use [Clark to build](/building-with-clark) with Amazon Redshift. ## Creating Amazon Redshift steps Connect to your Redshift integration from Superblocks by creating steps in Application APIs, Workflows and Scheduled Jobs. You can configure a Superblocks Redshift integration with read only, read/write, or write only users. You can then configure a Superblocks Redshift step to read from a database, as well as modify/delete data. To get started, enter your SQL query into the text area of the Redshift step. Then click "Run" to see the Result and Executed SQL statement below. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Amazon S3 Source: https://docs.superblocks.com/integrations/integrations-library/aws-s3 Build apps that can list, read, delete, and upload files in S3 ## Setting up Amazon S3 ### 1. Add integration Select **Amazon S3** from the [integrations page](https://app.superblocks.com/integrations/s3). ### 2. Configure settings Fill out the form with the following settings: > [tab] Cloud > > | Setting | Required | Description | > | - | - | - | > | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | > | Region | ✓ | [AWS region](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region) where the S3 bucket is hosted, e.g. *us-east-1* | > | Access Key ID | ✓ | [Access key ID](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | Secret Key | ✓ | [Secret access key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | IAM Role ARN | ✗ | ARN of the role for Superblocks to assume for accessing S3 resources | > [tab] Hybrid or Cloud-Prem > > | Setting | Required | Description | > | - | - | - | > | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | > | Auth Type | ✓ | Choose between:
  • **Access Key** - Use access key ID and secret access key authorization
  • **Token File** - Use [Service Account Token Volume Projection](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to authorize your data plane to connect to your S3 Buckets
  • **EC2 Instance Metadata** - Use [EC2 Instance Metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) to authorize your data plane to connect to your S3 Buckets. If you are using [Kube2Iam](https://github.com/jtblin/kube2iam), you would select this option.
| > | Region | ✓ | If **Auth Type** is Access Key: [AWS region](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region) where the S3 bucket is hosted, e.g. *us-east-1* | > | Access Key ID | ✓ | If **Auth Type** is Access Key: [Access key ID](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | Secret Key | ✓ | If **Auth Type** is Access Key: [Secret access key](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) for your AWS account | > | IAM Role ARN | ✗ | ARN of the role for Superblocks to assume for accessing S3 resources | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Amazon S3 connected!** You can now use [Clark to build](/building-with-clark) with Amazon S3. ## Creating Amazon S3 steps Connect to your S3 integration from Superblocks by creating steps in Application APIs, Workflows, and Scheduled Jobs. An S3 step can perform the following actions: * Delete Files * Generate presigned URL * List bucket objects * List buckets * Read file * Upload file * Upload multiple files * List files (deprecated) # Bitbucket Source: https://docs.superblocks.com/integrations/integrations-library/bitbucket ## Setting up Bitbucket **Bitbucket** **Bitbucket connected!** You can now use [Clark to build](/building-with-clark) with Bitbucket. ## Use Bitbucket in APIs Once your Bitbucket integration is created, you can start calling Bitbucket actions in Superblocks APIs. In addition to generic HTTP requests, Bitbucket supports the following actions. ### Supported actions # Box Source: https://docs.superblocks.com/integrations/integrations-library/box ## Setting up Box **Box** **Box connected!** You can now use [Clark to build](/building-with-clark) with Box. ## Use Box in APIs Once your Box integration is created, you can start calling Box actions in Superblocks APIs. In addition to generic HTTP requests, Box supports the following actions. ### Supported actions # CircleCI Source: https://docs.superblocks.com/integrations/integrations-library/circleci ## Setting up CircleCI **CircleCI** **CircleCI connected!** You can now use [Clark to build](/building-with-clark) with CircleCI. ## Use CircleCI in APIs Once your CircleCI integration is created, you can start calling CircleCI actions in Superblocks APIs. In addition to generic HTTP requests, CircleCI supports the following actions. ### Supported actions # CockroachDB Source: https://docs.superblocks.com/integrations/integrations-library/cockroachdb Build apps with read and write access to a CockroachDB database ## Setting up CockroachDB ### 1. Add integration Select **CockroachDB** from the [integrations page](https://app.superblocks.com/integrations/cockroachdb). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Hostname or IP address to connect to | | Port | ✓ | Port to use when connecting to CockroachDB | | Database Name | ✓ | Name of database to connect to | | Database Username | ✓ | Username to use to connect | | Database Password | ✓ | Password for database username | | Enable SSL | ✗ | Connect via SSL if selected | | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** if selected | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **CockroachDB connected!** You can now use [Clark to build](/building-with-clark) with CockroachDB. ## Creating CockroachDB steps Connect to your CockroachDB integration from Superblocks by creating steps in Application APIs, Workflows and Scheduled Jobs. You can configure a Superblocks CockroachDB integration with read only, read/write, or write only users. You can then configure a Superblocks CockroachDB step to read from a database, as well as modify/delete data. To get started, enter your SQL query into the text area of the CockroachDB step. Then click "Run" to see the Result and Executed SQL statement below. ![See the results of a CockroachDB query](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/integrations-library/cockroachdb/cockroachdb_create_an_api_step.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=ec32aa46627b6141f456edeb5355c5dc) ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [CockroachDB's troubleshooting guide](https://www.cockroachlabs.com/docs/stable/error-handling-and-troubleshooting.html). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Cohere Source: https://docs.superblocks.com/integrations/integrations-library/cohere ## Setting up Cohere **Cohere** **Cohere connected!** You can now use [Clark to build](/building-with-clark) with Cohere. ## Use Cohere in APIs Once your Cohere integration is created, you can start calling Cohere actions in Superblocks APIs. In addition to generic HTTP requests, Cohere supports the following actions. ### Supported actions # Confluence Cloud Source: https://docs.superblocks.com/integrations/integrations-library/confluence ## Setting up Confluence Cloud **Confluence Cloud** **Confluence Cloud connected!** You can now use [Clark to build](/building-with-clark) with Confluence Cloud. ## Use Confluence Cloud in APIs Once your Confluence Cloud integration is created, you can start calling Confluence Cloud actions in Superblocks APIs. In addition to generic HTTP requests, Confluence Cloud supports the following actions. ### Supported actions # Azure CosmosDB Source: https://docs.superblocks.com/integrations/integrations-library/cosmosdb Build apps with read and write access to a CosmosDB database ## Setting up CosmosDB ### 1. Add integration Select **CosmosDB** from the [integrations page](https://app.superblocks.com/integrations/cosmosdb). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Hostname or IP address to connect to | | Port | ✓ | Port to use when connecting to CosmosDB | | Database ID | ✓ | ID of database to connect to | | Master Key | ✓ | The Master Key to access the database | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If you're using Superblocks Cloud, you may need to allowlist Superblocks IP addresses to connect to your database. Learn more about [Superblocks IP addresses](/enterprise/security/overview#ip-addresses) (not necessary when [self-hosting the data plane](/enterprise/hybrid-architecture/overview)). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **CosmosDB connected!** You can now use [Clark to build](/building-with-clark) with CosmosDB. ## Creating CosmosDB steps When using CosmosDB steps, there are 2 options: 1. [SQL queries](#sql-queries) 2. [Single object actions](#single-object-actions) ### SQL queries Write SQL queries to interact with your CosmosDB instance directly. ### Single object actions Use **single object actions** to perform CRUD actions on a single object. Pass in an object of data in the **Item Body**. Actions supported include: * Create a single object * Read a single object * Upsert a single object * Replace a single object * Delete a single object ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [common CosmosDB connection issues](https://learn.microsoft.com/en-us/azure/cosmos-db/postgresql/howto-troubleshoot-common-connection-issues). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Couchbase Source: https://docs.superblocks.com/integrations/integrations-library/couchbase Couchbase is a NoSQL database management system that is designed for high-performance, scalability, and flexibility. Integrate Couchbase with Superblocks to build applications and other custom internal tools on top of your Couchbase documents. ## Setting up Couchbase ### Create Cluster Access Credentials To connect to Couchbase, you'll need a `username` and `password`. For self-managed clusters, refer to Couchbase's guide on how to [Connect a Self-Managed Cluster](https://docs.cloud.couchbase.com/cloud/BETA/clusters/connect-self-managed-cluster.html). For Couchbase Cloud, use the following instructions to create Cluster Access Credentials. 1. Navigate to your Couchbase Cluster 2. Click **Settings** 3. In the navigation menu, click **Cluster Access** 4. Click **Create Cluster Access** 5. Specify a cluster access name and secret, these will serve as the `username` and `password` when connecting 6. Specify the buckets and scope the credentials should have access to 7. Once you have finished making the desired configurations, click **Create Cluster Access** Learn more about how to [Configure Cluster Access Credentials](https://docs.couchbase.com/cloud/clusters/manage-database-users.html#create-database-credentials) ### Set up allowed IP Addresses If you're using Superblocks Cloud, add [Superblocks' IPs](/enterprise/security/overview#ip-addresses) as allowed IPs for your cluster. Learn how to in Couchbase's guide on [Configuring Allowed IP Addresses](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html). ### Add integration 1. In the web app, navigate to the **Integrations** page 2. Click the **Couchbase** tile 3. **Name** the integration 4. Fill out the connection configuration as follows: | Field | Required | Description | | - | - | - | | URI | ✓ | Comma-delimited list of IP addresses and/or hostnames to connect to. Learn more about the format of Couchbase connection strings in Couchbase's guide on [Managing Connections](https://docs.couchbase.com/nodejs-sdk/current/howtos/managing-connections.html). | | Username | ✓ | Cluster access credential name or username. | | Password | ✓ | Cluster access credential secret or cluster password. | 5. Optionally, add more configurations to set credentials for [different environments](/development-lifecycle/build/data-tags) 6. Click **Test Connection** to check that Superblocks can connect 7. Click **Create** **Couchbase connected!** You can now use [Clark to build](/building-with-clark) with Couchbase. ## Use Couchbase in APIs Once your Couchbase integration is created, you can start using Couchbase actions in Superblocks APIs. > [tab] Raw query > > Write [SQL++ queries](https://docs.couchbase.com/server/current/n1ql/n1ql-intro/queriesandresults.html) to issue queries to Couchbase. > > ![Query Couchbase with SQL++](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/integrations-library/couchbase/couchbase_query.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=d877693c2257d5904c57abc27b71b5db) > [tab] Insert Item > > Insert new documents into Couchbase collections with the **Insert item** action. > > ![Insert item into Couchbase](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/integrations-library/couchbase/couchbase_insert_item.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=819ce78e75f5905a1a382d4404236cf0) > [tab] Get Item > > Get a single document from your Couchbase collection with the **Get item** action. > > ![Get item from Couchbase](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/integrations-library/couchbase/couchbase_get_item.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=423ef704b1e93af602d1093b30a19981) > [tab] Remove Item > > Remove individual documents from a Couchbase collection with the **Remove item** action. > > ![Remove item from Couchbase](https://mintcdn.com/superblocks/G-ib4vcIpqKg18lL/images/integrations/integrations-library/couchbase/couchbase_remove_item.png?fit=max\&auto=format\&n=G-ib4vcIpqKg18lL\&q=85\&s=9980d369ca6f79a95c8ed115400457d4) # Databricks SQL Warehouse Source: https://docs.superblocks.com/integrations/integrations-library/databricks Databricks SQL Warehouse is a powerful data analytics and lakehouse platform that enables organizations to unify data engineering, data science, and business analytics at scale. Integrate Databricks SQL Warehouse with Superblocks to build internal tools and workflows that query, analyze, and update your Databricks data, empowering your team to automate processes, gain insights, and accelerate decision-making. [https://www.youtube.com/embed/f\_cjUVluqOc](https://www.youtube.com/embed/f_cjUVluqOc) ## Setting up Databricks SQL Warehouse If you're using Superblocks Cloud, you may need to allowlist Superblocks IP addresses to connect to your database. Learn how to configure this in Databricks' guide on [Configuring IP access lists](https://docs.databricks.com/aws/en/security/network/front-end/ip-access-list-workspace). Alternatively, use the Superblocks Hybrid or Cloud-Prem architectures to keep your data within your VPC. ### Configure authentication To access your Databricks warehouse, you'll need to authenticate using a Databricks account. Superblocks provides several different ways to authenticate. See the Databricks documentation below for how to configure your preferred authentication method. | Method | Description | | - | - | | [Personal access token (PAT)](https://docs.databricks.com/aws/en/dev-tools/auth/pat) | Use a short or long-lived access token for a user or service principal. | | [Machine-to-machine OAuth](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) | Configure OAuth client credentials for a service principal. Superblocks will exchange the client credentials with Databricks to retrieve a short-lived OAuth token. | | [OAuth token federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) | Use OAuth tokens issued by your identity provider when users log in to Superblocks to authenticate with Databricks using the authenticated user's permissions. | ### Add integration 1. In the web app, navigate to the [Integrations](https://app.superblocks.com/integrations) page 2. Click **Add integration** 3. Search for **Databricks SQL Warehouse** and select it from the list of available integrations 4. **Name** the integration 5. Fill out the integration configuration as follows: > [tab] Personal access token based connection > > | Field | Required | Description | > | - | - | - | > | Host | ✓ | Databricks instance host name | > | Port | ✓ | Port to use when connecting to your warehouse | > | HTTP Path | ✓ | HTTP path either to a DBSQL endpoint (e.g. `/sql/1.0/endpoints/1234567890abcdef`) or to a DBR interactive cluster (e.g. `/sql/protocolv1/o/1234567890123456/1234-123456-slid123`) | > | Default catalog | ✗ | An optional initial catalog to use | > | Default schema | ✗ | An optional initial schema to use | > | Access token | ✓ | Databricks personal access token | > [tab] Machine-to-machine OAuth > > | Field | Required | Description | > | - | - | - | > | Host | ✓ | Databricks instance host name | > | Port | ✓ | Port to use when connecting to your warehouse | > | HTTP Path | ✓ | HTTP path either to a DBSQL endpoint (e.g. `/sql/1.0/endpoints/1234567890abcdef`) or to a DBR interactive cluster (e.g. `/sql/protocolv1/o/1234567890123456/1234-123456-slid123`) | > | Default catalog | ✗ | An optional initial catalog to use | > | Default schema | ✗ | An optional initial schema to use | > | OAuth client ID | ✓ | Client ID associated with your service principal | > | OAuth client secret | ✓ | Client secret associated with your service principal | > [tab] OAuth token federation > > | Field | Required | Description | > | - | - | - | > | Host | ✓ | Databricks instance host name | > | Port | ✓ | Port to use when connecting to your warehouse | > | HTTP Path | ✓ | HTTP path either to a DBSQL endpoint (e.g. `/sql/1.0/endpoints/1234567890abcdef`) or to a DBR interactive cluster (e.g. `/sql/protocolv1/o/1234567890123456/1234-123456-slid123`) | > | Default catalog | ✗ | An optional initial catalog to use | > | Default schema | ✗ | An optional initial schema to use | > | Subject token source | ✓ | Select **Login identity provider** to use the access token issued to Superblocks when users log in via SSO, or provide a **Static token**. | > | Token URL | ✓ | Databricks token URL. Choose a URL format based on the federation policy you previously configured. **Workspace identity federation** `https:///oidc/v1/token` **Account-wide token federation** `https:///oidc/accounts//v1/token` | > | Service Principal UUID | ✗ | Only required if using [Workload identity federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation-policy). The service principal client ID to authenticate as. | > > **Login identity provider** token source is only supported for Enterprise organizations with OIDC-based [Single Sign-On](/admin/org-administration/auth/single-sign-on) configured. If you're not sure how your SSO provider is configured, contact support for assistance. 6. Optionally, add more configurations to set credentials for [different environments](/development-lifecycle/build/data-tags) 7. Click **Test Connection** to check that Superblocks can connect to the data source 8. Click **Create** **Databricks SQL Warehouse connected!** You can now use [Clark to build](/building-with-clark) with Databricks SQL Warehouse. ## Using Databricks SQL Warehouse in APIs Once your Databricks SQL Warehouse integration is created, you can start using Databricks by writing SQL in Superblocks APIs. ### Troubleshooting If you run into issues, first see our guide on [Troubleshooting Database Integrations](/integrations/troubleshooting/troubleshooting-databases). There are also several common errors you may see when using Databricks SQL Warehouse. The table below includes error messages, why they happen, and how to address them. | Error message | Why it's happening & Resolution | | - | - | | `IntegrationTimeoutError: Failed to connect to warehouse. Connection timed out after ms` | **Reason** Databricks warehouses can be configured to automatically hibernate after a period of inactivity. This timeout usually occurs when the warehouse is hibernating and did not restart within the timeout threshold of the agent. **Resolution** Retry the API/test connection after the warehouse has restarted, or increase the automatic hibernation time for your Databricks warehouse. | | `IntegrationOAuthError: OAuth2 - "On-Behalf-Of Token Exchange" could not find identity provider token` | **Reason** You've selected **Login identity provider** as the subject token source when using OAuth token federation, but you are not currently logged in to Superblocks using an OIDC-based Identity Provider. **Resolution** Reach out to [[support@superblocks.com](mailto:support@superblocks.com)](mailto:support@superblocks.com) for assistance configuring SSO or migrating your SSO configuration to OIDC. | | `Failed to process token: TOKEN_EXPIRED` | **Reason** The access token issued to Superblocks when you logged in, or the static token you've provided has expired. **Resolution** If using **Login identity provider**, log out of and back into Superblocks. If using a static token, obtain a new federated JWT from your identity provider. | | `Failed to process token: TOKEN_INVALID (Ensure a valid federation policy has been configured)` | **Reason** Your Databricks account either does not have a federation policy configured, or the `subject_token` being sent to Databricks by Superblocks does not satisfy the policy. This can happen if the token is not a valid JWT, or has a different `aud` or `iss` than configured in the Databricks federation policy. **Resolution** Make sure the `aud` and `iss` configured in Databricks are the same `aud` and `iss` your IdP uses when issuing tokens to Superblocks. Make sure the Databricks federation policy points to a valid JWKS URI. By default, Databricks uses the URI provided at `/.well-known/openid-configuration`. You may need to change this if your IdP uses a non-default authorization server or does not support a `/.well-known` discovery URL. | If you are encountering an error that's not listed, or the provided steps are insufficient to resolve the error, please contact us at [[support@superblocks.com](mailto:support@superblocks.com)](mailto:support@superblocks.com) # Datadog Source: https://docs.superblocks.com/integrations/integrations-library/datadog ## Setting up Datadog **Datadog** **Datadog connected!** You can now use [Clark to build](/building-with-clark) with Datadog. ## Use Datadog in APIs Once your Datadog integration is created, you can start calling Datadog actions in Superblocks APIs. In addition to generic HTTP requests, Datadog supports the following actions. ### Supported actions # Dropbox Source: https://docs.superblocks.com/integrations/integrations-library/dropbox ## Setting up Dropbox **Dropbox** **Dropbox connected!** You can now use [Clark to build](/building-with-clark) with Dropbox. ## Use Dropbox in APIs Once your Dropbox integration is created, you can start calling Dropbox actions in Superblocks APIs. In addition to generic HTTP requests, Dropbox supports the following actions. ### Supported actions # Elasticsearch Source: https://docs.superblocks.com/integrations/integrations-library/elasticsearch ## Setting up Elasticsearch **Elasticsearch** **Elasticsearch connected!** You can now use [Clark to build](/building-with-clark) with Elasticsearch. ## Use Elasticsearch in APIs Once your Elasticsearch integration is created, you can start calling Elasticsearch actions in Superblocks APIs. In addition to generic HTTP requests, Elasticsearch supports the following actions. ### Supported actions # Fireworks AI Source: https://docs.superblocks.com/integrations/integrations-library/fireworks ## Setting up Fireworks AI **Fireworks AI** **Fireworks AI connected!** You can now use [Clark to build](/building-with-clark) with Fireworks AI. ## Use Fireworks AI in APIs Once your Fireworks AI integration is created, you can start calling Fireworks AI actions in Superblocks APIs. In addition to generic HTTP requests, Fireworks AI supports the following actions. ### Supported actions # Front Source: https://docs.superblocks.com/integrations/integrations-library/front ## Setting up Front **Front** **Front connected!** You can now use [Clark to build](/building-with-clark) with Front. ## Use Front in APIs Once your Front integration is created, you can start calling Front actions in Superblocks APIs. In addition to generic HTTP requests, Front supports the following actions. ### Supported actions # Gemini Source: https://docs.superblocks.com/integrations/integrations-library/gemini ## Setting up Gemini **Gemini** **Gemini connected!** You can now use [Clark to build](/building-with-clark) with Gemini. ## Use Gemini in APIs Once your Gemini integration is created, you can start calling Gemini actions in Superblocks APIs. In addition to generic HTTP requests, Gemini supports the following actions. ### Supported actions # GitHub Source: https://docs.superblocks.com/integrations/integrations-library/github ## Setting up GitHub **GitHub** **GitHub connected!** You can now use [Clark to build](/building-with-clark) with GitHub. ## Use GitHub in APIs Once your GitHub integration is created, you can start calling GitHub actions in Superblocks APIs. In addition to generic HTTP requests, GitHub supports the following actions. ### Supported actions # Google Analytics Source: https://docs.superblocks.com/integrations/integrations-library/google-analytics ## Setting up Google Analytics **Google Analytics** **Google Analytics connected!** You can now use [Clark to build](/building-with-clark) with Google Analytics. ## Use Google Analytics in APIs Once your Google Analytics integration is created, you can start calling Google Analytics actions in Superblocks APIs. In addition to generic HTTP requests, Google Analytics supports the following actions. ### Supported actions # Google BigQuery Source: https://docs.superblocks.com/integrations/integrations-library/google-bigquery Build apps with read and write access to BigQuery ## Setting up Google BigQuery Before getting started in Superblocks, set up a GCP Service Account with the [following IAM roles](https://cloud.google.com/bigquery/docs/access-control#bigquery): * **Data Viewer** * **Metadata Viewer** * **Job User** Then generate a [service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating_service_account_keys). ### 1. Add integration Select **BigQuery** from the [integrations page](https://app.superblocks.com/integrations/bigquery). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Service Account Key | ✓ | Paste your Google [Service Account Key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys) JSON object in this field | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these Superblocks IPs to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). See the [Configure IP allowlist for databases](/integrations/auth/guides/configure-ip-allowlist-for-databases) guide for more information. After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Google BigQuery connected!** You can now use [Clark to build](/building-with-clark) with Google BigQuery. # Google Cloud Storage Source: https://docs.superblocks.com/integrations/integrations-library/google-cloud-storage Build apps with read and write access to a Google Cloud Storage instance ## Setting up Google Cloud Storage ### 1. Add integration Select **Google Cloud Storage** from the [integrations page](https://app.superblocks.com/integrations/gcs). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Service Account Key | ✓ | Paste your Google [Service Account Key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating_service_account_keys) | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these Superblocks IPs to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). See the [Configure IP allowlist for databases](/integrations/auth/guides/configure-ip-allowlist-for-databases) guide for more information. After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Google Cloud Storage connected!** You can now use [Clark to build](/building-with-clark) with Google Cloud Storage. ## Creating Google Cloud Storage steps Connect to your GCS integration from Superblocks by creating steps in Application APIs, Workflows, and Scheduled Jobs. A GCS step can perform the following actions: * List files * Read file * Delete file * Upload file * Upload multiple files * List buckets * Generate presigned URL ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Google Drive Source: https://docs.superblocks.com/integrations/integrations-library/google-drive ## Setting up Google Drive **Google Drive** **Google Drive connected!** You can now use [Clark to build](/building-with-clark) with Google Drive. ## Use Google Drive in APIs Once your Google Drive integration is created, you can start calling Google Drive actions in Superblocks APIs. In addition to generic HTTP requests, Google Drive supports the following actions. ### Supported actions # GraphQL Source: https://docs.superblocks.com/integrations/integrations-library/graphql Call any internal or external GraphQL API from Superblocks ## Setting up GraphQL ### 1. Add integration Select **GraphQL** from the [integrations page](https://app.superblocks.com/integrations/graphql). ### 2. Configure settings Fill out the form with the following settings: | Field | Required | Description | | - | - | - | | URL | ✓ | GraphQL URL to connect to | | Authentication | ✓ | The [authentication type](/integrations/auth/authentication-types) you want to use. See detailed instructions for setting up API auth in our docs on [Authentication & authorization](/integrations/auth/authentication-types) | | Headers | ✗ | List of headers that will be added to requests to your API | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to your API. After connecting successfully, click **Create** to save the integration. **GraphQL connected!** You can now use [Clark to build](/building-with-clark) with GraphQL. # Groq Source: https://docs.superblocks.com/integrations/integrations-library/groq ## Setting up Groq **Groq** **Groq connected!** You can now use [Clark to build](/building-with-clark) with Groq. ## Use Groq in APIs Once your Groq integration is created, you can start calling Groq actions in Superblocks APIs. In addition to generic HTTP requests, Groq supports the following actions. ### Supported actions # HubSpot Source: https://docs.superblocks.com/integrations/integrations-library/hubspot ## Setting up HubSpot **HubSpot** **HubSpot connected!** You can now use [Clark to build](/building-with-clark) with HubSpot. ## Use HubSpot in APIs Once your HubSpot integration is created, you can start calling HubSpot actions in Superblocks APIs. In addition to generic HTTP requests, HubSpot supports the following actions. ### Supported actions # Integrations library Source: https://docs.superblocks.com/integrations/integrations-library/index Connect Superblocks to any databases, third-party SaaS services, or internal REST / GraphQL APIs # Intercom Source: https://docs.superblocks.com/integrations/integrations-library/intercom ## Setting up Intercom **Intercom** **Intercom connected!** You can now use [Clark to build](/building-with-clark) with Intercom. ## Use Intercom in APIs Once your Intercom integration is created, you can start calling Intercom actions in Superblocks APIs. In addition to generic HTTP requests, Intercom supports the following actions. ### Supported actions # Jira Cloud Source: https://docs.superblocks.com/integrations/integrations-library/jira ## Setting up Jira Cloud **Jira Cloud** **Jira Cloud connected!** You can now use [Clark to build](/building-with-clark) with Jira Cloud. ## Use Jira Cloud in APIs Once your Jira Cloud integration is created, you can start calling Jira Cloud actions in Superblocks APIs. In addition to generic HTTP requests, Jira Cloud supports the following actions. ### Supported actions # Databricks Lakebase Source: https://docs.superblocks.com/integrations/integrations-library/lakebase Build apps with read and write access to a Databricks Lakebase database Databricks Lakebase is a fully managed Postgres database integrated with the Databricks lakehouse, built for modern operational workloads. It provides a Postgres-compatible OLTP database that eliminates complex ETL pipelines and ensures transactional data is seamlessly integrated with analytics and AI-driven applications. Integrate Databricks Lakebase with Superblocks to build internal tools and workflows that query, analyze, and update your data using familiar PostgreSQL syntax. ## Setting up Databricks Lakebase If you're using Superblocks Cloud, you may need to allowlist Superblocks IP addresses to connect to your database. Learn how to configure this in Databricks' guide on [Configuring IP access lists](https://docs.databricks.com/aws/en/security/network/front-end/ip-access-list-workspace). Alternatively, use the Superblocks Hybrid or Cloud-Prem architectures to keep your data within your VPC. ### Configure authentication To access your Databricks Lakebase database, you'll need to authenticate using a Databricks account. Superblocks provides several different ways to authenticate. See the Databricks documentation below for how to configure your preferred authentication method. | Method | Description | | - | - | | [Personal access token (PAT)](https://docs.databricks.com/aws/en/dev-tools/auth/pat) | Use a short or long-lived access token for a user or service principal. | | [Machine-to-machine OAuth](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m) | Configure OAuth client credentials for a service principal. Superblocks will exchange the client credentials with Databricks to retrieve a short-lived OAuth token. | | [OAuth token federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation) | Use OAuth tokens issued by your identity provider when users log in to Superblocks to authenticate with Databricks using the authenticated user's permissions. | ### Add integration 1. In the web app, navigate to the [Integrations](https://app.superblocks.com/integrations) page 2. Click **Add integration** 3. Search for **Databricks Lakebase** and select it from the list of available integrations 4. **Name** the integration 5. Fill out the integration configuration as follows: > [tab] Personal access token > > | Field | Required | Description | > | - | - | - | > | Host | ✓ | Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`) | > | Port | ✓ | Port to use when connecting (default: `5432`) | > | Database Name | ✓ | Name of database to connect to | > | Default schema | ✗ | An optional initial schema to use | > | Database Username | ✓ | Username to use to connect | > | Access token | ✓ | Databricks personal access token | > | Enable SSL | ✗ | Connect using SSL | > | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | > [tab] Machine-to-machine OAuth > > | Field | Required | Description | > | - | - | - | > | Host | ✓ | Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`) | > | Port | ✓ | Port to use when connecting (default: `5432`) | > | Database Name | ✓ | Name of database to connect to | > | Default schema | ✗ | An optional initial schema to use | > | Database Username | ✓ | Username to use to connect | > | OAuth client ID | ✓ | Client ID associated with your service principal | > | OAuth client secret | ✓ | Client secret associated with your service principal | > | Enable SSL | ✗ | Connect using SSL | > | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | > [tab] OAuth token federation > > | Field | Required | Description | > | - | - | - | > | Host | ✓ | Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`) | > | Port | ✓ | Port to use when connecting (default: `5432`) | > | Database Name | ✓ | Name of database to connect to | > | Default schema | ✗ | An optional initial schema to use | > | Database Username | ✓ | Username to use to connect | > | Subject token source | ✓ | Select **Login identity provider** to use the access token issued to Superblocks when users log in via SSO, or provide a **Static token**. | > | Token URL | ✓ | Databricks token URL. Choose a URL format based on the federation policy you previously configured. **Workspace identity federation** `https:///oidc/v1/token` **Account-wide token federation** `https:///oidc/accounts//v1/token` | > | Service Principal UUID | ✗ | Only required if using [Workload identity federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation-policy). The service principal client ID to authenticate as. | > | Enable SSL | ✗ | Connect using SSL | > | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | > > **Login identity provider** token source is only supported for Enterprise organizations with OIDC-based [Single Sign-On](/admin/org-administration/auth/single-sign-on) configured. If you're not sure how your SSO provider is configured, contact support for assistance. 6. Optionally, add more configurations to set credentials for [different environments](/development-lifecycle/build/data-tags) 7. Click **Test Connection** to check that Superblocks can connect to the data source 8. Click **Create** **Databricks Lakebase connected!** You can now use [Clark to build](/building-with-clark) with Databricks Lakebase. ## Using Databricks Lakebase in APIs Once your Databricks Lakebase integration is created, you can start using it by writing SQL in Superblocks APIs. Since Lakebase is fully Postgres-compatible, you can use standard PostgreSQL syntax for all your queries, including support for Postgres extensions like PostGIS and pgvector. ## Troubleshooting If you run into issues, first see our guide on [Troubleshooting Database Integrations](/integrations/troubleshooting/troubleshooting-databases). There are also several common errors you may see when using Databricks Lakebase. The table below includes error messages, why they happen, and how to address them. | Error message | Why it's happening & Resolution | | - | - | | `IntegrationOAuthError: OAuth2 - "On-Behalf-Of Token Exchange" could not find identity provider token` | **Reason** You've selected **Login identity provider** as the subject token source when using OAuth token federation, but you are not currently logged in to Superblocks using an OIDC-based Identity Provider. **Resolution** Reach out to [[support@superblocks.com](mailto:support@superblocks.com)](mailto:support@superblocks.com) for assistance configuring SSO or migrating your SSO configuration to OIDC. | | `Failed to process token: TOKEN_EXPIRED` | **Reason** The access token issued to Superblocks when you logged in, or the static token you've provided has expired. **Resolution** If using **Login identity provider**, log out of and back into Superblocks. If using a static token, obtain a new federated JWT from your identity provider. | | `Failed to process token: TOKEN_INVALID (Ensure a valid federation policy has been configured)` | **Reason** Your Databricks account either does not have a federation policy configured, or the `subject_token` being sent to Databricks by Superblocks does not satisfy the policy. This can happen if the token is not a valid JWT, or has a different `aud` or `iss` than configured in the Databricks federation policy. **Resolution** Make sure the `aud` and `iss` configured in Databricks are the same `aud` and `iss` your IdP uses when issuing tokens to Superblocks. Make sure the Databricks federation policy points to a valid JWKS URI. By default, Databricks uses the URI provided at `/.well-known/openid-configuration`. You may need to change this if your IdP uses a non-default authorization server or does not support a `/.well-known` discovery URL. | If you are encountering an error that's not listed, or the provided steps are insufficient to resolve the error, please contact us at [[support@superblocks.com](mailto:support@superblocks.com)](mailto:support@superblocks.com) # LaunchDarkly Source: https://docs.superblocks.com/integrations/integrations-library/launchdarkly ## Setting up LaunchDarkly **LaunchDarkly** **LaunchDarkly connected!** You can now use [Clark to build](/building-with-clark) with LaunchDarkly. ## Use LaunchDarkly in APIs Once your LaunchDarkly integration is created, you can start calling LaunchDarkly actions in Superblocks APIs. In addition to generic HTTP requests, LaunchDarkly supports the following actions. ### Supported actions # MariaDB Source: https://docs.superblocks.com/integrations/integrations-library/mariadb Build apps with read and write access to a MariaDB database ## Setting up MariaDB ### 1. Add integration Select **MariaDB** from the [integrations page](https://app.superblocks.com/integrations/mariadb). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Hostname or IP address to connect to | | Port | ✓ | Port to use when connecting to MariaDB | | Database Name | ✓ | Name of database to connect to | | Database Username | ✓ | Username to use to connect | | Database Password | ✓ | Password for database username | | Enable SSL | ✗ | Connect via SSL if selected | | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** if selected | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **MariaDB connected!** You can now use [Clark to build](/building-with-clark) with MariaDB. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [common MariaDB connection issues](https://mariadb.com/kb/en/troubleshooting-connection-issues/). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Mistral AI Source: https://docs.superblocks.com/integrations/integrations-library/mistral ## Setting up Mistral AI **Mistral AI** **Mistral AI connected!** You can now use [Clark to build](/building-with-clark) with Mistral AI. ## Use Mistral AI in APIs Once your Mistral AI integration is created, you can start calling Mistral AI actions in Superblocks APIs. In addition to generic HTTP requests, Mistral AI supports the following actions. ### Supported actions # MongoDB Source: https://docs.superblocks.com/integrations/integrations-library/mongodb Build apps with read and write access to a MongoDB instance ## Setting up MongoDB ### 1. Add integration Select **MongoDB** from the [integrations page](https://app.superblocks.com/integrations/mongodb). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Connection URI | ✓ | Connection URI used to connect to a MongoDB instance. See [Connection URI Docs](https://www.mongodb.com/docs/manual/reference/connection-string/) for standard format. | | Database Name | ✓ | Name of database to connect to | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **MongoDB connected!** You can now use [Clark to build](/building-with-clark) with MongoDB. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [common MongoDB connection issues](https://www.mongodb.com/docs/atlas/troubleshoot-connection/). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Microsoft SQL Server Source: https://docs.superblocks.com/integrations/integrations-library/mssql Build apps with read and write access to a Microsoft SQL Server database ## Setting up Microsoft SQL Server ### 1. Add integration Select **Microsoft SQL Server** from the [integrations page](https://app.superblocks.com/integrations/mssql). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Hostname or IP address to connect to | | Port | ✓ | Port to use when connecting to Microsoft SQL Server | | Database Name | ✓ | Name of database to connect to | | Database Username | ✓ | Username to use to connect | | Database Password | ✓ | Password for database username | | Enable SSL | ✗ | Connect via SSL if selected | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Microsoft SQL Server connected!** You can now use [Clark to build](/building-with-clark) with Microsoft SQL Server. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [common Microsoft SQL Server connection issues](https://docs.microsoft.com/en-us/troubleshoot/sql/connect/resolve-connectivity-errors-overview). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # MySQL Source: https://docs.superblocks.com/integrations/integrations-library/mysql Build apps with read and write access to a MySQL database ## Setting up MySQL ### 1. Add integration Select **MySQL** from the [integrations page](https://app.superblocks.com/integrations/mysql). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Hostname or IP address to connect to | | Port | ✓ | Port to use when connecting to MySQL | | Database Name | ✓ | Name of database to connect to | | Database Username | ✓ | Username to use to connect | | Database Password | ✓ | Password for database username | | Enable SSL | ✗ | Connect using SSL | | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | | Use SSH Tunnel | ✗ | Connect via an SSH tunnel. See configuration details [here](/integrations/auth/database-connections#ssh-configuration). | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **MySQL connected!** You can now use [Clark to build](/building-with-clark) with MySQL. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [common MySQL connection issues](https://dev.mysql.com/doc/refman/8.0/en/problems-connecting.html). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Notion Source: https://docs.superblocks.com/integrations/integrations-library/notion ## Setting up Notion **Notion** **Notion connected!** You can now use [Clark to build](/building-with-clark) with Notion. ## Use Notion in APIs Once your Notion integration is created, you can start calling Notion actions in Superblocks APIs. In addition to generic HTTP requests, Notion supports the following actions. ### Supported actions # OpenAI Source: https://docs.superblocks.com/integrations/integrations-library/openai ## Setting up OpenAI **OpenAI** **OpenAI connected!** You can now use [Clark to build](/building-with-clark) with OpenAI. ## Use OpenAI in APIs Once your OpenAI integration is created, you can start calling OpenAI actions in Superblocks APIs. In addition to generic HTTP requests, OpenAI supports the following actions. ### Supported actions # OracleDB Source: https://docs.superblocks.com/integrations/integrations-library/oracledb Build apps with read and write access to an Oracle database Oracle Database is a powerful, enterprise-grade relational database management system known for its scalability, reliability, and comprehensive feature set. Integrate OracleDB with Superblocks to build internal tools and workflows that query, analyze, and update your Oracle data, enabling your team to automate processes and accelerate decision-making. ## Setting up OracleDB If you're using Superblocks Cloud, you may need to allowlist Superblocks IP addresses to connect to your database. Configure your Oracle network access rules to allow connections from [Superblocks IP addresses](/enterprise/security/overview#ip-addresses). Alternatively, use Superblocks Hybrid or Cloud-Prem architectures to keep your data within your VPC. ### 1. Add integration Select **OracleDB** from the [integrations page](https://app.superblocks.com/integrations/oracledb). ### 2. Configure settings Connect using either a form or a connection string. > [tab] Form > > \ > Fill out the form with the following settings: > > | Setting | Required | Description | > | - | - | - | > | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | > | Host | ✓ | Hostname or IP address of the Oracle database server | > | Port | ✓ | Port to use when connecting to Oracle (default: `1521`) | > | Service Name | ✓ | Oracle service name to connect to | > | Database Username | ✓ | Username to use to connect | > | Database Password | ✓ | Password for database username | > | Enable SSL | ✗ | Connect using SSL/TLS encryption | > | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | > [tab] Connection string > > \ > Provide an Oracle connection string. Superblocks supports multiple formats: > > **Easy Connect format:** > > ``` > host[:port]/service_name > ``` > > **TNS connect descriptor format:** > > ``` > (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service_name))) > ``` ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **OracleDB connected!** You can now use [Clark to build](/building-with-clark) with OracleDB. ## Using OracleDB in APIs Once your OracleDB integration is created, you can start using it by writing SQL in Superblocks APIs. Use standard Oracle SQL syntax for all your queries, including support for PL/SQL blocks. ## Troubleshooting If you run into issues, first see our guide on [Troubleshooting Database Integrations](/integrations/troubleshooting/troubleshooting-databases). There are also several common errors you may see when using OracleDB: | Error message | Why it's happening & Resolution | | - | - | | `ORA-12154: TNS:could not resolve the connect identifier specified` | **Reason** The service name or connect identifier cannot be found. **Resolution** Verify the service name is correct and that the Oracle listener is configured properly. | | `ORA-12541: TNS:no listener` | **Reason** The Oracle listener is not running on the specified host and port. **Resolution** Verify the host and port are correct, and ensure the Oracle listener service is running on the database server. | | `ORA-01017: invalid username/password; logon denied` | **Reason** The username or password provided is incorrect. **Resolution** Verify your credentials are correct. Note that Oracle passwords are case-sensitive. | | `ORA-28000: the account is locked` | **Reason** The database user account has been locked due to too many failed login attempts or administrative action. **Resolution** Contact your database administrator to unlock the account. | If you are encountering an error that's not listed, or the provided steps are insufficient to resolve the error, please contact us at [[support@superblocks.com](mailto:support@superblocks.com)](mailto:support@superblocks.com) # PagerDuty Source: https://docs.superblocks.com/integrations/integrations-library/pagerduty ## Setting up PagerDuty **PagerDuty** **PagerDuty connected!** You can now use [Clark to build](/building-with-clark) with PagerDuty. ## Use PagerDuty in APIs Once your PagerDuty integration is created, you can start calling PagerDuty actions in Superblocks APIs. In addition to generic HTTP requests, PagerDuty supports the following actions. ### Supported actions # Perplexity Source: https://docs.superblocks.com/integrations/integrations-library/perplexity ## Setting up Perplexity **Perplexity** **Perplexity connected!** You can now use [Clark to build](/building-with-clark) with Perplexity. ## Use Perplexity in APIs Once your Perplexity integration is created, you can start calling Perplexity actions in Superblocks APIs. In addition to generic HTTP requests, Perplexity supports the following actions. ### Supported actions # PostgreSQL Source: https://docs.superblocks.com/integrations/integrations-library/postgres Build apps with read and write access to a PostgreSQL database ## Setting up PostgreSQL ### 1. Add integration Select **PostgreSQL** from the [integrations page](https://app.superblocks.com/integrations/postgres). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Host | ✓ | Hostname or IP address to connect to | | Port | ✓ | Port to use when connecting to PostgreSQL | | Database Name | ✓ | Name of database to connect to | | Database Username | ✓ | Username to use to connect | | Database Password | ✓ | Password for database username | | Enable SSL | ✗ | Connect using SSL | | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | | Use SSH Tunnel | ✗ | Connect via an SSH tunnel. See configuration details [here](/integrations/auth/database-connections#ssh-configuration). | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **PostgreSQL connected!** You can now use [Clark to build](/building-with-clark) with PostgreSQL. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases), in addition to [common Postgres connection issues](https://www.pgsclusters.com/docs/postgresql/Troubleshooting%20Connection%20Issues%20for%20PostgreSQL1605777396.html). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # REST API Source: https://docs.superblocks.com/integrations/integrations-library/rest-api Call any internal or external REST API from Superblocks ## Setting up REST API ### 1. Add integration Select **REST API** from the [integrations page](https://app.superblocks.com/integrations/restapi). ### 2. Configure settings Fill out the form with the following settings: | Field | Required | Description | | - | - | - | | Base URL | ✓ | The main endpoint address of the API that serves as the root for all requests | | Authentication | ✓ | The [authentication type](/integrations/auth/authentication-types) you want to use. See detailed instructions for setting up API auth in our docs on [Authentication & authorization](/integrations/auth) | | Headers | ✗ | List of headers that will be added to requests to your API | | Params | ✗ | List of query parameters that will be added to requests to your API | #### OpenAPI Specifications OpenAPI specs help Clark understand how to work with your API. To upload an OpenAPI specification to a REST API integration: 1. Select **Upload OpenAPI** in the top-right corner 2. From the uploader, select a JSON or YAML file containing your API's OpenAPI spec (version 2.0 or later) 3. Click **Ok** to upload Once your API's spec has been uploaded, you can manage your spec and explore docs from the **API Specification** tab. ##### Replacing an OpenAPI specification To replace an API specification, such as to upload a new version, you can click on the button in the top-right labeled with the name of specification, e.g. `spec-name.yaml`, and upload a new specification. ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to your API. After connecting successfully, click **Create** to save the integration. **REST API connected!** You can now use [Clark to build](/building-with-clark) with REST API. ## Supported OpenAPI specs Superblocks supports uploading the following specification versions: * OpenAPI 3.0 and 3.1 * Swagger 2.0 Specification files can be provided in any of the following formats: * JSON * YAML * X-YAML # Salesforce Source: https://docs.superblocks.com/integrations/integrations-library/salesforce Build dashboards, Sales and CRM panels, and other custom internal tools on top of your Salesforce data ## Setting up Salesforce ### 1. Create a Salesforce app and add integration Start by [configuring a connected app](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_basics.htm\&type=5) in your Salesforce account. The app should have [OAuth Settings enabled](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_api_integration.htm\&type=5), specifically using the [OAuth 2.0 Client Credentials Flow](https://help.salesforce.com/s/articleView?id=sf.connected_app_client_credentials_setup.htm\&type=5) authorization flow. Follow the Salesforce REST API [Quick Start](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/quickstart.htm) for a full guide. Once the app has been created, navigate back to Superblocks and select **Salesforce** from the [integrations page](https://app.superblocks.com/integrations/salesforce). ### 2. Configure settings Fill out the form with the following settings: | Setting | Required | Description | | - | - | - | | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | | Instance URL | ✓ | URL for the Salesforce instance, e.g. `https://your-domain.my.salesforce.com` | | Token URL | ✓ | The full URL path to the token endpoint that serves OAuth tokens | | Consumer ID | ✓ | A public identifier used to identify this Salesforce consumer to the authorization/token servers | | Consumer Secret | ✓ | A secret shared between the Salesforce consumer and the authorizing/token servers to verify the Consumer ID | ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Salesforce connected!** You can now use [Clark to build](/building-with-clark) with Salesforce. ## Creating Salesforce steps When using Salesforce steps, there are 3 options: 1. [SOQL queries](#soql-queries) 2. [Single object actions](#single-object-actions) 3. [Bulk actions](#bulk-actions) ### SOQL queries Write **[SOQL queries](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm)** to perform read-only actions on your SFDC data. ### Single object actions Use **single object actions** to perform CRUD actions on a single object. Pass in an object of data in the **Resource Body**. * Create a single object * Update a single object * Delete a single object * Read a single object ### Bulk actions Use **bulk actions** to perform CRUD actions on several objects at time. Pass in an array of objects in the **Bulk Update Body**. * Create several objects * Update several objects * Delete several objects * Upsert (update or insert) several objects # Segment Source: https://docs.superblocks.com/integrations/integrations-library/segment ## Setting up Segment **Segment** **Segment connected!** You can now use [Clark to build](/building-with-clark) with Segment. ## Use Segment in APIs Once your Segment integration is created, you can start calling Segment actions in Superblocks APIs. In addition to generic HTTP requests, Segment supports the following actions. ### Supported actions # SendGrid Source: https://docs.superblocks.com/integrations/integrations-library/sendgrid ## Setting up SendGrid **SendGrid** **SendGrid connected!** You can now use [Clark to build](/building-with-clark) with SendGrid. ## Use SendGrid in APIs Once your SendGrid integration is created, you can start calling SendGrid actions in Superblocks APIs. In addition to generic HTTP requests, SendGrid supports the following actions. ### Supported actions # Slack Source: https://docs.superblocks.com/integrations/integrations-library/slack ## Setting up Slack **Slack** **Slack connected!** You can now use [Clark to build](/building-with-clark) with Slack. ## Use Slack in APIs Once your Slack integration is created, you can start calling Slack actions in Superblocks APIs. In addition to generic HTTP requests, Slack supports the following actions. ### Supported actions # Snowflake Warehouse Source: https://docs.superblocks.com/integrations/integrations-library/snowflake Snowflake is a cloud-based data platform that combines the power of a data warehouse with the flexibility of a cloud solution, enabling organizations to store, analyze, and share large volumes of data seamlessly. Using the Superblocks integration with Snowflake, teams can effortlessly build custom internal tools that leverage real-time data, streamlining workflows and enhancing operational efficiency across the organization. ## Setting up Snowflake If you're using Superblocks Cloud, you may need to allowlist Superblocks IP addresses to connect to your database. Learn how to configure this in Snowflake's guide on [Controlling network traffic with network policies](https://docs.snowflake.com/en/user-guide/network-policies). Alternatively, use Superblocks Hybrid or Cloud-Prem architectures to keep your data within your VPC. ### 1. Add integration Select **Snowflake Warehouse** from the [integrations page](https://app.superblocks.com/integrations/snowflake). ### 2. Configure settings Fill out the form with the following settings based on your authentication method: > [tab] Password-based authentication > > | Field | Required | Description | > | - | - | - | > | Account identifier | ✓ | Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#account-identifiers). The account identifier **does not** include the `snowflakecomputing.com` suffix | > | Username | ✓ | Login name for the user | > | Password | ✓ | Password for the user | > | Database | ✓ | Name of the database to use | > | Default warehouse | ✗ | Name of the warehouse to use. Defaults to the user's default warehouse | > | Default schema | ✗ | Name of the schema to use for the database. Defaults to **public** | > | Default role | ✗ | Name of the role to use. Defaults to the user's default role | > [tab] Native SSO > > | Field | Required | Description | > | - | - | - | > | Account identifier | ✓ | Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#account-identifiers). The account identifier **does not** include the `snowflakecomputing.com` suffix | > | Username | ✓ | User name of Okta user | > | Password | ✓ | Password of Okta user | > | Authenticator URL | ✓ | The URL endpoint for your Okta account (e.g. `https://.okta.com`) | > | Database | ✓ | Name of the database to use | > | Default warehouse | ✗ | Name of the warehouse to use. Defaults to the user's default warehouse | > | Default schema | ✗ | Name of the schema to use for the database. Defaults to **public** | > | Default role | ✗ | Name of the role to use. Defaults to the user's default role | > > For more information, see Snowflake's docs on [Native SSO](https://docs.snowflake.com/en/user-guide/admin-security-fed-auth-use#native-sso-okta-only) > [tab] Key-pair authentication > > | Field | Required | Description | > | - | - | - | > | Account identifier | ✓ | Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#account-identifiers). The account identifier **does not** include the `snowflakecomputing.com` suffix | > | Username | ✓ | Login name for the user | > | Private key | ✓ | The private key used for authentication. For more information, see [Using key-pair authentication and key-pair rotation](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-connect.html#label-python-key-pair-authn-rotation). | > | Passphrase | ✗ | The passphrase used to decrypt the private key for the specified user. See [Using key-pair authentication and key-pair rotation](https://docs.snowflake.com/en/developer-guide/python-connector/python-connector-connect.html#label-python-key-pair-authn-rotation). | > | Database | ✓ | Name of the database to use | > | Default warehouse | ✗ | Name of the warehouse to use. Defaults to the user's default warehouse | > | Default schema | ✗ | Name of the schema to use for the database. Defaults to **public** | > | Default role | ✗ | Name of the role to use. Defaults to the user's default role | > > For more information, see Snowflake's docs on [Key-pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth) > [tab] External OAuth > > | Field | Required | Description | > | - | - | - | > | Account identifier | ✓ | Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html#account-identifiers). The account identifier **does not** include the `snowflakecomputing.com` suffix | > | Subject token source | ✓ | | > | Token URL | ✓ | The token endpoint of the authorization server, used to exchange an authorization code for an access token | > | Client ID | ✓ | The ID issues to your OAuth client during registration | > | Client secret | ✓ | The secret issued to your OAuth client during registration | > | Audience | ✓ | Snowflake [account url](https://docs.snowflake.com/en/user-guide/admin-account-identifier#finding-the-organization-and-account-name-for-an-account) | > | Scopes | ✓ | `session:role-any` | > | Database | ✓ | Name of the database to use | > | Default warehouse | ✗ | Name of the warehouse to use. Defaults to the user's default warehouse | > | Default schema | ✗ | Name of the schema to use for the database. Defaults to **public** | > | Default role | ✗ | Name of the role to use. Defaults to the user's default role | > > For more information: > > * See Snowflake's docs on [External Auth](https://docs.snowflake.com/en/user-guide/oauth-ext-overview) > * Check out our tutorial on [Snowflake External OAuth with Okta as your IdP](/integrations/auth/guides/snowflake-external-oauth-with-okta) ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Snowflake connected!** You can now use [Clark to build](/building-with-clark) with Snowflake. ## Troubleshooting If you run into issues, see [Troubleshooting Database Integrations](/integrations/troubleshooting/troubleshooting-databases). # Snowflake Cortex Source: https://docs.superblocks.com/integrations/integrations-library/snowflake-cortex ## Setting up Snowflake Cortex **Snowflake Cortex** **Snowflake Cortex connected!** You can now use [Clark to build](/building-with-clark) with Snowflake Cortex. ## Use Snowflake Cortex in APIs Once your Snowflake Cortex integration is created, you can start calling Snowflake Cortex actions in Superblocks APIs. In addition to generic HTTP requests, Snowflake Cortex supports the following actions. ### Supported actions # Snowflake Postgres Source: https://docs.superblocks.com/integrations/integrations-library/snowflake-postgres Build apps with read and write access to a Snowflake Postgres database ## Setting up Snowflake Postgres ### 1. Add integration Select **Snowflake Postgres** from the [integrations page](https://app.superblocks.com/integrations/snowflakepostgres). ### 2. Configure settings Connect using either a form or a connection string. > [tab] Form > > \ > Fill out the form with the following settings: > > | Setting | Required | Description | > | - | - | - | > | Name | ✓ | Name that will be displayed to users when selecting this integration in Superblocks | > | Host | ✓ | Hostname or IP address to connect to (e.g. `xxxx.us-west-2.aws.postgres.snowflake.app`) | > | Port | ✓ | Port to use when connecting (default: `5432`) | > | Database Name | ✓ | Name of database to connect to | > | Database Username | ✓ | Username to use to connect | > | Database Password | ✓ | Password for database username | > | Use a self-signed SSL certificate | ✗ | Provide **Server CA**, **Client Key**, and **Client Cert** | > [tab] Connection string > > \ > Provide a PostgreSQL connection string in the following format: > > ``` > postgresql://username:password@host:port/database > ``` ### 3. Test and save Click **Test Connection** to check that Superblocks can connect to the data source. If using Superblocks Cloud, add these [Superblocks IPs](/enterprise/security/overview#ip-addresses) to your allowlist (not necessary for Hybrid or Cloud-Prem deployments). After connecting successfully, click **Create** to save the integration. ### 4. Set data tags Optionally, configure different data tags for [separate development environments](/development-lifecycle/build/data-tags). **Snowflake Postgres connected!** You can now use [Clark to build](/building-with-clark) with Snowflake Postgres. ## Troubleshooting Check out our guide on [common errors across database integrations](/integrations/troubleshooting/troubleshooting-databases). If you are encountering an error that you don't see in the guide, or the provided steps are insufficient to resolve the error, please contact us at [help@superblocks.com](mailto:help@superblocks.com). # Stability AI Source: https://docs.superblocks.com/integrations/integrations-library/stabilityai ## Setting up Stability AI **Stability AI** **Stability AI connected!** You can now use [Clark to build](/building-with-clark) with Stability AI. ## Use Stability AI in APIs Once your Stability AI integration is created, you can start calling Stability AI actions in Superblocks APIs. In addition to generic HTTP requests, Stability AI supports the following actions. ### Supported actions # Stripe Source: https://docs.superblocks.com/integrations/integrations-library/stripe ## Setting up Stripe **Stripe** **Stripe connected!** You can now use [Clark to build](/building-with-clark) with Stripe. ## Use Stripe in APIs Once your Stripe integration is created, you can start calling Stripe actions in Superblocks APIs. In addition to generic HTTP requests, Stripe supports the following actions. ### Supported actions # Twilio Source: https://docs.superblocks.com/integrations/integrations-library/twilio ## Setting up Twilio **Twilio connected!** You can now use [Clark to build](/building-with-clark) with Twilio. ## Use Twilio in APIs You can use Twilio in your Superblocks applications through the API interface. This allows you to programmatically send messages, manage phone numbers, and interact with Twilio's services. In addition to generic HTTP requests, Twilio supports the following actions. ### Supported actions # Zendesk Source: https://docs.superblocks.com/integrations/integrations-library/zendesk ## Setting up Zendesk **Zendesk** **Zendesk connected!** You can now use [Clark to build](/building-with-clark) with Zendesk. ## Use Zendesk in APIs Once your Zendesk integration is created, you can start calling Zendesk actions in Superblocks APIs. In addition to generic HTTP requests, Zendesk supports the following actions. ### Supported actions # Zoom Source: https://docs.superblocks.com/integrations/integrations-library/zoom ## Setting up Zoom **Zoom** **Zoom connected!** You can now use [Clark to build](/building-with-clark) with Zoom. ## Use Zoom in APIs Once your Zoom integration is created, you can start calling Zoom actions in Superblocks APIs. In addition to generic HTTP requests, Zoom supports the following actions. ### Supported actions # Integration knowledge Source: https://docs.superblocks.com/integrations/knowledge Teach Clark about your data sources so it writes better queries and API calls Integration knowledge is scoped to a specific data source and is looked up whenever Clark works with that integration. Use it to capture the details and nuances that help Clark write correct queries and API calls from the start — things like schema quirks, query patterns, naming conventions, and API behavior. ## Adding integration knowledge Navigate to the **Knowledge** page and chat with Clark to describe what you want it to remember about a specific data source. Clark will create the right knowledge entry at the right scope for you, then present it for your review before saving. We recommend using Clark to write entries because it optimizes them for LLM retrieval — producing focused, well-structured instructions that Clark can look up effectively at build time. For example, you might tell Clark: * "The `orders` table uses soft deletes. Always include `WHERE deleted_at IS NULL` unless explicitly asked to include deleted records." * "This Salesforce instance uses a custom `Region__c` field on Account. Always include it when querying accounts." * "Rate limit is 100 requests per minute. Use batch endpoints for bulk operations instead of individual calls." * "The `users` table has a `legacy_id` column that is no longer used. Always use `user_id` instead." Clark will draft the entry, scope it to the relevant integration, and present it for your review before saving. ![Clark creating an integration knowledge entry](https://mintcdn.com/superblocks/nJ3ep6kSq7I75bb2/images/building-with-clark/knowledge/integration-knowledge.png?fit=max\&auto=format\&n=nJ3ep6kSq7I75bb2\&q=85\&s=3604d0d41360e0f2bc3111ef9017635a) You can also ask Clark to **explore your existing knowledge**, refine entries, or identify duplicates — for example, "Review my integration knowledge for Postgres and flag anything that's outdated." ## Permissions Integration knowledge follows your existing integration access. If you can update an integration, you can update its knowledge. If you can build with an integration, Clark will use its knowledge during your conversations. ## Related Integration knowledge is part of Clark's broader [Knowledge](/building-with-clark/knowledge) system. You can also define knowledge at the [organization](/admin/org-administration/knowledge), [user](/building-with-clark/knowledge/user-knowledge), and [app](/building-with-clark/knowledge/app-knowledge) levels. # Overview Source: https://docs.superblocks.com/integrations/overview Connect Superblocks to databases, APIs, and SaaS services to build powerful internal tools Integrations connect Superblocks to your data sources, APIs, and third-party services. Once configured, Clark can use integrations you have access to in your applications. ## How integrations work An integration in Superblocks is a reusable, centrally managed connection to an external system. When you create an integration, you provide connection details and authentication credentials once. From there, [share the integration](/admin/org-administration/resource-roles/manage-access#granting-access-to-a-resource) with any builder in your organization so they can reference it when [building with Clark](/building-with-clark/tagging-integrations). ## Creating an integration 1. Navigate to the [**Integrations**](https://app.superblocks.com/integrations) page in Superblocks 2. Click **+ Add integration** then select the integration you want to add 3. Provide a **Name** for the integration and fill out the relevant connection details and authentication credentials 4. Click **Test Connection** to verify connectivity 5. Click **Create** to save 6. [Share](/admin/org-administration/resource-roles/manage-access#granting-access-to-a-resource) the integration for others to build with ## Authentication Superblocks supports a range of authentication methods depending on the integration type, including basic auth, API keys, OAuth 2.0, AWS IAM, and more. For details, see [Authentication types](/integrations/auth/authentication-types). For database integrations, you can also configure [SSL, SSH tunneling, and connection strings](/integrations/auth/database-connections/index) for secure connectivity. ## Integration configurations You can set up separate integration configurations with distinct connection details (endpoints, authentication, etc.) and associate these configurations with different [data tags](/development-lifecycle/build/data-tags). This lets your apps automatically connect to the right data source (i.e. staging, prod-us, prod-eu) with the relevant credentials based on the data tag in use in your app. A source with a single instance, such as most SaaS tools, can use one configuration linked to all your data tags, or a second configuration with a scoped user for `dev`. See [Sharing a third-party configuration between dev and production](/enterprise/hybrid-architecture/plan/index#sharing-a-third-party-configuration-between-dev-and-production). ## App availability Integrations can be available to all apps or restricted to specific apps. [Grant access to specific apps](/admin/org-administration/resource-roles/manage-access#granting-specific-apps-access-to-integrations) to control which apps can discover and build with each integration while keeping user and group permissions separate. ## Related docs * [Integrations library](/integrations/integrations-library) — browse all supported integrations * [Manage access to resources](/admin/org-administration/resource-roles/manage-access#granting-specific-apps-access-to-integrations) — control which apps can discover and use each integration * [Integration knowledge](/integrations/knowledge) — teach Clark about your data sources for better AI-assisted development * [Authentication types](/integrations/auth/authentication-types) — supported authentication methods * [Database connections](/integrations/auth/database-connections/index) — connection methods, SSL, and SSH tunneling # Troubleshooting database integrations Source: https://docs.superblocks.com/integrations/troubleshooting/troubleshooting-databases If you encounter errors connecting database integrations (Postgres, MySQL, MariaDB, MongoDB, SQL Server) from Superblocks, check the following conditions / scenarios: #### Correct settings for: * **Host/IP address** - Results in a `getaddrinfo ENOTFOUND` error when the hostname is incorrect. * **Database name** - Specify the database name, not the database instance identifier. Otherwise, Superblocks will report an `Unknown database` error. * **Username and Password** - Invalid credentials result in `Access denied` or `password authentication failed for user` errors. #### Inbound access blocked Is there a firewall blocking access to the database? For example, if you're using Superblocks Cloud, make sure your VPC security groups have the right inbound rules to allow access from the [Superblocks IP addresses](/enterprise/security/overview#ip-addresses). Similarly, if you're [self-hosting the data plane](/enterprise/hybrid-architecture/overview), make sure that it is running inside the same network as the database or is allowed to connect to your database externally. Expect to see `Connection timeout: failed to create socket`, `timeout expired`, or similar errors when the database instance is not accessible from Superblocks. #### Server listening internally only If you're running your own database server, you may need to configure it to accept remote connections, instead of listening locally on its network interfaces. If the latter is true, then you can configure the server to listen on all interfaces by editing the database config file and setting the bind / listening address accordingly (for example `bind_address = 0.0.0.0` for [MySQL](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_bind_address) or `listen_addresses = '*'` for [Postgres](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-LISTEN-ADDRESSES)). #### Testing with self-hosted data plane using localhost For Docker containers, `localhost` inside a container doesn't mean the same from the context of the host where the container is running. As such, you'll see `ECONNREFUSED` errors if you've specified `localhost` in the integration form. Instead, use `host.docker.internal` in the Superblocks integration form configuration. More on this in the [Docker docs here](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). # Release notes Source: https://docs.superblocks.com/release-notes/index Product updates and announcements **10.9.26** ## Highlights **Superblocks in Claude is in beta.** Add Superblocks to Claude, then ask in plain language to import, build, edit, or publish an app. Clark does the work in Superblocks, and your app appears right alongside the conversation. This is optimized for Claude Cowork, and because it uses the Superblocks MCP, you can add it to any AI chat client. [Learn more →](/building-with-clark/superblocks-in-claude) **Code Security is now enabled for all customers.** The default mode is Blocking, so security issues are flagged before an app reaches production. In Blocking mode, critical and high findings must be fixed before publish. [Learn more →](/admin/code-security/index) **Superblocks Database is now in beta for every customer with AWS.** Any customer on AWS can turn on Database beta and give each app its own Aurora PostgreSQL database on their infrastructure. [Learn more →](/admin/superblocks-on-aws/database) **Claude Opus 5.5 is now the default model for Clark.** Opus 5.5 is more powerful and more cost-effective than the previous default. In our internal evaluation and during beta, we saw substantial improvements in Clark's capabilities. **You can now connect your own secrets manager.** Store credentials in a secrets manager and provide them to integrations at runtime, including when you rotate them, instead of pasting secrets into Superblocks. Supported stores are [AWS Secrets Manager](/admin/secrets-management/aws-secrets-manager), [Google Secret Manager](/admin/secrets-management/google-secrets-manager), and [HashiCorp Vault](/admin/secrets-management/hashicorp-vault). [Learn more →](/admin/secrets-management/overview) ## New Clark features * **Submit feedback directly from the chat.** Use the thumbs up or thumbs down controls to tell the Superblocks team how Clark is doing, without leaving your conversation. Your feedback goes straight to our team and helps us improve Clark's responses. * **Automatically collapse long user messages.** Lengthy messages, including detailed policy findings sent from the Publish tab's Fix action, are condensed so they no longer push the rest of the conversation out of view. ## Clark context management and reliability * **More context-efficient screenshotting.** By default, Clark takes a small glance at the visible part of your app instead of rendering the whole page at full size. That uses about 7x fewer vision tokens for routine checks. When it needs more, Clark can capture a specific region, the full page, or a high-detail view. * **More context-efficient docs for Clark.** We trimmed the docs Clark reads so lookups cost less. That leaves more room for your app in each prompt, uses fewer GAUs per prompt, and means less summarization. * **Clark knows it cannot capture certain images in screenshots.** External images that block cross-origin requests appear with a clear placeholder, labeled "image not captured" on larger images, instead of a blank or loading state. Clark also gets a short note explaining the limitation, so it no longer retries the screenshot or assumes the image failed to render. That means faster generations and fewer GAUs used per prompt. * **Editor no longer shows a false "404 - Page not found".** Some apps generated by Clark would display a "Page not found" overlay in the editor, even though they ran fine in preview and when deployed. The editor now correctly detects these pages, so you no longer need to rework your app's routing to clear the error. ## Integrations * **APIs that download files now run faster.** Binary REST responses are now sent in a much more compact format, so file download payloads are significantly smaller. This improves performance for any API that downloads files. For customers self-hosting data planes, upgrade your data plane to v1.53.0 or later. * **Upload binary data to REST APIs.** Clark can now set the `bodyType` option to `"raw"`, `"binary"`, `"formUrlencoded"`, or `"multipartForm"` to upload files, send form-encoded data, or post multipart forms to REST integrations in APIs. For customers self-hosting data planes, upgrade your data plane to v1.52.0 or later. * **Zendesk integration now supports OAuth 2.0 Authorization Code authentication.** New Zendesk integrations default to OAuth, and you can use either a shared access token or per-user authentication. Each organization registers its own OAuth client in Zendesk admin, since Zendesk does not offer a shared one. Zendesk is phasing out API tokens, so switching to OAuth keeps your integration working. Existing integrations continue to use basic authentication until you switch them. * **OAuth2 Client Credentials integrations can now send credentials in the request body.** A new Client authentication dropdown lets you choose between sending credentials as a Basic Auth header or in the body of the token request. This makes the Client Credentials flow compatible with APIs that only accept credentials in the body. For customers self-hosting data planes, upgrade your data plane to v1.52.0 or later. ## Code Security * **Clark can now fix large batches of security findings.** You can now fix a long list of security findings with Clark in a single turn. Clark breaks the findings into a checklist and works through the list, so you can address security issues before publishing. ## Publishing * **You can roll back to a previously published commit even when pre-publish Policy Agents are enabled.** Commits that already passed your pre-publish Policy Agents can be republished right away, without re-running the checks. This makes it faster to recover from production issues. To publish a commit that has not cleared the checks, reset the editor and go through the full policy review. ## Editor UI * **The app preview banner has a fresh look.** The old blue banner is now a neutral, dark design that matches the app builder, with a refreshed environment tag and a redesigned Publish button. **10.1.26** ## New Clark features * **Replace Excel-based workflows with production-grade apps.** You can now upload an `.xlsx` file in the Clark editor or homepage chat, and Clark reads each sheet to understand its tables, headers, computed columns, and cross-sheet references. It then imports the sheets that hold data. Files can be up to 5 MiB. * **Clark can now import CSV data into your app's database.** Upload a CSV file in chat and Clark can load the contents into any connected data source available in Edit mode. This makes it straightforward to seed your development database from a spreadsheet or Excel workbook. Clark can also process your CSV and send the data to any connected integration. * **Checkpoint cards in the Clark panel are cleaner and easier to act on.** The newest and live cards keep their Publish and Preview buttons, and every card keeps a labeled Preview so you can jump back to any version. On older cards, Restore and publish details appear when you hover, and a publish in progress shows as progress you can cancel instead of a grayed-out button. ## Clark context management and reliability * **Clark now caps oversized tool error messages.** Errors from validation, blocked access, missing tools, and confirmation-required steps are now limited to 25,000 characters, matching other tool failures. This keeps Clark's context lean, while short errors and permission behavior stay the same. * **Clark is more resilient to brief editor connection drops during generation.** If your editor unexpectedly loses its connection while Clark is building, Clark's next browser actions, like navigating the preview or taking screenshots, now wait up to 30 seconds for the editor to reconnect instead of failing right away. * **The Clear chat history button is now disabled while Clark is generating.** This prevents history from being cleared mid-turn. Stop remains available, and clearing is re-enabled as soon as the turn stops. ## Integrations * **You can now download files from REST API integrations.** Pull a generated PDF report, an invoice, or an image from a REST API and use it in your app or pass it along to another integration. For customers self-hosting data planes, upgrade your data plane to v1.50.0 or later. ## Billing and usage * **You can now filter GAU usage on the Billing page by activity type.** Filter GAUs to Clark usage or Code Security activity (Security Fixes, Security Agents, Security Scans, and CVE Scans), so you can see how much your organization spends securing applications. ## Code Security * **Policy Agents no longer run for Git-connected apps.** Pre-publish Policy Agents are now skipped for apps connected to Git. Run security and code checks in your CI pipeline for those apps. If you disconnect Git from an app, any enabled policy agents apply on the next publish. **9.24.26** ## Clark Context Management & Reliability * **Clark now catches problematic attachments before sending your message.** Clark rejects unsupported, oversized, or unreadable files before your message is saved or sent to the model. The error shows the filename, the limit for that file type, and how to fix it, and your draft and valid files are kept so you can retry. * **Clark sessions are faster and cheaper with improved prompt caching.** Clark no longer rewrites messages it has already sent each time it captures a screenshot, so prompt-cache entries stay valid and long build sessions cost less per prompt. Screenshot resolution has also been adjusted, and the stored session record is now size-bounded. * **Clark chat updates now stay in sync across open editor tabs.** Clark's responses and progress updates now appear in every editor tab you have open for the same app, even if another tab is briefly reconnecting. This fixes a case where a second tab could show "Thinking..." until you reloaded. * **Clark recovers from stuck chats caused by malformed tool calls.** Clark now repairs malformed tool names in saved chat history before sending it to the model. Retries no longer get stuck on a rejected conversation, so you don't need to clear chat history to continue building. * **Clark re-reads files less after making edits.** Clark now avoids reading a file again right after it edits or writes it, since a reported success means the change landed. This cuts unnecessary steps and context usage, so editing sessions stay more efficient. ## Billing & Usage * **Policy Agent runs are now attributed to users.** AI usage from Policy Agents is now attributed to the person who started the run. It appears under that user on the Usage page. * **Usage page now shows security and remediation GAU costs per checkpoint.** See exactly how much you spend to secure each checkpoint. Checkpoints with Policy Agents now expand into Clark Usage, Security Agent, Security Scan, and CVE Scan totals, covering both the cost of each review and the cost of addressing its findings. * **Usage page now shows all your usage, including before a contract change.** The Usage page now displays usage in units only, with dollar amounts shown only in the commitment bar. Usage recorded before a contract change, such as a trial-to-POC upgrade, now appears, and the Published app charges and Governed Agents Usage tiles are consistent across plans. ## Code Security * **New Policy Agent flags vulnerable dependencies before you publish.** A new pre-publish Policy Agent for Vulnerability Detection checks your app's dependencies against known CVEs before publishing completes, preventing your builders from shipping apps with known CVEs. Clark will upgrade or find an alternative package that's safe for production. * **Security findings stay consistent between publishes.** The policy gate and Security Agent now report consistent findings across republishes when your code hasn't changed. Issues no longer disappear, show up as duplicates, or change unexpectedly, making it easier to find, fix, and publish. * **Dependency scan findings now show the vulnerability name.** Findings from the publish-time dependency scan now show the affected package and version alongside the advisory name, making them easier to triage. * **Security emails now link straight to Fix with Clark.** Vulnerability emails (new finding alerts and the admin and creator daily digests) now take you directly to Fix with Clark for the affected app and finding, matching in-app notifications. The emails also have a cleaner layout, with color-coded severity badges and useful links. ## App Publishing * **Clark publish button no longer times out during slower builds.** The publish button in Clark chat now waits up to 15 minutes, up from 5, before showing "Timed out — Retry". Slower builds, such as those that start after an idle period, can finish without a false timeout message. * **Publish tab no longer shows a false "older version" warning on your latest version.** The Publish tab now treats a checkpoint and the commit created from it as the same version. Opening your latest version from history no longer triggers a restore-version warning, and the header and pipeline stay consistent. * **Publish tab now explains when you lack publish permission.** There is now a clear message on the Publish tab when you don't have permission to publish the app, with guidance to contact an admin. You can still create a Preview if you have permission. * **The Live tag in the Publish tab now opens your published app.** Clicking **Live** in the Publish tab header of the 2.0 app editor now opens the deployed app in a new tab. This matches how the Live badge already works in chat checkpoint cards and the history panel. ## Embedded Apps * **Embedded previews stay working after you publish a new version.** Embedded app previews that were already open no longer fail with "not found" errors when a new version is published. Open sessions keep loading the version they started on, so users aren't interrupted mid-session. ## Environments & Data Tags * **Switch environments for your editor session without changing app settings.** You and Clark can now change the selected environment (data tag) for your current session without touching saved app settings. Use the new "Selected for this session" picker in the Edit section of the Environments sidebar, or ask Clark, who will confirm with you before switching. * **New permission to manage app environments.** A new permission determines who can add or remove environments in an app. This enables admins to keep sensitive environments, like a restricted Dev or Prod variant, out of builders' apps unless they are explicitly added by a user with this permission. The built-in Developer role includes this permission, but you can create a custom role that excludes this permission. **9.14.26** ## New Clark features * **Clark can now run approved schema changes on external PostgreSQL databases.** In Build mode, Clark can run a single DDL statement, such as creating or altering tables, indexes, and views, against external PostgreSQL-family integrations after you approve it. * **Clark can now uninstall packages from your apps.** Clark can remove packages as well as add them, which makes it possible to fix vulnerabilities that require dropping a dependency. * **Clark chat history now appears right away when you open the editor.** Recent messages now show up as soon as the editor opens, without waiting for the live-edit environment to connect. You can also scroll back to load older messages in long conversations, so earlier history stays available. ## Clark context management and reliability * **Clark reads files more efficiently with fewer wasted tokens.** When Clark reads specific line ranges of a file, the reported range now matches the lines actually returned. Overlapping ranges are merged and returned in file order, so no lines are repeated. This cuts token usage during builds. * **Clark no longer fails with a "Maximum call stack size exceeded" error during error logging.** Clark now handles error logging reliably, so a logging problem no longer surfaces as "Failed to get response from LLM provider". * **Clark handles large API test errors without losing context.** When an SDK API test fails with a very large validation error, Clark now shortens the error before reading it, so it no longer fills the model's context. The actionable message is kept first, and small errors are shown unchanged. * **Clark no longer fails on conversations containing emojis.** Long Clark conversations with emojis or other special characters now compact cleanly, so they no longer cause model errors. Existing conversations that were affected can continue without clearing history. * **Invalid PDF attachments are now caught at upload with a clear error.** Files that look like PDFs but are not valid are rejected when you upload them, so they no longer break the rest of your chat. If a model provider rejects an attachment, Clark now explains the cause and what to do next instead of showing a generic error that suggests retrying. * **Switching back to Clark Chat no longer flashes a loading screen.** Returning to Chat from the Versions or Environments tabs in the Clark panel now shows your conversation right away, so you no longer see a brief loading skeleton or flicker. ## Integrations and APIs * **API code can now read the current data tag with `ctx.dataTag`.** APIs can read the server-validated data tag (such as staging or production) via `ctx.dataTag`, so you can run checks like permission assertions only against production data. For customers self-hosting data planes, upgrade your data plane to v1.51.0 or later. * **APIs can now scan DynamoDB tables larger than 1 MB.** DynamoDB scans in your APIs can now page through large tables instead of silently returning a partial result. New options let you pass a start key, index name, limit, and related AWS fields. Existing scan and table query calls work unchanged. For customers self-hosting data planes, upgrade your data plane to v1.51.0 or later. * **Test Connection now works for secrets stores attached to multiple environments.** Testing a secrets store connection no longer fails with a 401 error when the store is attached to multiple data tags and uses named agents. Test Connection now uses the same profile your agent routing selects, so you see real connection results instead of profile errors. ## Editor and UI polish * **Homepage now shows up to 20 recent apps in a scrollable grid.** The recent apps section expands from 3 apps to a wrapping grid of up to 20, about five per row, so you can jump back into your work faster. * **Refreshed look for the Integrations and Apps pages.** The Integrations and Apps pages have a cleaner light-theme design. Integration forms disable Save, Cancel, and Delete while a connection test runs, and the Apps page shows folders and apps together in one grid. Integrations now load with a skeleton instead of flashing an empty state. ## Environments and data tags * **Environments and self-hosted data planes now live on one Data setup page.** Admins can now configure data tags and the data planes that serve them in one place. Clicking a tag highlights the data planes that serve it, and each tag shows how many active data planes cover it. * **The data plane setup wizard is now a paged flow.** The wizard uses Next and Back instead of one long scrolling page. When App Databases is enabled, it collects data-plane identity and AWS networking inputs and generates Terraform and Helm configs from them. * **You can now restore a removed Default integration configuration.** If you have removed the Default configuration for an integration, the options to add Default and tagged configurations now appear again. Restoring Default opens a fresh form ready for editing, and creating tagged or cloned configurations works as before. **9.8.26** ## Highlights **Improved data tag management**: We have revamped the admin experience for managing data tags to make it simpler to set the defaults within apps and provide more controls to Admins around who can modify the available data tags. Specifically: * Admins can now set a default data tag per environment. This data tag will be the only tag available by default in all new apps. * We've introduced a new permission for `apps:manage_environments`. This permission controls whether a builder can modify the data tags available to their app, so admins can prevent builders from enabling access to sensitive integrations configurations and data planes. * Clark now has information about the available data tags per environment, plus the ability to add and remove data tags from an app for builders with this permission. * All of these enhancements are important for App Databases, since the available data tags determine the database lifecycle. **Support for binary API responses**. You can now build APIs against integrations that return binary data, so apps can retrieve images, audio, and other files from external systems. For customers self-hosting data planes, you'll need to upgrade your On-Premise Agent to v1.50.0. ## Clark AI * **Increased context window size**: Clark now has 2x the context window, reducing summarization and improving Clark's focus in longer sessions. * Improved context management for Clark reading API documentation. Clark no longer reads full API documentation files, reducing context bloat and summarization. ## Code Security * Added the ability to "Fix with Clark" for any CVE from the Security Center. ## Everything else * Clark will no longer incorrectly guide users to use Git to publish their applications for any apps that are not connected to Git repositories. * Show lock screen instead of crash when another user is currently editing an application * Fixed a misleading "Token took too long to load" error shown to users viewing published apps * Redesigned edit mode error empty state when the editor fails to load * Fixed bug where "Clear chat" only cleared the session history for the current user. Clearing your chat history now clears the history for all builders as expected. * Any user with `billing:manage` permission can now see the checkpoint labels for all checkpoints in the Billing & Usage page. Previously the label was incorrectly redacted unless the viewer had the org-wide `apps:update` permission. **8.25.26** ## General improvements * Idle users no longer prevent other users from editing apps. If a user steps away or their computer goes to sleep, teammates can now take over their editing session instead of waiting for the editor to explicitly close their editing window. * **Upload images to Clark from the Knowledge page**: Fixed bugs with images uploaded through the Knowledge Clark chat that were resulting in errors. ## Code Security * **Notifications for new CVEs**: Every hour, Superblocks scans all packages across your published apps for new CVEs and notifies you when something new appears. You'll receive an hourly in-platform notification in your inbox, plus a daily email digest. * You can now drill into the App detail page from the Security Center to view the software bill of materials (SBOM) for the currently published version and all historical versions. * **Advisory and Blocking with Exceptions**: You can now set Security Scans and Security Agents to run as Advisory or Blocking with Exceptions. Advisory Policy Agents do not block publishing. Blocking with Exceptions prevents publishing, but builders can bypass and Publish anyway for false positives. ## Integrations Platform * **REST integrations support OAuth with PKCE.** Authorization-code flows can use PKCE for both public and confidential clients. If your organization is self-hosting your data plane, you'll need to upgrade to v1.49.0 to access this functionality. * **Admins can now delete the default integration configuration**. This is relevant if an integration is not accessible for certain data tags; for example, if an integration is only accessible from a specific on-premise agent due to network isolation. * "Connect your data" is hidden from the Clark chat for users that don't have permission to create integrations. **8.19.26** ## Clark AI * **Fewer false write-approval prompts on SQL.** Clark ignores `--` comments when deciding whether an API is read-only, so words in comments (for example "set" in "set of") no longer trigger an approval prompt for a read. * **Improved stability for app upgrades.** Legacy apps with hundreds of APIs can be upgraded without running out of memory. ## Everything else * A new publish does not break the app for any live users. Open sessions keep running on the version that a user has loaded instead of breaking when a new version goes live. The previous version stays available for up to 12 hours after it's replaced. * **Smoother app loading.** Opening an app now shows one continuous progress bar through startup instead of a spinner that restarts at each step. * **Long "Created by" names** (such as email addresses) no longer overflow the homepage list. **8.14.26** ## Highlights **Unified version management and publish flows.** We've dramatically simplified how builders move from a checkpoint to Preview or Production. * Every checkpoint in the Clark chat can be built into a Preview or published to Production * You no longer need to manually commit just to generate a Preview * Version history lives directly in the Clark chat panel — click the versions icon at the top of chat * Every Preview and Publish has a detail view for progress and errors, and is where pre-publish actions such as security scans and database operations are surfaced [Learn more →](/building-with-clark/checkpoints) **Improved Billing & Usage page.** We redesigned Billing & Usage so admins can analyze spend and understand ROI more easily. * GAU usage rolls up to the relevant Clark checkpoint, so you can see what it cost to deliver a specific outcome * Group usage by User, App, and Day to find the highest-ROI work * See which published apps are charged each month, including pending charges * Break spend down over time across GAUs, published apps, users, and more with charts and filters [Learn more →](/admin/plan-and-usage) **Upgrade 2.0 apps to 3.0.** If you were building with Clark before April 2026, your apps may still use the legacy YAML API format. Upgrading to TypeScript APIs unlocks the latest editor and Git features. Clark runs the upgrade for you. [Learn more →](/building-with-clark/migrate-to-typescript) ## Clark AI * **Clark can write to integrations with your approval.** In Build Mode, Clark can run one-off data updates and similar mutating API or database calls from chat after you approve each action. * **More accurate read vs write detection for Postgres.** Clark uses a real PostgreSQL parser instead of keyword matching, so you get fewer false permission prompts and fewer accidental write allowances. * **Better Clark context management.** Clark does less redundant summarization mid-conversation, so it stays smarter and more consistent throughout longer sessions. * **Clark context is shared for the whole app.** Clark's reasoning context is scoped to the application, not each individual editor. Previously, the chat could look shared while Clark was missing another teammate's context. * **Clark no longer gets stuck on "Thinking…".** If the connection drops mid-turn, Clark recovers and continues instead of leaving you hanging with no response. * **Clark @-mention category drill-down.** Clicking a category such as APIs or a database lists the entities in that category instead of showing "No entities available." * **Chat messages no longer scroll from the top when loading.** Opening a conversation now lands directly on your newest message, instead of visibly sweeping down through the history while it loads. ## Everything else * **Filter homepage apps by deployment status.** The apps list supports All / Deployed / Not deployed. Unpublished apps show "Not deployed" instead of a stale last-published date. * **Self-serve teams are no longer limited by builder seats.** Self-serve / Teams plans no longer use seat-based pricing, so your whole team can use Clark without being constrained by the number of builder seats. * **Upload images up to 50MB.** Give Clark larger screenshots and reference images as visual context for building your apps. * **Rotate Git tokens without disconnecting.** When Git Setup is healthy, you can update your Git credential in place instead of disconnecting and reconnecting. * **Shareable published app URLs stay clean.** Published app links no longer append an internal version query param, so URLs you copy and share remain stable. * **Admins can inventory packages across the org.** Listing distinct npm packages used across your organization (for security and supply-chain reviews) now requires the `policies:manage` permission, which Admins and Owners have by default. You can also assign that permission to other roles. * **IdP re-auth in published apps.** When an On-Behalf-Of OAuth token expires, the re-auth popup opens from a real user gesture instead of leaving end users in a dead-end state where APIs cannot execute. * **SCIM display names.** User updates now keep the display name sent by your identity provider. **7.25.26** **Clark AI** * **Clark API testing stays scoped.** When you edit an API in a shared file, Clark tests only that API instead of forcing tests on unrelated APIs in the same entry point. * **Typed answers to multiple-choice questions appear in order.** If you type a custom answer instead of clicking a choice, it shows up in chat in the right place before Clark continues. * **Clarifying text during tool-permission prompts is guidance.** Extra text you enter while approving or denying a tool call is passed to Clark as guidance instead of being treated as a denial. * **Clark chat no longer flashes in the side panel.** On initial load, chat settles in the center without first appearing briefly in the side panel. **Everything else** * **No Superblocks top bar on published apps.** Published apps no longer show the black bar with built-in Superblocks branding. * **Publish button is only visible for users with permission to deploy.** Builders without deploy access no longer see a Publish button they cannot use. * **Homepage visual polish.** Refreshed the homepage color palette, icons, and avatars for a cleaner look and feel. * **Non-JSON API responses.** Superblocks can now connect to API endpoints that return XML, CSV, HTML, or plain text. Previously, responses were decoded as JSON and failed on anything else; you can now request a text response and get the raw body back. * **Integration forms show saved bound field values on first paint.** Bound fields no longer appear blank until you focus them. **6.16.26** ## Highlights **Major stability improvements across Clark and the Superblocks Editor.** We've made sweeping reliability and performance improvements across Clark AI and the Superblocks editor. Users should no longer see model response errors, hanging "Thinking…" states, slow editor loading, random disconnections, or other common error states. We're continuing to invest here to improve the stability of the product. **Improved spend management.** The Billing & Usage pages now have more granular data and new spend management controls. Usage is now tracked per-application, giving more granular insight into where credits are spent. We also now support **Spend Alerts**. Set a threshold and get notified before any builder hits it. **Code Security is now in Beta.** [Code Security](/admin/code-security/index) policies scan your apps for security issues before they are published, keeping your security team in the loop without slowing down builders. ## Everything else **Clark AI** * Clark now maintains a checklist to track and manage tasks during large builds and migrations, making it more accurate and effective for complex, multi-step work * Clark can now navigate between pages to take screenshots, enabling it to verify multi-page apps and catch rendering issues across routes * Clark now self-fixes common import errors (e.g., type-only imports used as values) that would previously cause blank previews and block UI verification * Better tool timeout handling — long-running tools like API verification now have appropriate timeouts (up to 5 minutes), reducing false failures on slow API or LLM calls **Embed & app loading** * Embedded app bootstrap is more reliable — the iframe handshake now retries on both sides so slow-loading embeds complete instead of timing out with "Authentication Error" * Fixed data tag switching in embedded 2.0 apps — `setDataTag()` now correctly re-syncs the profile in the deployed shell * Commit preview now works correctly for code-mode apps that have commits but have never been deployed **Integrations & workflows** * Fixed a bug where workflows called from an app would use the wrong environment — the data tag display name was being sent instead of the data tag key * Fixed Databricks and other OAuth integrations getting stuck for up to 10 minutes on an expired token — tokens are now reactively evicted and re-exchanged when a provider rejects them * Fixed GraphQL and other integrations failing to save due to validation errors **Git Sync** * Fixed "Cannot commit in draft mode" errors that blocked users from committing even when they were not in an active AI session, caused by an uninitialized or stuck draft state * Commit errors now show the real error message instead of `[object Object]` in the toast notification **Import apps into Superblocks** * Streamlit is now a first-class app import source in the migration modal, with its own icon, prompt copy, and detection signals **MCP** * New MCP tool `list_distinct_packages_in_org` lets a security or platform owner enumerate the distinct npm package footprint across an entire org in a single call **5.20.26** ## Highlights **Set your default AI inference for all features your team builds.** IT Admins can now configure a default AI integration that Clark uses automatically for all AI-powered app features. Set your preferred AI provider once, and builders get immediate access to AI capabilities without needing to think about configuration. [Learn more →](/integrations/app-ai) **Git-based source control is now GA.** Connect your Superblocks applications directly to GitHub, GitLab, Bitbucket, or Azure Repos. Full version control for your apps in your repo without needing to be a Git expert. [Learn more →](/development-lifecycle/version-control/connect-to-git) Source Control is only available for apps with TypeScript-backed APIs. As mentioned below, the migration system to port legacy Clark apps to the new API format is coming soon. **Set spending limits at the organization and user level.** Enterprise customers can now configure spending limits to control AI credit usage across their organization. Set limits at the org level or per individual user to ensure costs stay within budget while giving teams the flexibility they need. [Learn more →](/admin/spend-management) **Embedded apps now load 50-80% faster.** We've rebuilt our Embed architecture from the ground up with a new deployment shell that dramatically reduces load times for embedded applications, especially for users in different regions. ## Everything else * Increased Clark text file upload limit to 3MB for better support of larger documents and datasets * Fixed out-of-order chat messages when typing custom prompts instead of using multiple choice widgets * Eliminated thinking indicator jitter when knowledge messages arrive during conversations * Added automatic and manual AI credit top-up for self-serve customers so you can build seamlessly without being interrupted — [Learn more →](/admin/self-serve-plan#gau-refills) * Added geolocation API support for deployed applications — apps can now access `navigator.geolocation` when embedded **5.5.26** ## Clark AI Improvements **Import apps from any platform.** Upload zip files containing applications from other platforms or built with Claude/ChatGPT directly to Clark. Clark can now extract, analyze, and help you migrate these apps to Superblocks. **Smarter write operation detection.** Clark now more accurately identifies when API calls are read-only vs. write operations, reducing unnecessary permission prompts. **Stability fixes:** * Fixed issues where Clark would get stuck on "Summarizing conversation" after connection interruptions * Improved the restore functionality in Clark's checkpoint interface ## Integrations & Authentication **Streamlined team onboarding.** New users with matching email domains can now discover and join their organization during signup. * Enhanced the AI Builder license assignment flow for adding team members * Added a Usage tab to integration pages showing which applications reference each integration * Improved support for on-behalf-of token exchange integrations, allowing Clark to test APIs that require delegated authentication * Fixed scrolling and multiple selection issues when choosing integrations in the chat interface ## Editor & Development Experience **Faster API execution.** Removed editor overhead from the SDK API execution path, improving API response times during development. * Added Input/Output preview pills to API request panels with detailed popovers * Added end-to-end timing summaries to SDK API trace views * Users can now skip the datasource selection step in the onboarding survey * Improved the integration home page filters with better "select all" and "deselect all" behavior * Enhanced visual feedback when Clark is testing APIs and requesting permission to test write operations * Various UI polish including improved chat loading animations ## Billing & Usage Improvements **Better credit handling.** Users can now open and work on applications even when out of AI credits — quota enforcement now only applies to actual AI prompt usage. * Improved trial-ending emails with clearer billing information and direct links to billing management * Removed unnecessary Stripe bundle loading from deployed applications for better performance * Added audit events for application undeployment actions **4.23.26** ## Highlights **Edit mode now starts in under 10 seconds - significantly faster than previous startup time.** Starting a new editing session on any app — new or existing — is now lightning fast. No more waiting for your app to load before you can start editing. **One-click publish from Clark checkpoints.** You can now publish your app directly from each checkpoint in your Clark conversation. Just click and it automatically creates a commit, builds your code, and publishes — streamlining your entire deployment workflow. **New Superblocks MCP tools for platform management from your IDE or AI Client.** Three new capabilities in the Superblocks MCP server give teams programmatic access to platform operations directly from AI coding assistants, CLI workflows, and automation scripts: * **Role Management** — Assign and update organization-level roles (Admin, Developer, End-User) for users and groups from your favorite AI tool. Useful for onboarding automation, bulk role changes, and scripted access control. * **Chat History Retrieval** — Retrieve the full conversation history between your builders and Clark AI for any application. See what prompts were sent, which plans were approved, and what screenshots were attached. Valuable for auditing how apps were built, onboarding new team members to an existing app's context, examining the intent behind AI-generated code, and identifying potential abuse. * **Audit Event Aggregation** — Run server-side analytics over your organization's audit log without downloading raw events. Answer questions like "how many unique builders were active this month?", "what's our daily API execution volume?", and "which apps have the most activity?" — makes it easy to report on your team's usage and take action. ## Everything else * Clark sidebar now shows actual knowledge entry names instead of generic "Read app knowledge" * Prevented users from uploading unsupported file types which would break Clark's chat context and result in chat errors * Fixed cmd+click and hover preview for links in deployed and preview apps * Fixed integration setup forms not populating field values reliably when viewing or editing connections * Added auto-focus on search input in the "Connect your data" modal * Fixed Clark checking integration create permissions before opening setup forms — no more confusing permission errors after configuring the fields because you don't have permission on the integration * Improved Clark's error handling when integration metadata isn't available * Added a grid view toggle to the apps homepage — switch between the familiar table view and a new visual grid with app screenshots for easier browsing **4.13.26** ## Highlights **New Audit Logs and Superblocks MCP.** Track everything happening across your platform — who's building apps, running queries, what packages are in use, integration access, and more. When something suspicious happens, investigate and take action through our new [Superblocks MCP tools](/admin/mcp-server): lock out malicious users, undeploy compromised apps, or respond to supply chain attacks. **Superblocks 2.0 APIs (APIs as code) are now generally available.** Clark now builds all [APIs in TypeScript](/building-with-clark/backend-apis), making generations faster, more accurate, and easier for humans and AI to code review and edit. We've also dramatically improved the experience of building these APIs, including: 1. A detailed trace viewer to understand individual queries and timings run as part of your API 2. Real-time visibility into API calls as you use your app, making it simpler to correlate your UI with specific APIs 3. A code editor in the browser for reviewing the underlying React and TypeScript code All new apps will be this new format for: 1. All Cloud customers 2. OPA customers on v1.37.1 or higher We're also going to provide a migration path for existing Clark apps in the coming weeks. **Clark can now create integrations directly in your app.** No more navigating to the Integrations page and filling out forms manually. Clark sets up, configures, tests, and saves connections right where you're building. ## Clark improvements * Added the ability to commit, build, and publish right from a checkpoint in the Clark chat * Clark is now more effective at building custom logic based on user attributes * Clark is now more effective at building custom logic using Data Tags * Fixed display issues when referencing integrations with special characters in their names * Chat now properly auto-scrolls to new messages, fixing issues where auto-scroll would break * Clark no longer incorrectly requests permission to test read-only APIs * Fixed "No metadata found" errors when Clark explores integration capabilities * Copy buttons for code blocks: hover-to-reveal copy button for syntax-highlighted code blocks in Clark chat * Expandable package install messages: "Installed X packages" messages can now be expanded to see which packages were installed ## Integrations & authentication * Eliminated "Authentication token scope value is incorrectly formatted" errors for Slack per-user OAuth * Valid identity provider JWTs now refresh silently instead of opening new browser tabs * Better integration sorting: page now sorts alphabetically by default with properly working "Created by" column sorting * Fixed blank integrations screen for new organizations with no connected integrations ## User management * Cross-org user transfers now work: if someone on your team mistakenly creates their own organization, you can invite them to join your org and they'll be transferred over ## Billing and plans * Fixed blank billing page for POC and other non-standard plans * Clearer prorated costs: preview invoice for Teams customers now shows accurate prorated amounts instead of confusing totals ## Navigation and editor * "Start building" button in Clark introduction modal now navigates to homepage * Fixed folder breadcrumbs showing org name instead of "Apps" when navigating folders * Version panel now links to appropriate docs based on both template type and Git configuration * Added helpful guidance when attempting to commit without Git configured * Hidden Developer Preferences panel for fullstack apps where it's not applicable * Route load errors are now properly forwarded to Clark AI for diagnosis * Fine-grained progress for editor start: live edit loading now shows a 4-step progress indicator tied to real connection phases instead of generic rotating messages * Simplified sidebar: removed pin/unpin feature and added close buttons to all panels * Fixed returning from deployed app going to /integrations instead of /home ## Bug fixes * Added safety measures to prevent file corruption during multi-file edits * Integration names now appear correctly in Superblocks 2.0 API trace views * OAuth setup errors now properly surface to users instead of failing silently * Redesigned email templates: new clean card layout for org invites, transfers, verification, and share invites * Fixed bulk delete on home page failing with transaction errors **3.28.26** ## Clark AI * File uploads re-enabled across all Clark surfaces — app conversations, the homepage, and Knowledge * Clark now references the Superblocks public docs, making it better at working with integrations and other platform-specific features * Several improvements to Clark's context management — Clark stays focused better throughout longer sessions, large files are automatically size-limited, and compaction no longer drops active task state * Enabled SMTP plugin support for Clark — you can now build email-sending workflows with SMTP integrations * Clark no longer disconnects mid-generation if you switch to another browser tab * Fixed a bug where chat history was lost on page refresh during active generation * Fixed Clark attempting to edit code while in plan mode — a regression that caused unnecessary correction loops ## Clark Knowledge * Empty state added to the Knowledge canvas when no item is selected * Added a link from the in-app Knowledge panel to the admin Knowledge page for easier management * Fixed knowledge promotion failing after a previous hotfix * Fixed a permissions issue that blocked saving integration knowledge with a 403 error * Friendlier error messages in Knowledge chat when issues occur ## Billing & self-serve * New AI Credit Usage chart with daily usage breakdown * Teams plan users can self-serve purchase additional deployed apps ## Integrations * Fixed the save modal for integrations with data tag configurations — the connection test flow now works correctly when data tags are set * Fixed creating integrations in Clark AI mode failing for certain plugins (e.g., Salesforce) due to a schema validation error ## Source Control with Git (beta) * Ask Clark to help you set up and manage your Git repository — connect to a repo, commit changes, view diffs, and check branch status from the chat * AI-generated PR descriptions when opening GitHub PRs from Superblocks * Clearer error messages when commits fail — including specific guidance for insufficient GitHub PAT permissions ## Bug fixes * Fixed BigQuery auth being stripped in deployed mode, causing token expiration for customers using Workforce Identity Federation * Fixed Databricks Token Federation re-authentication — deployed apps now correctly prompt for re-auth, and the editor re-executes APIs after authenticating * Fixed long links breaking the chat panel layout **3.19.26** ## Highlights * **Clark now accepts file uploads when building apps.** You can share PDFs, CSVs, Markdown docs, and other files directly with Clark — both in app conversations and from the Superblocks homepage. Give Clark your actual schemas, data, or docs to work from instead of describing them by hand. * **Promote app knowledge to your whole organization.** Insights you develop while building — about your integrations, data, or workflows — can now be promoted to broader scopes: org-wide, personal, or integration-level. Knowledge compounds across your team instead of staying locked to a single app. ## Other improvements **Clark AI** * Tag integrations when starting a conversation from the homepage — Clark gets immediate context about your data sources before you even create an app **Clark Knowledge** * Markdown tables now render correctly in Knowledge forms and the rich-text editor * Knowledge page updated with inline actions, a refreshed icon, and cleaner empty-state copy **Billing & self-serve** * New Usage & Credits page with role-based billing action * Plans & Credits page updated with a builder seats table, seat assignment modal, and checkout flow for Teams customers ## Bug fixes * Fixed up to 3 duplicate API calls firing on page load when only 1 should run * Fixed WebSocket and AI stream disconnects going undetected and added better observability to surface these failures proactively * Minor fix to integration tagging height on the Clark homepage **3.10.26** ## Highlights * **File attachments in Clark Knowledge.** Upload documents like design guideline PDFs, CSS stylesheets, internal docs, or security guidelines; Clark uses them to build out knowledge optimized for his own consumption when building. No more copying and pasting content in manually. * **Start building from [superblocks.com](https://www.superblocks.com).** Type a prompt directly on the marketing site and land in a working app. You can start building even before you log in. ## Bug fixes * Fixed a bug where Clark could time out when testing APIs * Improved Clark API generation accuracy by fixing an SDK documentation regression — Clark now generates working APIs more reliably on the first try, with fewer correction loops * Fixed UI flickering that occurred when Clark reads system skills during prompting * Fixed certain read-only APIs not correctly triggering approval prompts when Clark attempts to test them * Fixed cleared Clark chats reappearing after a checkpoint refresh * Fixed queued prompts causing horizontal scrolling in the AI chat sidebar * Fixed an issue causing AI model errors for some users * Fixed a handoff bug that could leave apps uneditable when switching between users **3.6.26** ## Highlights * **Clark is now available to everyone.** Clark AI is out of private beta and open to all. New users can sign up for free at [superblocks.com](https://www.superblocks.com), start a free trial, and upgrade to the Teams plan entirely self-serve. No more waitlist. * **New Snowflake integrations: Cortex AI and Postgres.** Superblocks now connects natively to both Snowflake Cortex AI and Snowflake Postgres. If your team is in the Snowflake ecosystem, you can bring AI-powered queries and Postgres-compatible data sources into your apps seamlessly. * **A new homepage for building.** The new Clark homepage puts a prompt box front and center. The first thing you see when you log in is the Clark prompt box and your most recently edited apps, so you can start building immediately. ## Onboarding * New onboarding survey flow helps tailor the experience when you first sign up and start using Superblocks * We added a banner to the apps list to help existing Low Code users easily navigate between Clark AI and their legacy apps and workflows ## Clark improvements * The Org Knowledge editing experience now includes an accept/reject diff workflow. You get an explicit review step before any changes are saved, and the Knowledge panel refreshes immediately after. ## Bug fixes * AI/Code Mode requests no longer fail when app screenshots are very large. They're now scaled down automatically. * Fixed a bug where saving an app knowledge fact could put the app into a broken state * Fixed a bug where Clark would stop responding after you replied to a multiple-choice question about app knowledge * Fixed a routing issue where Clark's app view would be stuck in the center of the screen when routes were defined in a variable * Prompts containing UUIDs are no longer incorrectly blocked by chat guardrails * Downloaded app file names now reflect the actual app name * Fixed the API panel getting stuck open with no way to exit in code mode * Fixed a visual flicker and improved save UX in the Edit Data Tag modal * Fixed a bug where the REST Base URL was silently discarded when saving an integration * Fixed a package installation failure in cloud edit mode caused by npm being overridden by pnpm * Default data tag selection is now pre-populated for a smoother setup experience **2.26.26** ## Highlights * **Clark in [Organization Knowledge](https://docs.superblocks.com/admin/org-administration/knowledge).** You can now chat with Clark directly in the admin panel to set up your organization knowledge. Clark helps you articulate your org's conventions, integration nuances, and personal preferences through conversation, making it faster and easier to get your knowledge dialed in. As a reminder, knowledge works at three levels that Clark follows by default: * [**App Knowledge**](https://docs.superblocks.com/building-with-clark/knowledge/app-knowledge)**: Clark remembers context per app.** You can now ask Clark to remember facts, architecture decisions, and context specific to an app — just prompt it during a session. Clark stores these as app-level skills and uses them in future sessions, so the more you build, the better Clark gets. No setup required — just tell Clark what to remember. * [**Environment access controls**](https://docs.superblocks.com/admin/environments)**.** Admins can now configure which data tags are available in each Superblocks environment — edit, preview, and production — directly from the new Environments admin UI. This makes it easy to lock down production data so builders and Clark only work against the right environments. ## What's next * **Knowledge promotion.** Soon, you'll be able to save knowledge directly to your organization from chat while building apps. Today, you can save app knowledge during a build session, and org knowledge when chatting with Clark in the admin. Knowledge promotion bridges the gap, so insights you surface while building flow back to your org knowledge without leaving the app editor. * **Improved onboarding experience.** We're working on making it easier to get started with Superblocks, including a new home page, the ability to set up integrations by talking to Clark, and a more seamless commit and deploy flow. * **APIs as code.** We're moving to code-based APIs written entirely in TypeScript — a new format that Clark can generate more accurately and is easier for you and your agents to review and maintain. * **Source Control for Clark Apps.** We're adding the ability to sync your Clark app code to remote Git repositories for code review and automation. ## Other improvements * Web exploration links are now clickable in the results panel for easier access to referenced sources * Open share modal immediately when you create an integration for easy access control management * Restored manual JavaScript/Python/REST/GraphQL step creation in API editor * Increased UI timeout for OPA healthchecks to reduce "unable to connect to on-premise agent" errors * App debug downloads now use zip format for easy sharing ## Bug fixes * Fixed issue where Clark would hang indefinitely when testing APIs — the system now properly handles timeouts and error states * Fixed bug where reference images uploaded with the first prompt were lost and couldn't be included in plans * Fixed bugs with API runs showing error exclamation points and green checkmarks on a single run **2.20.26** ## Highlights * **Queue prompts and steer Clark mid-generation.** You can now send messages while Clark is working — queue up follow-up instructions as ideas come to you, or interrupt and redirect Clark mid-generation if it's heading the wrong direction. No more waiting for Clark to finish before giving your next thought. * **Organization Knowledge beta is now open to all customers.** We've opened up the Org Knowledge beta to everyone. You can define knowledge at three levels that Clark follows by default: * **Organization** — design system and brand guidelines, coding standards, team conventions, and other org-wide context * **Integration** — nuances about your data sources, schema quirks, naming conventions, query patterns, and other details that help Clark work with your APIs correctly * **Personal** — your individual preferences and how you'd like Clark to work with you ## Clark improvements * Screenshots now capture full pages and wait for content to fully load before analyzing, so Clark no longer reasons over incomplete UI states * Improved context summarization to better track build completion — Clark no longer asks about next steps after successfully making proposed changes * Added a warning when users enable too many Knowledge entries ## Data exploration in Clark Chat * Enhanced JSON view inside results tables for better readability * Improved handling of truncated API outputs with clear messaging and partial result display ## Bug fixes * Fixed retry UI showing incorrect success messages when AI model requests were paused or failed * Fixed success toasts incorrectly showing for failed API calls * Clark no longer incorrectly requests permission to test read-only APIs * Clearing context now properly clears in-memory data to prevent recurring inference errors in edge cases * Fixed checkpoint restoration to avoid a rare race condition where users could not restore to past checkpoints **2.12.26** ## Highlights * **Clark is now powered by Claude Opus 4.6.** Clark now runs on Anthropic's Claude Opus 4.6 — the world's best coding model. You should see improvements across the board in code generation quality, reasoning, and Clark's ability to handle complex app-building tasks. * **Clark automatically optimizes for large datasets.** Apps generated by Clark now automatically implement pagination, virtualization, and server-side aggregation when working with large datasets. This means fewer browser slowdowns and better performance out of the box — no extra configuration needed. * **Agent Memory is in Beta.** We're rolling out the first piece of Clark's memory system: organization-level knowledge. Admins can now define facts about your org, integrations, and users that Clark follows by default — things like coding standards, integration quirks, and team conventions. Reach out for access! ## Clark improvements * Clark now handles API call failures gracefully — errors display in the UI instead of appearing to hang indefinitely * You can now skip testing specific APIs and still complete generation when Clark encounters API test rejections * Improved Clark's ability to inspect historical API runs * Fixed false positives in safety checks that were blocking legitimate internal security audits ## Editor experience * Added mobile view support on the editor canvas * Fixed profile switcher being disabled when chat is in fullscreen mode * Returning to the editor after idle time no longer shows a fullscreen connection error — it automatically reconnects * Fixed chat sidebar opening before the app has fully loaded * Fixed pages opening in new tabs getting stuck on a loading screen * Fixed full page reloads when navigating between pages in deployed apps ## API & integrations * Added Salesforce OAuth 2.0 Token Exchange support for authentication via Login Identity Provider * Added BigQuery Workforce Federation authentication * Fixed API errors silently failing — Clark now properly throws errors when an API run fails * Fixed Databricks SQL queries getting corrupted when manually editing code * Improved handling of integrations with large OpenAPI specs — metadata search no longer hangs * Fixed Python code with escape sequences getting corrupted **2.6.26** ## Highlights * **Clark can now explore data when planning without asking for permission.** Instead of prompting for permission to read, Clark can explore your integrations automatically at your direction to figure out the right approach. Query results appear right in the chat so you can see exactly what Clark is working with, drill in, and guide it toward the right queries. * **Clark tests APIs faster.** We cut API test latency significantly — previously this could take 30+ seconds. Things should feel noticeably snappier when Clark is building and validating APIs for you. * **New safety protections.** Clark now detects and blocks malicious or unsafe prompts, and we've added protections to prevent system prompt extraction attempts. These safeguards run automatically in the background. * **New integration: Databricks Lakebase.** You can now connect to Databricks Lakebase directly from Superblocks. ## Clark improvements * Clark can now offer up to 6 options for multiple choice questions * Fetched links are now clickable in web exploration * Improved retry experience when Clark falls back across models and inference providers * Clark now knows it cannot navigate between pages to take screenshots, reducing unnecessary loops ## Deployed apps * Opening app pages in new tabs now uses the correct URLs * Cleaner deployed app URLs (removed `deployed_at` timestamp) ## Editor experience * Fixed issue where typing "ms" quickly would accidentally trigger preview mode * Keyboard shortcuts like Cmd+Click now work correctly in fullscreen mode **1.26.26** ## Highlights * **Clark now stays smart over long sessions.** Previously, Clark would lose context as conversations grew. Now Clark maintains a working memory—automatically retaining what was accomplished, key decisions, and constraints discovered. * **API generation is significantly faster and more accurate.** We rewrote core parts of how Clark understands and generates APIs—full support for control flow features, a completely rebuilt parameterized SQL system, and improved handling of API documentation. Fewer mistakes, faster results. * **Inference errors no longer block you.** Intermittent Vertex/Bedrock errors are now handled gracefully—if you see one, just send another message and Clark will recover. * **Clark can search the web**. Clark can now perform real-time web searches. This is especially useful for using third-party libraries and looking up documentation for integrations in real time. ## New capabilities * **Embedded apps with two-way communication.** Superblocks apps can now communicate with parent apps and vice versa. Ask Clark to set up the interface for properties and events. * **Windows local development.** Powershell support—no WSL required. ## Clark generation improvements * Clark can now build file upload features (e.g., send a file to an AI model or upload to bucket storage) * Clark can now build apps with data tag switching * Clark can now modify REST API body content types reliably * Clark is better at targeted UI edits thanks to improved context about UI component layout * Clark tests APIs faster * Clark no longer hits timeouts when testing APIs ## API generation * Added support for all control flow features * Rewrote parameterized SQL system—Clark can now always write parameterized SQL accurately and safely queries when parameterization isn't possible * Improved handling of API documentation and integration OpenAPI specs * Fixed API transformation so Clark always sees user modifications * Fixed missing bodyType field in REST API type declarations that caused TypeScript errors * Added missing integration class declarations for 8 data sources (S3, MongoDB, GraphQL, and others) * Prevented Clark from reading redundant JavaScript files in API directories ## Chat experience * Improved performance and reduced flickering for chats with many messages * Chat no longer appears stuck thinking—now distinguishes between model thinking and time between tool calls * Keyboard shortcuts for multichoice responses * Fixed newlines not rendering correctly in AI-generated summaries * Removed duplicate reconnection messages ## Plan mode * Plan mode always presents a new plan when you give feedback * Clark has better context about targeted UI components and can make targeted edits more accurately ## Reliability * Edit mode loads reliably even after bad code generations, allowing Clark to fix issues * Fixed chat crashes when clicking Clark's interactive buttons (Build it, multiple choice) too quickly * Fixed chat getting stuck centered on screen after generation * Deployed app links now work correctly when opened in new tabs * Syntax error indicator in top bar now clears after Clark fixes the issue ## Versions & checkpoints * Restore to any checkpoint from the **Versions** panel * Restore to past checkpoint if you pause a generation midway * Reset now works from the history panel even when unpinned ## Other improvements * Clone existing apps from the homepage * Homepage search clears when entering folders * Step navigation preserves previous run outputs * Run Superblocks APIs locally without disabling browser local network access checks * Changed "Think..." to "Starting development server" for clearer status during startup