# Create Display Source: https://formbricks.com/docs/api-reference/client-api--display/create-display /api-reference/openapi.json post /api/v1/client/{workspaceId}/displays Create a new display for a valid survey ID. If a userId is passed, the display is linked to the user. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Get Workspace State Source: https://formbricks.com/docs/api-reference/client-api--environment/get-workspace-state /api-reference/openapi.json get /api/v1/client/{workspaceId}/environment Retrieves the workspace state to be used in Formbricks SDKs. Note - Environments are deprecated. Use Workspace/workspaceId terminology. **Cache Behavior**: This endpoint uses server-side caching with a **5-minute TTL (Time To Live)**. Any changes to surveys, action classes, workspace settings, or other workspace data will take up to 5 minutes to reflect in the API response. This caching is implemented to improve performance for high-frequency SDK requests. # Create Response Source: https://formbricks.com/docs/api-reference/client-api--response/create-response /api-reference/openapi.json post /api/v1/client/{workspaceId}/responses Create a response for a survey and it's fields with the user's responses. The userId & meta here is optional. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Update Response Source: https://formbricks.com/docs/api-reference/client-api--response/update-response /api-reference/openapi.json put /api/v1/client/{workspaceId}/responses/{responseId} Update an existing response for example when you want to mark a response as finished or you want to change an existing response's value. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Create or Identify User Source: https://formbricks.com/docs/api-reference/client-api--user/create-or-identify-user /api-reference/openapi.json post /api/v1/client/{workspaceId}/user Endpoint for creating or identifying a user within the specified workspace. If the user already exists, this will identify them and potentially update user attributes. If they don't exist, it will create a new user. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Generate API Key Source: https://formbricks.com/docs/api-reference/generate-key Here is how you can generate an API key which gives you full access to the Formbricks Management API. Keep it safe! ## Generate API Key **1. Navigate to API Keys** Click on **API Keys** in the breadcrumbs at the top left corner of the page. Your organization name is a dropdown menu. **2. Add a new API key** Click on the "Add API Key" button to open the creation modal. **3. Configure your API key** 1. Give your API key a descriptive label (e.g., "GitHub Integration", "PostHog", "Slack") 2. Configure **Workspace Access** — this controls access to data inside a Workspace (surveys, responses, contacts, webhooks, and so on): * Add each Workspace this key should reach by clicking "Add Permission" * Choose the permission level for each (read, write, or manage) * There is no "all Workspaces" option — a key can only reach the Workspaces you add here 3. Configure **Organization Access** — this controls organization administration (members and teams) and does **not** grant access to Workspace data: * Set read and/or write access as needed **4. Copy your key** After creating the key, you'll see the API key value displayed once. Copy it immediately and store it in a secure location. For security reasons, you won't be able to view the complete API key again. > [!NOTE] > > Store your API key safely! Anyone who has your API key has access based on the permissions you've granted. For security reasons, the complete API key value cannot be viewed again after creation. ## API Key Access Scopes An API key has two independent access scopes. They control different families of endpoints and do not overlap: | Scope | What it grants | Example endpoints | | - | - | - | | **Workspace Access** (per Workspace: read / write / manage) | Access to data and configuration inside the selected Workspaces | `/api/v2/management/surveys`, `/responses`, `/contacts`, `/webhooks` | | **Organization Access** (read / write) | Organization administration only | `/api/v2/organizations/{organizationId}/users`, `/teams`, `/api/v2/me` | > [!NOTE] > > **Organization Access is not a shortcut for "all Workspaces".** It only grants access to organization-administration endpoints (members and teams). To read or write survey and response data, add each Workspace explicitly under Workspace Access. A key with only Organization Access and no Workspaces cannot access any Workspace data. > [!NOTE] > > Access scopes are fixed when the key is created. Afterwards you can only rename the key's label — to change its Workspaces or permissions, delete the key and create a new one. > [!NOTE] > > On Formbricks Cloud, organization user-management endpoints (creating and updating members) are not available. Organization Access is primarily intended for self-hosted instances. ## Delete API Key If you need to revoke access for an API key: 1. Go to **Settings → Organization → API Keys** page 2. Find the key you wish to revoke and click the trash icon 3. Confirm the deletion in the dialog that appears Your API key will stop working immediately after deletion. ## API Key Permission Levels API Keys have three permission levels that can be assigned per Workspace: * **Read**: Can only perform read operations (GET requests) * **Write**: Can perform read and write operations (GET, POST, PUT, PATCH requests) * **Manage**: Has full access including delete operations (all request types) These permission levels apply to **Workspace Access**. **Organization Access** is separate: it uses read/write access for organization administration only. See [API Key Access Scopes](#api-key-access-scopes) for how the two scopes differ. # Health Check Source: https://formbricks.com/docs/api-reference/health/health-check /api-reference/openapi.json get /health Formbricks' Health Check endpoint to make sure the App & the Database are connected with each other & up! # Create Action Class Source: https://formbricks.com/docs/api-reference/management-api--action-class/create-action-class /api-reference/openapi.json post /api/v1/management/action-classes Create Action Class from the UI or from the API! You can read more about them [here](https://formbricks.com/docs/in-app-surveys/actions). # Delete Action Class Source: https://formbricks.com/docs/api-reference/management-api--action-class/delete-action-class /api-reference/openapi.json delete /api/v1/management/action-classes/{actionClassId} Deletes an existing action class # Get Action Class by ID Source: https://formbricks.com/docs/api-reference/management-api--action-class/get-action-class-by-id /api-reference/openapi.json get /api/v1/management/action-classes/{actionClassId} Fetch an Action Class by it's ID # Get All Action Classes Source: https://formbricks.com/docs/api-reference/management-api--action-class/get-all-action-classes /api-reference/openapi.json get /api/v1/management/action-classes Fetches all the action classes available in the workspace # Get All Contact Attribute Keys Source: https://formbricks.com/docs/api-reference/management-api--contact-attribute-keys/get-all-contact-attribute-keys /api-reference/openapi.json get /api/v1/management/contact-attribute-keys Retrieve a list of all contact attribute keys defined in the current workspace # Get Contact Attribute Key by ID Source: https://formbricks.com/docs/api-reference/management-api--contact-attribute-keys/get-contact-attribute-key-by-id /api-reference/openapi.json get /api/v1/management/contact-attribute-keys/{contactAttributeKeyId} Retrieve a specific contact attribute key by its ID. This returns detailed information about how a particular attribute is defined in your workspace. # Get All Contact Attributes Source: https://formbricks.com/docs/api-reference/management-api--contact-attributes/get-all-contact-attributes /api-reference/openapi.json get /api/v1/management/contact-attributes Retrieve a list of all contact attributes in the current workspace # Get All Contacts Source: https://formbricks.com/docs/api-reference/management-api--contacts/get-all-contacts /api-reference/openapi.json get /api/v1/management/contacts Retrieve a list of all contacts for the current workspace # Get Contact by ID Source: https://formbricks.com/docs/api-reference/management-api--contacts/get-contact-by-id /api-reference/openapi.json get /api/v1/management/contacts/{contactId} Retrieve a specific contact by its ID # Me Source: https://formbricks.com/docs/api-reference/management-api--me/me /api-reference/openapi.json get /api/v1/management/me Fetches the product associated with the passed API key # Create Response Source: https://formbricks.com/docs/api-reference/management-api--response/create-response /api-reference/openapi.json post /api/v1/management/responses Create a user response using the management API. This will trigger the response pipeline, including webhooks, integrations, follow-up emails, and other configured actions. # Delete Response Source: https://formbricks.com/docs/api-reference/management-api--response/delete-response /api-reference/openapi.json delete /api/v1/management/responses/{responseId} Delete a response with its ID # Get Response by ID Source: https://formbricks.com/docs/api-reference/management-api--response/get-response-by-id /api-reference/openapi.json get /api/v1/management/responses/{responseId} Fetch the entire response object based on its ID # Get Survey Responses Source: https://formbricks.com/docs/api-reference/management-api--response/get-survey-responses /api-reference/openapi.json get /api/v1/management/responses Pass the surveyId as a Query Parameter & only fetch responses for a specific survey that you have access to. # Update Response Source: https://formbricks.com/docs/api-reference/management-api--response/update-response /api-reference/openapi.json put /api/v1/management/responses/{responseId} Update an existing user response with new data. This will trigger the response pipeline, including webhooks, integrations, follow-up emails (if the response is marked as finished), and other configured actions. # Upload Public File Source: https://formbricks.com/docs/api-reference/management-api--storage/upload-public-file /api-reference/openapi.json post /api/v1/management/storage API endpoint for uploading public files. Uploaded files are public and accessible by anyone. This endpoint requires authentication and enforces a hard limit of 5 MB for all uploads. It accepts a JSON body with fileName, fileType, workspaceId, and optionally allowedFileExtensions to restrict file types. On success, it returns a signed URL for uploading the file to S3. # Create Survey Source: https://formbricks.com/docs/api-reference/management-api--survey/create-survey /api-reference/openapi.json post /api/v1/management/surveys Create a survey with granular settings, questions, their types, welcomeCard, thankYouCard, languages, etc right from this API. We'd however recommend you to do this via our Formbricks App with the UI for a better visual experience. # Delete Survey Source: https://formbricks.com/docs/api-reference/management-api--survey/delete-survey /api-reference/openapi.json delete /api/v1/management/surveys/{surveyId} Delete a Survey by its ID. Please use this only when extrememly necessary. # Get All Surveys Source: https://formbricks.com/docs/api-reference/management-api--survey/get-all-surveys /api-reference/openapi.json get /api/v1/management/surveys Fetches all existing surveys. Each survey includes both `questions` (the legacy structure) and `blocks` (the newer structure). `questions` is always derived from `blocks` for backwards compatibility, so integrations may read either field. # Get SingleUse Links Source: https://formbricks.com/docs/api-reference/management-api--survey/get-singleuse-links /api-reference/openapi.json get /api/v1/management/surveys/{surveyId}/singleUseIds Generates multiple single use survey links for a survey based on its id. # Get Survey by ID Source: https://formbricks.com/docs/api-reference/management-api--survey/get-survey-by-id /api-reference/openapi.json get /api/v1/management/surveys/{surveyId} Fetch a survey object based on its ID. The response includes both `questions` (the legacy structure) and `blocks` (the newer structure). `questions` is always derived from `blocks` for backwards compatibility, so integrations may read either field. # Update Survey Source: https://formbricks.com/docs/api-reference/management-api--survey/update-survey /api-reference/openapi.json put /api/v1/management/surveys/{surveyId} Update an existing survey with new properties. This is also what we'd recommend you to do from the UI for a better visual feedback. # Create Webhook Source: https://formbricks.com/docs/api-reference/management-api--webhook/create-webhook /api-reference/openapi.json post /api/v1/webhooks Create a new webhook right from the API and see it active right away! # Delete Webhook Source: https://formbricks.com/docs/api-reference/management-api--webhook/delete-webhook /api-reference/openapi.json delete /api/v1/webhooks/{webhookId} Delete an existing webhook by provifding it's ID. It will immediately apply and not trigger again. # Get All Webhooks Source: https://formbricks.com/docs/api-reference/management-api--webhook/get-all-webhooks /api-reference/openapi.json get /api/v1/webhooks Retrieve a list of all webhooks for the current workspace # Get Webhook Source: https://formbricks.com/docs/api-reference/management-api--webhook/get-webhook /api-reference/openapi.json get /api/v1/webhooks/{webhookId} Get a specific webhook object based on its ID # REST API Source: https://formbricks.com/docs/api-reference/rest-api Formbricks provides two APIs: the Public Client API for frontend survey interactions and the Management API for backend management tasks. Formbricks offers two types of APIs: the **Public Client API** and the **Management API**. Each API serves a different purpose, has *different* authentication requirements, and provides access to different data and settings. ## Public Client API The **Public Client API** is used by our SDKs and doesn’t require authentication, making it ideal for client-side interactions without exposing sensitive data. We currently have the following Client API methods exposed and below is their documentation attached in Postman: * [Displays API](/docs/api-reference/client-api--display/create-display) - Mark a survey as displayed or link a display to a response for a person. * [Responses API](/docs/api-reference/client-api--response/create-response) - Create & Update a Response for a Survey. ## Management API The **Management API** gives full access to all data and settings available in your Formbricks account. It requires a personal API Key for authentication, which you can generate and manage in the Settings section of the Formbricks app. We currently have the following Management API methods exposed and below is their documentation attached in Postman: * [Action Class API](/docs/api-reference/management-api--action-class/get-all-action-classes) - Create, List, and Delete Action Classes * [Contact Attribute Keys API](/docs/api-reference/management-api--contact-attribute-keys/get-all-contact-attribute-keys) - List Contact Attribute Keys * [Contacts API](/docs/api-reference/management-api--contacts/get-all-contacts) - List Contacts * [Me API](/docs/api-reference/management-api--me/me) - Retrieve Account Information * [Response API](/docs/api-reference/management-api--response/get-survey-responses) - List, List by Survey, Update, and Delete Responses * [Survey API](/docs/api-reference/management-api--survey/get-all-surveys) - List, Create, Update, generate multiple suId, and Delete Surveys * [Webhook API](/docs/api-reference/management-api--webhook/get-all-webhooks) - List, Create, and Delete Webhooks *** **Need help?** Reach out in [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Test API Key Source: https://formbricks.com/docs/api-reference/test-key Here is how you can test your API key to make sure it is working. To test if your API key is working, you can use the following request: ### Mandatory Headers | Name | x-Api-Key | | - | - | | **Type** | string | | **Description** | Your Formbricks API key. | ### Request ```bash cURL theme={null} GET - /api/v1/me curl --location \ 'https://app.formbricks.com/api/v1/me' \ --header \ 'x-api-key: ' ``` ### Response ```bash 200 (Success) theme={null} { "id": "cll2m30r70004mx0huqkitgqv", "createdAt": "2023-08-08T18:04:59.922Z", "updatedAt": "2023-08-08T18:04:59.922Z", "type": "production", "workspace": { "id": "cll2m30r60003mx0hnemjfckr", "name": "My Workspace" }, "appSetupCompleted": false, "websiteSetupCompleted": false, } ``` ```bash 401 (Not Authenticated) theme={null} Not authenticated ``` # Create Display Source: https://formbricks.com/docs/api-v2-reference/client-api--display/create-display /api-v2-reference/openapi.yml post /client/{workspaceId}/displays Create a new display for a valid survey ID. If a userId is passed, the display is linked to the user. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Upload Private File Source: https://formbricks.com/docs/api-v2-reference/client-api--file-upload/upload-private-file /api-v2-reference/openapi.yml post /client/{workspaceId}/storage API endpoint for uploading private files. Uploaded files are kept private so that only users with access to the specified Workspace can retrieve them. The endpoint validates the survey ID, file name, and file type from the request body, and returns a signed URL for S3 uploads along with a local upload URL. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Create Response Source: https://formbricks.com/docs/api-v2-reference/client-api--response/create-response /api-v2-reference/openapi.yml post /client/{workspaceId}/responses Create a response for a survey and its fields with the user's responses. The userId & meta here is optional. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Update Response Source: https://formbricks.com/docs/api-v2-reference/client-api--response/update-response /api-v2-reference/openapi.yml put /client/{workspaceId}/responses/{responseId} Update an existing response for example when you want to mark a response as finished or you want to change an existing response's value. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Create or Identify User Source: https://formbricks.com/docs/api-v2-reference/client-api--user/create-or-identify-user /api-v2-reference/openapi.yml post /client/{workspaceId}/user Endpoint for creating or identifying a user within the specified Workspace. If the user already exists, this will identify them and potentially update user attributes. If they don't exist, it will create a new user. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Get Workspace State Source: https://formbricks.com/docs/api-v2-reference/client-api--workspace/get-workspace-state /api-v2-reference/openapi.yml get /client/{workspaceId}/environment Retrieves the Workspace state to be used in Formbricks SDKs. Note - Environments are deprecated. Use Workspace/workspaceId terminology. **Cache Behavior**: This endpoint uses server-side caching with a **5-minute TTL (Time To Live)**. Any changes to surveys, action classes, Workspace settings, or other Workspace data will take up to 5 minutes to reflect in the API response. This caching is implemented to improve performance for high-frequency SDK requests. # Health Check Source: https://formbricks.com/docs/api-v2-reference/health/health-check /api-v2-reference/openapi.yml get /health Check the health status of critical application dependencies including database and cache. # API v2 Reference (Beta) Source: https://formbricks.com/docs/api-v2-reference/introduction Formbricks offers two types of APIs: the **Public Client API** and the **Management API**. Each API serves a different purpose, has *different* authentication requirements, and provides access to different data and settings. ### API Key Setup Checkout the [API Key Setup](/docs/api-reference/rest-api) to access the Management APIs with an API Key. If you’ve forked the collection and are running it, update the `apiKey` and `workspaceId` in the collection variables with your values. The API still accepts `environmentId` as a deprecated alias for backward compatibility. We also provide post-run scripts to help auto-assign variables when running scripts. Need more help? Visit our [Website](https://formbricks.com/) or join our [Discord](https://formbricks.com/discord)! # Create a contact attribute key Source: https://formbricks.com/docs/api-v2-reference/management-api--contact-attribute-keys/create-a-contact-attribute-key /api-v2-reference/openapi.yml post /management/contact-attribute-keys Creates a contact attribute key in the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Delete a contact attribute key Source: https://formbricks.com/docs/api-v2-reference/management-api--contact-attribute-keys/delete-a-contact-attribute-key /api-v2-reference/openapi.yml delete /management/contact-attribute-keys/{id} Deletes a contact attribute key from the database. # Get a contact attribute key Source: https://formbricks.com/docs/api-v2-reference/management-api--contact-attribute-keys/get-a-contact-attribute-key /api-v2-reference/openapi.yml get /management/contact-attribute-keys/{id} Gets a contact attribute key from the database. # Get contact attribute keys Source: https://formbricks.com/docs/api-v2-reference/management-api--contact-attribute-keys/get-contact-attribute-keys /api-v2-reference/openapi.yml get /management/contact-attribute-keys Gets contact attribute keys from the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Update a contact attribute key Source: https://formbricks.com/docs/api-v2-reference/management-api--contact-attribute-keys/update-a-contact-attribute-key /api-v2-reference/openapi.yml put /management/contact-attribute-keys/{id} Updates a contact attribute key in the database. # Create a contact Source: https://formbricks.com/docs/api-v2-reference/management-api--contacts/create-a-contact /api-v2-reference/openapi.yml post /management/contacts Creates a single contact in the database. This endpoint expects a top-level `attributes` object. For bulk uploads, use `PUT /management/contacts/bulk`, which expects `contacts[].attributes[]` instead. Each contact must have a valid email address in the attributes. All attribute keys must already exist in the Workspace. The email is used as the unique identifier along with the Workspace. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Upload Bulk Contacts Source: https://formbricks.com/docs/api-v2-reference/management-api--contacts/upload-bulk-contacts /api-v2-reference/openapi.yml put /management/contacts/bulk Uploads contacts in bulk. This endpoint expects the bulk request shape: `contacts` must be an array, and each contact item must contain an `attributes` array of `{ attributeKey, value }` objects. Unlike `POST /management/contacts`, this endpoint does not accept a top-level `attributes` object. Each contact must include an `email` attribute in its `attributes` array, and that email must be valid. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Create a response Source: https://formbricks.com/docs/api-v2-reference/management-api--responses/create-a-response /api-v2-reference/openapi.yml post /management/responses Creates a response in the database. This will trigger the response pipeline, including webhooks, integrations, follow-up emails, and other configured actions. # Delete a response Source: https://formbricks.com/docs/api-v2-reference/management-api--responses/delete-a-response /api-v2-reference/openapi.yml delete /management/responses/{id} Deletes a response from the database. # Get a response Source: https://formbricks.com/docs/api-v2-reference/management-api--responses/get-a-response /api-v2-reference/openapi.yml get /management/responses/{id} Gets a response from the database. # Get responses Source: https://formbricks.com/docs/api-v2-reference/management-api--responses/get-responses /api-v2-reference/openapi.yml get /management/responses Gets responses from the database. # Update a response Source: https://formbricks.com/docs/api-v2-reference/management-api--responses/update-a-response /api-v2-reference/openapi.yml put /management/responses/{id} Updates a response in the database. This will trigger the response pipeline, including webhooks, integrations, follow-up emails (if the response is marked as finished), and other configured actions. # Get personalized survey link for a contact Source: https://formbricks.com/docs/api-v2-reference/management-api--surveys--contact-links/get-personalized-survey-link-for-a-contact /api-v2-reference/openapi.yml get /management/surveys/{surveyId}/contact-links/contacts/{contactId}/ Retrieves a personalized link for a specific survey. # Get survey links for contacts in a segment Source: https://formbricks.com/docs/api-v2-reference/management-api--surveys--contact-links/get-survey-links-for-contacts-in-a-segment /api-v2-reference/openapi.yml get /management/surveys/{surveyId}/contact-links/segments/{segmentId} Generates personalized survey links for contacts in a segment. # Create a webhook Source: https://formbricks.com/docs/api-v2-reference/management-api--webhooks/create-a-webhook /api-v2-reference/openapi.yml post /management/webhooks Creates a webhook in the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Delete a webhook Source: https://formbricks.com/docs/api-v2-reference/management-api--webhooks/delete-a-webhook /api-v2-reference/openapi.yml delete /management/webhooks/{id} Deletes a webhook from the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Get a webhook Source: https://formbricks.com/docs/api-v2-reference/management-api--webhooks/get-a-webhook /api-v2-reference/openapi.yml get /management/webhooks/{id} Gets a webhook from the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Get webhooks Source: https://formbricks.com/docs/api-v2-reference/management-api--webhooks/get-webhooks /api-v2-reference/openapi.yml get /management/webhooks Gets webhooks from the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Update a webhook Source: https://formbricks.com/docs/api-v2-reference/management-api--webhooks/update-a-webhook /api-v2-reference/openapi.yml put /management/webhooks/{id} Updates a webhook in the database. Note - Environments are deprecated. Use Workspace/workspaceId terminology. # Me Source: https://formbricks.com/docs/api-v2-reference/me/me /api-v2-reference/openapi.yml get /me Fetches the Workspaces and organizations associated with the API key. # Create a team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--teams/create-a-team /api-v2-reference/openapi.yml post /organizations/{organizationId}/teams Creates a team in the database. # Delete a team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--teams/delete-a-team /api-v2-reference/openapi.yml delete /organizations/{organizationId}/teams/{id} Deletes a team from the database. # Get a team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--teams/get-a-team /api-v2-reference/openapi.yml get /organizations/{organizationId}/teams/{id} Gets a team from the database. # Get teams Source: https://formbricks.com/docs/api-v2-reference/organizations-api--teams/get-teams /api-v2-reference/openapi.yml get /organizations/{organizationId}/teams Gets teams from the database. # Update a team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--teams/update-a-team /api-v2-reference/openapi.yml put /organizations/{organizationId}/teams/{id} Updates a team in the database. # Create a user Source: https://formbricks.com/docs/api-v2-reference/organizations-api--users/create-a-user /api-v2-reference/openapi.yml post /organizations/{organizationId}/users Create a new user in the database.
Only available for self-hosted Formbricks. # Get users Source: https://formbricks.com/docs/api-v2-reference/organizations-api--users/get-users /api-v2-reference/openapi.yml get /organizations/{organizationId}/users Gets users from the database.
Only available for self-hosted Formbricks. # Update a user Source: https://formbricks.com/docs/api-v2-reference/organizations-api--users/update-a-user /api-v2-reference/openapi.yml patch /organizations/{organizationId}/users Updates an existing user in the database.
Only available for self-hosted Formbricks. # Create a Workspace team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--workspace-teams/create-a-workspace-team /api-v2-reference/openapi.yml post /organizations/{organizationId}/workspace-teams Creates a Workspace team in the database. # Delete a Workspace team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--workspace-teams/delete-a-workspace-team /api-v2-reference/openapi.yml delete /organizations/{organizationId}/workspace-teams Deletes a Workspace team from the database. # Get Workspace teams Source: https://formbricks.com/docs/api-v2-reference/organizations-api--workspace-teams/get-workspace-teams /api-v2-reference/openapi.yml get /organizations/{organizationId}/workspace-teams Gets workspace teams from the database. # Update a Workspace team Source: https://formbricks.com/docs/api-v2-reference/organizations-api--workspace-teams/update-a-workspace-team /api-v2-reference/openapi.yml put /organizations/{organizationId}/workspace-teams Updates a Workspace team in the database. # Get roles Source: https://formbricks.com/docs/api-v2-reference/roles/get-roles /api-v2-reference/openapi.yml get /roles Gets roles from the database. # Overview Source: https://formbricks.com/docs/development/overview How Formbricks is built, and the standards its code is held to. This section is for people working on the Formbricks codebase itself. It documents **how the platform is put together** and **the conventions its code follows** — not how to use Formbricks, which is what the rest of these docs are for. ## What is here > [card] [Technical Handbook](/docs/development/technical-handbook/overview) > > The architecture: how the Next.js app, the API gateway, the MCP server and the database fit together, and how tenants are kept apart. > [card] [Standards](/docs/development/standards/organization/file-and-directory-organization) > > How the repository is organised, how code is formatted and named, how errors are handled, and what a review and a test are expected to cover. ## Running Formbricks locally Setup instructions live with the code, where they stay in step with it: * [README](https://github.com/formbricks/formbricks#readme) — prerequisites and the steps to get an instance running. * [CONTRIBUTING.md](https://github.com/formbricks/formbricks/blob/main/CONTRIBUTING.md) — how to raise an issue, and what a good pull request looks like. If something goes wrong, [GitHub Discussions](https://github.com/formbricks/formbricks/discussions) is the fastest way to get help from people who have hit the same thing. > [!NOTE] > > Looking to **run** Formbricks rather than develop it? See [Self-hosting](/docs/self-hosting/overview). > Building **against** it? See the [API v2 reference](/docs/api-v2-reference/introduction) and the > [SDK guides](/docs/surveys/website-app-surveys/framework-guides). # File and Directory Org. Source: https://formbricks.com/docs/development/standards/organization/file-and-directory-organization This document outlines the structure and organization of files and directories in the Formbricks codebase, providing guidelines for maintaining consistency and clarity across the repository. ## Repository Structure Overview The Formbricks codebase follows a monorepo structure using pnpm workspaces, with two main directories: * `apps/` - Contains full applications * `packages/` - Contains shared libraries and utilities ## Apps Directory The `apps/` directory contains complete applications: ### apps/web/ * Main Formbricks web application (Next.js) * Primary application with full feature set * Uses App Router architecture * Contains environment-specific settings and configurations ### apps/demo/ * Demo application (Next.js) * Showcases Formbricks in-product surveying functionality * Used for testing and demonstration purposes ### apps/demo-react-native/ * React Native demo app (React Native) * Demonstrates mobile integration capabilities * Example implementation for React Native ### apps/storybook/ * Component documentation * Visual documentation of UI components * Testing environment for isolated components ## Packages Directory The `packages/` directory contains shared libraries and utilities: ### packages/js-core/ * Contains core functionality for in-product surveys * Shared logic between different SDK implementations * Base classes and utilities ### packages/js/ * JavaScript SDK for browser-based applications * Used for running surveys on websites and web apps (browser) * Public NPM package ### packages/react-native/ * React Native SDK * Used to run surveys in mobile apps built with React Native / Expo * Includes native platform adaptations ### packages/lib/ * Shared business logic * Shared utilities and helpers ### packages/types/ * TypeScript type definitions * Zod schemas for validation ### packages/database/ * Database schemas and migrations * Prisma schema definitions * Migration management ### packages/surveys/ * Survey-specific functionality * Survey rendering logic and UI components * Survey state management ## Module Organization ### Core Module Structure Each feature module follows a consistent structure: ``` modules/ └── ee/ ├── insights/ │ ├── components/ │ ├── experience/ │ └── types/ └── contacts/ ├── segments/ └── components/ ``` ## Adding New Code ### New Features When adding new features, follow these guidelines: 1. **Determine Scope**: * Complete application → `apps/` * Shared library → `packages/` * Feature for existing app → appropriate module in `apps/web/modules/` 2. **Module Creation**: Create a new module with the standard structure: ``` modules/ └── your-feature/ ├── components/ # React components ├── lib/ # Business logic ├── types/ # TypeScript types ├── actions.ts # Server actions └── route.ts # API routes ``` 3. **Component Organization**: * Base UI components → `modules/ui/components/` * Feature-specific components → `modules/[feature]/components/` ## Best Practices ### Code Organization * Keep modules focused and single-purpose * Maintain clear separation between UI and business logic * Use proper TypeScript interfaces and types ### File Structure * Group related files in descriptive directories * Use consistent naming patterns * Keep files focused and modular ### Module Independence * Minimize dependencies between modules * Share common utilities through appropriate packages * Maintain clear module boundaries ### Documentation * Document complex logic and APIs as laid out in the [Documentation](/docs/development/standards/practices/documentation) section * Keep documentation current with code changes ## Testing Organization ### Test File Location * Test files should be located alongside the code they test * Use `.test.ts` or `.spec.ts` suffix for test files * Example: `user-service.test.ts` for `user-service.ts` ### Test Directory Structure ``` feature/ ├── tests/ # Test directory (if grouping tests) ├── components/ # Feature components └── lib/ # Business logic ``` ## Configuration Files ### Root Level Configuration * `.eslintrc.js` - ESLint configuration * `tsconfig.json` - TypeScript configuration * `package.json` - Package metadata and scripts * `.env` - Environment variables ### Package Level Configuration Each package maintains its own configuration files: * `package.json` - Package-specific dependencies and scripts * `tsconfig.json` - Package-specific TypeScript settings * `.eslintrc.js` - Package-specific linting rules ## Version Control ### Git Organization * `.gitignore` - Specifies ignored files and directories * `.github/` - GitHub specific configurations and workflows * `CHANGELOG.md` - Documents version changes * `LICENSE` - License information ## Conclusion Following these organizational patterns ensures: * Consistent code structure across the repository * Easy navigation and maintenance * Clear separation of concerns * Scalable architecture for future growth Remember to maintain these patterns when adding new code to keep the codebase organized and maintainable. # Modules & Components Source: https://formbricks.com/docs/development/standards/organization/module-component-structure In this document we outline the best practices for organizing modules and components across the codebase. Clear separation of concerns between modules (which encompass business logic and domain-specific functionality) and components (reusable UI elements and building blocks) promotes clarity, scalability, and maintainability. ## Introduction Our codebase follows a modular architecture with two primary organizational units: 1. **UI Components**: Reusable components in the `modules/ui/components` directory 2. **Feature Modules**: Domain-specific functionality organized by feature in the `modules` directory ## Module Organization ### Core Module Structure Modules are organized by feature and can be found in the `modules` directory. Each module typically includes: ``` modules/ └── feature-name/ ├── components/ # Feature-specific components ├── lib/ # Business logic and utilities ├── types/ # TypeScript types ├── actions.ts # Server actions └── route.ts # API routes (if needed) ``` ### Enterprise Edition (EE) Modules Enterprise features are organized in a dedicated `modules/ee` directory: ``` modules/ └── ee/ ├── insights/ │ ├── components/ │ ├── experience/ │ └── types/ └── contacts/ ├── segments/ └── components/ ``` ## Component Organization ### UI Component Structure UI components are centralized in `modules/ui/components` and follow a consistent structure: ``` modules/ui/components/ └── component-name/ ├── index.tsx # Main component implementation ├── stories.tsx # Storybook stories └── components/ # Sub-components (if needed) ``` ### Component Types 1. **Base Components**: Fundamental UI elements like Button, Input, Modal 2. **Composite Components**: More complex components that combine base components 3. **Feature-Specific Components**: Components tied to specific features ### Feature Module Example A feature module with its components and business logic: ``` modules/survey/ ├── components/ │ ├── question-form-input/ │ └── template-list/ ├── editor/ │ └── components/ ├── lib/ │ └── utils.ts └── types/ └── index.ts ``` ## Best Practices 1. **Component Organization** * Keep components focused and single-purpose * Use proper TypeScript interfaces for props * Implement Storybook stories for UI components 2. **Module Structure** * Organize by feature domain * Separate business logic from UI components * Use proper type definitions 3. **Code Sharing** * Share common utilities through the ui/lib directory * Maintain clear boundaries between modules * Use proper imports with aliases (@/modules/...) # Naming Conventions Source: https://formbricks.com/docs/development/standards/organization/naming-conventions This section outlines the guidelines for naming conventions across the codebase, ensuring consistency and clarity. ## Files and Directories ### General Files * Use lowercase and hyphen-separated names (kebab-case) for files and directories * ✅ `user-profile.ts` * ❌ `UserProfile.ts` * Group related files in directories with descriptive plural names * ✅ `components`, `services`, `utils` * ❌ `component`, `util` ### Special Files * Configuration files should follow framework conventions * ✅ `next.config.mjs`, `tailwind.config.js` * Test files should mirror source files with `.test` or `.spec` suffix * ✅ `user-service.test.ts` for `user-service.ts` * Database migration files should include timestamp and description * ✅ `20241017124431_add_documents_and_insights.sql` ## Code Symbols ### Variables and Functions * Use camelCase for variables and function names * ✅ `fetchUserData`, `isLoading`, `handleSubmit` * ❌ `FetchUserData`, `is_loading` * Boolean variables should use is/has/should prefix * ✅ `isVerifyEmailEnabled`, `hasPermission`, `shouldDisplay` * Async functions should use verb prefixes suggesting async * ✅ `fetchData`, `createUser`, `updateProfile` ### Classes and Types * Use PascalCase for: * Classes: `Config`, `Client`, `ResponseAPI` * Interfaces: `TSurveySummaryResponse`, `ApiConfig` * Type aliases: `TResponseData` * Prefix types with T and interfaces with I (when helpful) * ✅ `TStats`, `TResponseData`, `IApiConfig` * Enum names should be PascalCase, values in UPPER\_SNAKE\_CASE ```typescript theme={null} enum WorkspaceFeatureKeys { FREE = "free", STARTUP = "startup", SCALE = "scale", } ``` ### Constants * Use UPPER\_SNAKE\_CASE for constant values * ✅ `API_TIMEOUT`, `MAX_RETRIES`, `CONTAINER_ID` * Use PascalCase for constant references/objects * ✅ `ErrorCodes`, `Config` ### Database Models * Use PascalCase singular form for model names * ✅ `Survey`, `Response`, `Document` * Use camelCase for field names * ✅ `createdAt`, `workspaceId`, `isSpam` * Use snake\_case for database column names * ✅ `created_at`, `updated_at` ### Components * Use PascalCase for React components and their files * ✅ `SurveyCard.tsx`, `UserProfile.tsx` * Component-specific types should be prefixed with component name * ✅ `SurveyCardProps`, `UserProfileData` ### API and Endpoints * Use kebab-case for API endpoints * ✅ `/api/user-profile`, `/api/survey-responses` * Use camelCase for query parameters * ✅ `/api/surveys?pageSize=10&sortOrder=desc` ## Schema and Validation * Prefix Zod schemas with Z * ✅ `ZSurvey`, `ZDocument`, `ZInsight` * Use descriptive names for validation schemas * ✅ `ZUpdateDocumentAction`, `ZGenerateDocumentObjectSchema` ## Error Handling * Suffix error classes with "Error" * ✅ `ValidationError`, `DatabaseError`, `AuthenticationError` * Use descriptive names for error types * ✅ `SURVEY_NOT_FOUND`, `INVALID_RESPONSE` ## Best Practices * Keep names descriptive but concise * Be consistent within each context * Follow existing patterns in the codebase * Use full words instead of abbreviations unless widely accepted * ✅ `configuration` vs ❌ `config` (except in standard terms) * ✅ `id`, `url` (standard abbreviations are acceptable) By following these conventions, we maintain consistency and clarity across the codebase, making it more maintainable and easier to understand for all team members. # Code Formatting Source: https://formbricks.com/docs/development/standards/practices/code-formatting Standards for consistent code formatting across the Formbricks codebase ## Core Configuration ### Prettier Config Formbricks uses a standardized Prettier configuration defined in `@formbricks/config-prettier`: ```javascript theme={null} module.exports = { bracketSpacing: true, bracketSameLine: true, singleQuote: false, jsxSingleQuote: false, trailingComma: "es5", semi: true, printWidth: 110, arrowParens: "always", importOrder: [ // Mocks must be at the top as they contain vi.mock calls "(.*)/__mocks__/(.*)", "server-only", "", "^@formbricks/(.*)$", "^~/(.*)$", "^@/(.*)$", "^[./]", ], importOrderSeparation: false, importOrderSortSpecifiers: true, }; ``` Key configurations: * 110 characters line width * Double quotes for strings * ES5 trailing commas * Always use parentheses for arrow functions * Strict import ordering ### Import Order All imports follow a strict ordering: 1. Mocks (for testing) 2. Server-only imports 3. Third-party modules 4. Internal `@formbricks/*` modules 5. Local aliases (\`\~/\*) 6. Relative imports ### TypeScript Config * Strict TypeScript checking enabled * Consistent use of `tsconfig.json` extending from `@formbricks/config-typescript` * Example configuration: ```json theme={null} { "compilerOptions": { "allowImportingTsExtensions": true, "isolatedModules": true, "noEmit": true, "resolveJsonModule": true, "strict": true }, "extends": "@formbricks/config-typescript/js-library.json", "include": ["src", "package.json"] } ``` ### JSDoc Comments Required for public APIs and complex functions: ```typescript theme={null} /** * Creates a new user * @param {string} name - User's name * @returns {Promise} The created user object */ function createUser(name: string): Promise { // implementation } ``` ### Error Handling Standardized error handling using the ErrorHandler class: ```typescript theme={null} export class ErrorHandler { private static instance: ErrorHandler | null; private handleError: (error: unknown) => void; public customized = false; public static initialized = false; private constructor(errorHandler?: (error: unknown) => void) { if (errorHandler) { this.handleError = errorHandler; this.customized = true; } else { this.handleError = (error) => { Logger.getInstance().error(JSON.stringify(error)); }; } } // ... additional methods } ``` ## Enforcement Tools ### Pre-commit Hooks Using Husky and lint-staged for automated checks: ```json theme={null} { "lint-staged": { "(apps|packages)/**/*.{js,ts,jsx,tsx}": [ "prettier --write" ], "*.json": [ "prettier --write" ], "packages/database/schema.prisma": [ "prisma format" ] } } ``` The hook formats staged files only — ESLint is not part of it. Lint violations are caught by `pnpm lint` and the "Run Linters" CI job. ### ESLint Configuration ESLint runs on the flat config format. Every package and app has its own `eslint.config.mjs` that imports one of the composable tiers exported by `@formbricks/config-eslint`: | Import | Use for | | - | - | | `@formbricks/config-eslint/library` | Node/TypeScript packages | | `@formbricks/config-eslint/react` | React packages (react, react-hooks, jsx-a11y) | | `@formbricks/config-eslint/react-hooks` | React packages that only need the hooks rules | | `@formbricks/config-eslint/next` | Next.js applications | Every tier builds on `@formbricks/config-eslint/base`, which holds the shared turbo, prettier, vitest and unused-vars conventions. It exports named building blocks rather than a ready-made config, so packages import one of the tiers above instead of `base` directly. The `library` and `react` tiers are factories — call them with the package's `tsconfigRootDir` so the type-aware rules resolve against that package's own tsconfig. The `react-hooks` and `next` tiers are plain arrays a config re-exports or spreads with its own overrides: ```javascript theme={null} // packages//eslint.config.mjs import library from "@formbricks/config-eslint/library"; export default library({ tsconfigRootDir: import.meta.dirname }); ``` ```javascript theme={null} // apps/web/eslint.config.mjs import next from "@formbricks/config-eslint/next"; export default [ { ignores: [".next/**", "public/**"] }, ...next, { rules: { "react-hooks/exhaustive-deps": "warn" } }, ]; ``` Use the extensionless subpaths above — they are the only ones the package exports. ### Continuous Integration * Automated formatting checks in CI/CD pipeline * SonarCloud integration for code quality analysis * Coverage requirements for tests ## VS Code Integration ### Required Extensions * `esbenp.prettier-vscode` - Prettier formatting * `dbaeumer.vscode-eslint` - ESLint integration * `bradlc.vscode-tailwindcss` - Tailwind CSS support ### Recommended Settings ```json theme={null} { "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "typescript.tsdk": "node_modules/typescript/lib" } ``` ## Best Practices 1. **Consistent Formatting** * Always run `pnpm format` before committing * Use VS Code's format on save feature * Follow the established import order 2. **Type Safety** * Enable strict TypeScript checks * Use explicit type annotations when necessary * Avoid using `any` type 3. **Code Organization** * Keep files focused and modular * Group related functionality * Use clear, descriptive names 4. **Documentation** * Document complex logic * Use JSDoc for public APIs * Keep comments current with code changes These standards ensure consistency across the Formbricks codebase while maintaining high code quality and developer productivity. # Documentation Source: https://formbricks.com/docs/development/standards/practices/documentation Standards for documenting code and features in the Formbricks codebase ## Overview At Formbricks, we maintain strict documentation standards to ensure code clarity, maintainability, and ease of use for both internal developers and external contributors. ### Contribute to Documentation We use Mintlify to maintain our documentation. You can find more information about how to contribute to the documentation in the [README](https://github.com/formbricks/formbricks/blob/main/docs/README.md) file. ## Code Documentation ### Function Documentation 1. **Complex Logic Documentation** * All functions with complex logic must include JSDoc comments * Document parameters, return types, and potential side effects * Example: ```typescript theme={null} /** Creates a new user and initializes their preferences @param {string} name - User's full name @param {UserOptions} options - Configuration options for user creation @returns {Promise} The created user object @throws {ValidationError} If name is invalid */ async function createUser(name: string, options: UserOptions): Promise { // implementation } ``` 2. **TypeScript Ignore Comments** * When using `@ts-ignore` or `@ts-expect-error`, always include a comment explaining why * Example: ```typescript theme={null} // @ts-expect-error -- Required for dynamic function calls void window.formbricks.setup(...args); ``` ### API Documentation 1. **API Endpoints** * All new API endpoints must be documented in the OpenAPI specification * Include request/response schemas, authentication requirements, and examples * Document both Client API and Management API endpoints * Place API documentation in the `docs/api-reference` directory 2. **Authentication** * Clearly specify authentication requirements * Document API key usage and permissions * Include error scenarios and handling ### Feature Documentation * All new features must include a feature documentation file * Document the feature's purpose, usage, and implementation details * Include code examples and best practices ## Working with Mintlify We use Mintlify to write our documentation. ### File Structure 1. **MDX Files** * All documentation files must use the `.mdx` extension * Include frontmatter with required metadata: ```markdown theme={null} --- title: "Document Title" description: "Brief description of the content" icon: "appropriate-icon" --- ``` 2. **Navigation** * Add new pages to the appropriate section in `docs/docs.json` * Follow the existing navigation structure * Include proper redirects if URLs change ### Content Guidelines 1. **Writing Style** * Use clear, concise language * Break content into logical sections with proper headings * Include practical examples and code snippets * Use Mintlify components for notes, warnings, and callouts: ```markdown theme={null} Important information goes here ``` 2. **Media and Assets** * Store images in the appropriate `/images` subdirectory * Use descriptive alt text for all images * Optimize images for web delivery * Use relative paths for internal links 3. **Code Examples** * Specify the language for all code blocks * Include comments for complex code snippets * Use proper indentation and formatting ## Validation 1. **Local Testing** * Test documentation locally using Mintlify CLI: ```bash theme={null} mint dev ``` 2. **Review Process** * Documentation changes require peer review * Verify all links and references work * Ensure proper formatting and rendering These documentation requirements ensure that our codebase remains maintainable, accessible, and well-documented for both current and future developers. # Error Handling Source: https://formbricks.com/docs/development/standards/practices/error-handling Standards for handling errors across the Formbricks codebase ## Overview At Formbricks, we follow consistent error handling patterns to ensure reliability, debuggability, and maintainability across our codebase. This document outlines our standard approaches to error handling. ## Core Principles 1. **Type Safety**: Use typed errors and results 2. **Meaningful Messages**: Provide clear, actionable error messages 3. **Proper Propagation**: Handle or propagate errors appropriately 4. **Logging**: Ensure errors are properly logged for debugging 5. **Recovery**: Implement graceful fallbacks where possible ## Standard Error Types We maintain a set of standardized error types for different scenarios: ```typescript theme={null} export interface ApiErrorResponse { code: | "not_found" | "gone" | "bad_request" | "internal_server_error" | "unauthorized" | "method_not_allowed" | "not_authenticated" | "forbidden" | "network_error"; message: string; status: number; url: URL; details?: Record; responseMessage?: string; } ``` ## Error Handling Patterns ### API Error Handling For API endpoints: ```typescript theme={null} export const GET = async (request: Request) => { try { const authentication = await authenticateRequest(request); if (!authentication) return responses.notAuthenticatedResponse(); const data = await fetchData(authentication.workspaceId!); return responses.successResponse(data); } catch (error) { if (error instanceof DatabaseError) { return responses.badRequestResponse(error.message); } throw error; } }; ``` ### Client-Side Error Handling For client-side operations: ```typescript theme={null} const handleOperation = async () => { const result = await performAction(); if (!result.ok) { logger.error(`Operation failed: ${result.error.message}`); toast.error("Operation failed. Please try again."); return; } // Process successful result processResult(result.data); }; ``` ## Best Practices 1. **Never Swallow Errors** * Always handle or propagate errors * Log errors appropriately for debugging * Use error boundaries in React components 2. **Type Safety** * Use typed error responses * Leverage TypeScript for compile-time error checking * Define clear error interfaces 3. **Error Messages** * Include relevant context in error messages * Make messages actionable for developers * Use consistent error formatting 4. **Error Recovery** * Implement fallback behaviors where appropriate * Gracefully degrade functionality when possible * Provide user feedback for recoverable errors 5. **Documentation** * Document expected errors in function JSDoc * Include error handling in code examples * Keep error handling documentation up to date ## Testing Error Scenarios Always include error case testing: ```typescript theme={null} describe("fetchEnvironmentState()", () => { test("returns err(...) on network error", async () => { const mockNetworkError = { code: "network_error", message: "Timeout", responseMessage: "Network fail", }; const result = await fetchEnvironmentState(); expect(result.ok).toBe(false); if (!result.ok) { expect(result.error.code).toBe(mockNetworkError.code); expect(result.error.message).toBe(mockNetworkError.message); } }); }); ``` These standards ensure consistent, reliable error handling across the Formbricks codebase while maintaining good developer experience and system reliability. # Code Reviews Source: https://formbricks.com/docs/development/standards/qa/code-reviews This document outlines our comprehensive code review process at Formbricks. We maintain high quality, consistency, and best practices within our codebase through this structured approach. ## Initial Checks via GitHub Workflows When a Pull Request (PR) is opened, our automated GitHub workflows perform several critical checks: > **Note:** At Formbricks, all feature changes must be submitted through Pull Requests - direct pushes to protected branches are not allowed. * **PR Title Validation**: Ensures clear, descriptive titles following our conventions * **Build Verification**: Confirms that the build process completes successfully * **Test Suite**: Runs all automated tests to catch potential regressions * **Translation Check**: Identifies any missing translation keys * **Linting**: Enforces our coding standards and style guidelines These checks must pass before proceeding to manual review. ## Reviewer Assignment Once all automated checks pass successfully: * The PR author picks the reviewer, usually a team member working in the same area or project * Reviewers are not assigned automatically, so request the review on GitHub to notify them * Priority is given based on PR urgency and complexity ## Functional Testing and UI Review The assigned reviewer performs thorough testing: ### Functionality Testing * Verifies that new features work as specified * Tests edge cases and error scenarios * Ensures proper error handling * Checks integration with existing features ### UI Review (if applicable) * Validates visual consistency * Checks responsive behavior * Ensures accessibility standards * Reviews user interaction flows ## Feedback Process If improvements are needed: * Reviewers add inline comments on GitHub * Feedback is specific and actionable * Code suggestions are provided when helpful * Comments follow our constructive feedback guidelines ## In-depth Code Review Our code review process utilizes both human expertise and AI assistance: ### Manual Review * Code structure and organization * Design patterns and best practices * Performance considerations * Security implications * Documentation completeness ### AI-Assisted Review We leverage advanced AI tools for additional insights: * **Code Rabbit**: Automated code analysis and suggestions * **Sonarqube**: Code quality metrics and potential issues ## Resolution and Merge Final steps before merging: * All review comments must be addressed * Required changes are implemented * At least one reviewer approval is required * All conversations must be resolved * CI/CD pipeline passes again * PR is merged into the target branch ## Best Practices * Keep PRs focused and reasonably sized * Respond to review comments promptly * Use the "Request Changes" feature when necessary * Mark conversations as resolved when addressed * Use approve/request changes workflow appropriately ## Conclusion Our code review process combines automated checks, manual review, and AI assistance to ensure high-quality code contributions. This multi-layered approach helps maintain code quality while promoting knowledge sharing within the team. Remember: Code reviews are not just about finding issues—they're opportunities for learning and improving our codebase together. # Screen Reader Pass Source: https://formbricks.com/docs/development/standards/qa/screen-reader-pass The manual screen-reader and keyboard walkthrough of a rendered survey, and how to record what it finds. Automated accessibility rules catch roughly a third of WCAG failures. Per Deque, axe-core detects about 30–40% of issues on a page; the rest — whether alt text says anything useful, whether a heading structure reflects the real hierarchy, whether a status change is announced at all, where focus actually lands after an interaction — needs a person with a screen reader. That gap is not theoretical here. The survey validation errors that were rendered but never announced (WCAG 4.1.3) passed the axe gate cleanly for months and were found by a manual pass. This page is the walkthrough that found it, written down so it can be repeated by someone who has not done it before. > [!NOTE] > > This is a procedure, not a CI gate. Run it when the survey renderer's structure, focus handling, > or status messaging changes, and before a release that carries such a change. A single UI detail > inside an already-covered flow does not need a full pass. *** ## What the automated gate already covers Do not spend the pass re-checking these. They run on every pull request, and if one regresses the Playwright job fails before a human ever looks: | Already asserted in CI | Where | | - | - | | Zero WCAG 2.1/2.2 AA axe violations on every card, in 10 variants | `survey-accessibility.spec.ts` | | One `h1` naming the survey, card headlines as `h2`, no skipped level | `survey-accessibility.spec.ts` | | Validation errors reach a resolvable live region; failed submit moves focus | `survey-keyboard.spec.ts` | | Progress is a determinate `progressbar` matching the painted width | `survey-progress-a11y.spec.ts` | | Arrow keys browse without selecting; Space selects and advances once | `survey-keyboard.spec.ts` | What is left for a human is everything above that involves judgement or hearing: whether the announcement that fires is the *right* one, whether the focus stop that exists is the *expected* one, and whether the text a screen reader reads out means anything. *** ## Before you start **1. Get a survey with every question type in it** The accessibility suite already seeds exactly this. Run any one of its tests against your local stack and the fixtures are left behind in your dev database — an "A11y Kitchen Sink" survey covering every renderable question type, and an "A11y Answered States" survey carrying the date picker, an external CTA, a required file upload and the Cal.com scheduler: ```bash theme={null} pnpm test:e2e survey-accessibility -g "heading structure" psql "$DATABASE_URL" -c "select name, id from \"Survey\" where name like 'A11y%' limit 3;" ``` They are published link surveys, so `http://localhost:3000/s/` opens one with no login. Use the kitchen sink for the walkthrough below and the answered-states survey for the composite controls step. **2. Pick one screen reader and browser pair** NVDA with Firefox or Chrome on Windows, or VoiceOver with Safari on macOS. Use one pair for the whole pass and write down which — a finding is only reproducible if the pair is known, and the same markup can behave differently in another one. **3. Turn the screen off, or turn the display curtain on** VoiceOver has one built in (`Ctrl+Option+Shift+F11`). The point is to stop yourself from resolving an ambiguity with your eyes, which is the failure mode of every sighted screen-reader pass. *** ## The pass Walk the survey from the link to the end screen. Each step below names what to do and what a pass looks like; anything else is a finding. **1. Read the page before touching it** Ask the screen reader for the page title and the heading list (NVDA: `Insert+F7`; VoiceOver: `Ctrl+Option+U`). **Pass:** the title identifies the survey and your position in it. The heading list has one level-1 heading — the survey's name — and the current card's prompt as a level 2. You can tell what you are being asked without reading the body. **2. Tab through every card** On each card, `Tab` from the top to the last stop, then `Shift+Tab` back. **Pass:** every stop is announced with a name that matches its visible text, and its focus indicator is visible. The order matches the visual order. Nothing off-screen takes focus — the stacked layout keeps neighbouring cards mounted, so a focus stop inside a card you cannot see is a finding. You never get stuck. **3. Submit a required card empty** Leave the first required question blank and activate the submit control. **Pass:** you hear the error without moving focus yourself, focus lands on the control that caused it, and you are still on the same card. The error text says which field and what to do. **4. Advance a card and listen** Answer the card and submit. **Pass:** something tells you the card changed — the new prompt, the progress, or both — without you having to go looking. Silence here is the highest-value finding this pass produces. **5. Go back** Activate the back control. **Pass:** you are told you moved back, your previous answer is still there and is announced as selected, and focus is somewhere useful rather than back at the top of the document. **6. Exercise the composite controls** The date picker, the file upload, the ranking list and the matrix are the four that do not reduce to a single native input. **Pass:** the date picker announces the selected day as selected and is operable from the keyboard alone. The file upload announces the upload starting, the file that was attached, and the control that removes it. Ranking announces an item's new position after it moves. Each matrix row announces which row it belongs to, not just the column. **7. Reach the end screen** Complete the survey. **Pass:** you hear that the survey is finished. Nothing is left focusable behind the end screen. **8. Re-read anything carrying meaning through colour or an image** Required markers, selected states, error states, images used as choices. **Pass:** each one is also carried by text or by an accessible name. Turn the screen back on and squint: if a state is only a colour, it is a finding regardless of its contrast ratio. *** ## Known third-party gaps These are already known and do not need re-filing. Both live inside a cross-origin iframe that Formbricks embeds but does not control: * **Cal.com scheduler.** Only the wrapper around it — the headline, description and container — is ours, and that is the part the axe gate scans. Barriers inside the booker itself belong upstream. * **Embedded video** (YouTube, Vimeo, Loom). Formbricks provides no route to captions, a transcript or an audio description, and it reduces the embedded player's controls. The gap and its workaround are published under [Known Limitations](/docs/platform/accessibility#known-limitations). *** ## Recording what you find One finding per barrier, in the accessibility findings log, then a ticket for each one worth fixing. A finding that someone else can act on carries five things: 1. The screen reader and browser pair, and the platform. 2. The survey link and the card, by its prompt text. 3. The keystrokes, in order, from opening the link. 4. What was announced — quoted, as heard — or "nothing". 5. What should have been announced instead, and the WCAG criterion it maps to. Barriers reported from outside the team arrive through the [accessibility issue template](https://github.com/formbricks/formbricks/issues/new?labels=accessibility\&template=accessibility.yml); use the same shape for what you find here. > [!NOTE] > > When a pass produces a finding that automation could have caught, fix the gate too: an assertion > in the relevant spec is cheaper than remembering to look next time. Where that assertion belongs > is decided the same way as any other test — see [Testing > Methodology](/docs/development/standards/qa/testing-methodology). # Testing Methodology Source: https://formbricks.com/docs/development/standards/qa/testing-methodology How we test Formbricks to ensure reliability, performance, and high-quality code. ## Overview At Formbricks, we maintain a rigorous testing strategy to ensure high-quality code and reliable functionality. Our testing approach is standardized and integrated into our development workflow. ## Testing Structure ### Unit Testing with Vitest We use Vitest as our primary testing framework. All unit tests follow these conventions: 1. **File Location and Naming** * Test files are co-located with the source files they test * Test files use the `.test.ts` extension (e.g., `utils.test.ts` tests `utils.ts`) 2. **Test Organization** ```typescript theme={null} import { describe, expect, test } from "vitest"; describe("ComponentName or FeatureName", () => { describe("functionName or scenario", () => { // We use the `test` function instead of `it` throught our test suite test("should describe expected behavior", () => { // test implementation }); }); }); ``` 3. **Coverage** * Coverage is measured, not targeted: confidence over coverage, and no test exists to move the number (see `AGENTS.md`, "Testing Guidelines") * The repo enforces exactly one Vitest threshold: `modules/auth/lib/**` at 80% (`apps/web/vite.config.mts`). Everything else is reported — `pnpm test:coverage` emits lcov and the SonarQube workflow uploads it, with the quality gate configured in SonarQube, not here * Coverage is tracked using the V8 provider * Coverage reports include: * Text summaries * HTML reports * LCOV reports ### End-to-End Testing with Playwright E2E tests are located in `apps/web/playwright/` and focus on critical user workflows. `AGENTS.md` is the source of truth for when one is warranted; the short version: 1. **Level.** Prove a behavior at the cheapest level that can fail on it. A feature's happy path or a journey across several surfaces is E2E. Business logic, invariants and anything pure is a unit test on the `.ts`. A route's authorization, response shape or query scoping is a unit or integration test on that route. 2. **Unit of coverage.** One spec per feature area, not per ticket and not per component. Every feature area ships a happy-path spec, and a new spec file is for an area that has none. Inside an area that already has one, the level still follows the behavior: journey behavior extends that spec, logic goes to a `.ts` unit test, UI detail goes to manual QA (see 3) — never a second spec file. 3. **Neither is an option.** A granular UI detail inside a covered feature — a label, a breadcrumb, an ARIA attribute, a keystroke inside one widget, a field's validation message — is verified manually and recorded in the PR. It does not get a spec. 4. **Cost.** Every spec is paid on every PR by everyone, forever. The Playwright job is the critical path of the PR gate and its wall clock can never drop below its slowest single test, so a new spec has to buy risk coverage that nothing cheaper can. ## Testing Setup ### Configuration The web app's Vitest configuration (`apps/web/vite.config.mts`) includes: ```typescript theme={null} test: { exclude: ["playwright/**", "node_modules/**", ".next/**", "**/*.integration.test.ts"], setupFiles: ["./vitestSetup.ts"], coverage: { provider: "v8", reporter: ["text", "html", "lcov"], reportsDirectory: "./coverage", }, } ``` ### Test Utilities Common test utilities are available in `vitestSetup.ts`: * Mock implementations for commonly used functions * Test lifecycle hooks (beforeEach, afterEach) * Validation test helpers ## Best Practices 1. **Test Independence** ```typescript theme={null} beforeEach(() => { vi.resetModules(); vi.resetAllMocks(); }); afterEach(() => { vi.clearAllMocks(); }); ``` 2. **Mocking** * Use Vitest's built-in mocking utilities * Mock external dependencies and services * Example: ```typescript theme={null} vi.mock("@formbricks/database", () => ({ prisma: { user: { create: vi.fn(), findUnique: vi.fn(), }, }, })); ``` 3. **Assertions** * Write clear, specific assertions * Test both success and error cases * Example: ```typescript theme={null} expect(result.ok).toBe(true); expect(result.data).toEqual(expectedData); expect(async () => await invalidCall()).rejects.toThrow(ValidationError); ``` ## Quality Assurance Process 1. **Continuous Integration** * Automated test suite execution on pull requests * Coverage reports generation * Test results reporting 2. **New Features** * Must include unit tests for the logic they add * A new user-facing feature area must include one happy-path E2E spec. Inside an area that already has one, the level follows the behavior: journey behavior extends that spec, logic goes to a unit test, UI detail is verified manually * Must not add tests whose only purpose is to move a coverage metric # Framework Usage Source: https://formbricks.com/docs/development/standards/technical/framework-usage Guidelines on how Formbricks utilizes Next.js, Tailwind CSS, and Prisma ORM for efficient development and performance. ## Introduction This document outlines the framework usage guidelines for Formbricks, which is built primarily on Next.js (with heavy use of Server-Side Rendering through the App Router), Tailwind CSS, and Prisma ORM. ## Next.js ### App Router and Server Components * Use the Next.js App Router with the /app directory for building the application. * Leverage React Server Components, which are the default in the App Router. * Perform server-side data fetching directly within page.tsx files using async function components. ### Data Fetching in page.tsx * Implement data fetching logic directly in your page.tsx components. This allows for server-side rendering without needing separate data fetching methods like getServerSideProps. * Utilize React Suspense and streaming features if using advanced asynchronous patterns. ### Server Actions for Mutations * Define Server Actions in dedicated action.ts files. * Server actions serve as entry points for mutations and delegate to service layers that perform Prisma operations and other business logic. * This approach promotes separation of concerns and maintainability by keeping form actions and mutations decoupled from UI components. ### Error Handling and Performance * Integrate error boundaries and loading states appropriately within your App Router structure. * Optimize performance with Next.js built-in features such as dynamic imports, the Image component, and code splitting. ## Tailwind CSS We follow the Tailwind framework as intended. Please have a look at the [Tailwind CSS Guidelines](https://tailwindcss.com/docs/styling-with-utility-classes) for more information. ## Prisma ORM We're working with Prisma as our ORM. Please have a look at the [Prisma ORM Documentation](https://www.prisma.io/docs/orm) for more information. # Language-Specific Source: https://formbricks.com/docs/development/standards/technical/language-specific-conventions This document outlines the language-specific conventions for the Formbricks codebase, providing guidelines for writing code in TypeScript/JavaScript. ## TypeScript Our codebase uses the `@vercel/style-guide` ESLint configurations for consistent code quality. ### ESLint Configuration We maintain three primary ESLint configurations for different package types: 1. **Library Configuration** (for packages): ```javascript theme={null} extends: [ "@vercel/style-guide/eslint/node", "@vercel/style-guide/eslint/typescript" ] ``` 2. **React Configuration** (for React applications): ```javascript theme={null} extends: [ "@vercel/style-guide/eslint/node", "@vercel/style-guide/eslint/typescript", "@vercel/style-guide/eslint/browser", "@vercel/style-guide/eslint/react", "@vercel/style-guide/eslint/next" ] ``` 3. **Next.js Configuration** (for Next.js applications): ```javascript theme={null} extends: [ "@vercel/style-guide/eslint/node", "@vercel/style-guide/eslint/typescript", "@vercel/style-guide/eslint/browser", "@vercel/style-guide/eslint/react", "@vercel/style-guide/eslint/next" ] ``` ### Key Conventions 1. **TypeScript Usage** * Strict TypeScript checking enabled * Explicit type annotations when necessary * Proper interface and type naming (prefix with T for types, I for interfaces when helpful) * No use of `any` type unless absolutely necessary 2. **Imports/Exports** * Follow strict import ordering: 1. Mocks (for testing) 2. Server-only imports 3. Third-party modules 4. Internal `@formbricks/*` modules 5. Local aliases (`~/*`) 6. Relative imports 3. **Error Handling** * Use typed error responses * Proper error propagation * Consistent error message formatting * Implement error boundaries in React components 4. **Async/Await** * Prefer async/await over raw promises * Proper error handling in async functions * Use Promise.all for parallel operations 5. **React Specific** * Functional components with TypeScript * Proper use of hooks * Consistent prop typing * Server Components by default in Next.js App Router ### Code Formatting We use Prettier with specific configurations: ```javascript theme={null} { bracketSpacing: true, bracketSameLine: true, singleQuote: false, jsxSingleQuote: false, trailingComma: "es5", semi: true, printWidth: 110, arrowParens: "always" } ``` ## Swift (iOS SDK) Our iOS SDK follows Swift best practices. ### Swift Configuration The iOS SDK requires the following: * **Swift Version**: 5.7+ * **Platform**: iOS 16.6+ * **Package Manager**: Swift Package Manager and CocoaPods support * **ARC**: Automatic Reference Counting enabled **Package.swift Configuration:** ```swift theme={null} // swift-tools-version:5.7 platforms: [ .iOS(.v16) ], ``` **CocoaPods Configuration:** ```ruby theme={null} s.platform = :ios, "16.6" s.swift_version = "5.7" s.requires_arc = true ``` ### Key Conventions 1. **Access Control Strategy** * `public`: SDK public API surface only * `internal`: Internal SDK communication and shared components * `private`: Implementation details within specific classes * Strategic use of `private(set)` for read-only public properties 2. **Architecture Patterns** * **Singleton Pattern**: Main SDK class (`Formbricks`) with static interface * **Manager Pattern**: Specialized managers (`UserManager`, `SurveyManager`, `PresentSurveyManager`) * **Builder Pattern**: Configuration objects (`FormbricksConfig.Builder`) * **Protocol-Oriented Programming**: Service protocols for dependency injection and testing 3. **Error Handling** * Custom error enums with descriptive cases (`FormbricksSDKErrorType`) * Error types conform to `LocalizedError` protocol * Structured error propagation with completion handlers * Defensive programming with guard statements and early returns 4. **Naming Conventions** * Classes: PascalCase (`FormbricksConfig`, `UserManager`) * Properties/Methods: camelCase (`workspaceId`, `setUserId`) * Constants: camelCase with descriptive names * Protocol names: Descriptive with "Protocol" suffix (`FormbricksServiceProtocol`) 5. **Code Organization** * `// MARK:` comments for logical section separation * Extensions for related functionality grouping * Consistent file structure with models, managers, networking, and views 6. **Model Design** * Prefer `struct` for data models and value types * Use `class` for reference types and managers * Implement `Codable` for JSON serialization/deserialization * Immutable properties where possible (`let` over `var`) 7. **Security & Validation** * HTTPS enforcement for all network requests * URL validation before network operations * Input validation with descriptive error messages * Secure data handling practices 8. **Asynchronous Operations** * `OperationQueue` for network operations * Completion handlers for async operations * Network connectivity checking with `NWPathMonitor` * Thread-safe operations with proper queue management ### Code Formatting We follow standard Swift formatting conventions: **Key Formatting Rules:** ```swift theme={null} // Class definitions @objc(Formbricks) public class Formbricks: NSObject { // Property declarations with access control static internal var isInitialized: Bool = false private let userManager: UserManager // Method signatures with clear parameter labels @objc public static func setup(with config: FormbricksConfig, force: Bool = false) // Guard statements for early returns guard !isInitialized else { let error = FormbricksSDKError(type: .sdkIsAlreadyInitialized) Formbricks.logger?.error(error.message) return } // Enum cases with descriptive names public enum FormbricksSDKErrorType: Int { case sdkIsNotInitialized case invalidAppUrl case networkError } ``` ## Kotlin (Android SDK) Our Android SDK codebase with Kotlin follows modern Android development practices and Kotlin conventions. ### Key Conventions 1. **Package Structure** * Logical grouping by functionality (api, model, network, manager, webview) * Clear separation of concerns across packages 2. **Kotlin Language Features** * **Object singletons** for stateless utilities and managers (`Formbricks`, `Logger`, `SDKError`) * **Data classes** for models with automatic equals/hashCode/toString (`Survey`, `User`) * **Sealed classes** for representing restricted hierarchies * **Extension functions** for utility methods (`Guard.kt`, `DateExtensions.kt`) * **Coroutines** for asynchronous operations with proper context switching 3. **Error Handling** * Centralized error definitions in `SDKError` object * Use of `Result` type for API responses * Proper exception propagation with meaningful error messages * Consistent error logging through centralized `Logger` 4. **Android-Specific Patterns** * `@Keep` annotations for ProGuard/R8 compatibility on public APIs * Proper lifecycle management in fragments and view models * Use of `FragmentManager` for UI components * Network security configuration for HTTPS enforcement 5. **Async/Await Pattern** * Prefer coroutines with `suspend` functions over callbacks * Use `withContext(Dispatchers.IO)` for network operations * Implement retry logic with `delay()` for robust API calls * Proper error handling in async functions 6. **API and Network Layer** * Retrofit for HTTP client with Gson converter * OkHttp interceptors for logging and security * Proper timeout configurations * Result-based API responses with retry mechanisms ### Code Formatting We use Android Studio's default Kotlin formatting ### Data Modeling 1. **Serialization** * Kotlinx Serialization for modern JSON handling * Gson annotations for backward compatibility: `@SerializedName` * Consistent nullable and non-nullable field declarations 2. **Data Classes** * Immutable data structures where possible * Proper use of nullable types (`String?`) * Clear property naming and documentation # API Gateway Source: https://formbricks.com/docs/development/technical-handbook/api-gateway Gateway auth architecture for proxied service APIs ### Gateway Model Formbricks gateway auth is split into three layers: * A shared gateway-auth core authenticates the caller, normalizes the original request, and dispatches to a service authorizer. * Provider adapters translate ingress-specific auth requests into the shared shape. Envoy uses `/api/envoy-auth/[...path]`; Traefik uses `/api/traefik-auth/[...path]`. * Service authorizers own service-specific authorization. FeedbackRecords is the first registered service authorizer. ### Tokens Session-authenticated browser callers should use `/api/v3/gateway/token` with `{ "service": "feedbackRecords" }`. The token identifies the user for the gateway only; every proxied request still runs through gateway authorization. `/api/v3/feedbackRecords/token` remains a compatibility alias. ### Provider Adapters Envoy and Traefik do not send auth subrequests in the same format, so they stay as thin adapters. Envoy derives the original path from the auth request path. Traefik derives it from `X-Forwarded-Method` and `X-Forwarded-Uri`. Both adapters reuse the same gateway-auth core and FeedbackRecords authorizer. ### Reference The public contract of the FeedbackRecords service — the eight operations the authorizer allows, and the two error shapes a caller sees — is documented in the [API v3 reference](/docs/api-v3-reference/introduction), which is unlisted and in private beta. # API v3 Schema Generation Source: https://formbricks.com/docs/development/technical-handbook/api-v3-schema-generation Why the v3 Zod schemas are generated from the OpenAPI spec, how the pipeline works, and how to adopt a resource ## Decision The v3 OpenAPI spec under `docs/api-v3-reference/src/` is the single source of truth for v3 request and response shapes. Zod schemas and their TypeScript types are **generated from it**, not written by hand and not the other way round (ENG-3335). This replaces the earlier plan to generate the spec from Zod with `zod-openapi`, as v2 does. Spec-first keeps the contract as the reviewed artifact that Schemathesis, Mintlify and the MCP server already read. It also keeps the prose, examples and error documentation where they live today, and makes contract drift a build failure instead of something a bespoke drift test may or may not cover. v2 keeps its code-first `zod-openapi` setup. Only v3 is in scope. ## Generator `@hey-api/openapi-ts` (MIT) with its `zod` plugin, exact-pinned in `packages/api-v3-schemas`. It was chosen after running every serious candidate against the real bundle: | Generator | Result on the v3 bundle | | - | - | | **hey-api 0.99** | Typechecks, deterministic, smallest install (+11 MB), no telemetry. Faithful once the pipeline below fixes strictness and composition. | | kubb 5 | Drops a base `required` on `.extend` (an element with no `type` validated), turns an open `metadata` object into `{}`, output fails `tsc`, telemetry on by default. | | orval 8 | No hook for custom formats (`cuid2`), strictness only all-or-nothing, `z.coerce.boolean` turns `"false"` into `true`. | | typed-openapi, `z.fromJSONSchema` | Crash on import / throw on `unevaluatedProperties` and `if/then`. | If hey-api's pre-1.0 churn ever outweighs its fidelity, orval is the fallback, with strictness and `cuid2` moved into the refinement layer. ## Pipeline `pnpm api:v3:schemas` runs `packages/api-v3-schemas/scripts/generate.ts`: **1. Read the committed bundle** `docs/api-v3-reference/openapi.yml` — the same file Schemathesis reads, so the schemas and the contract tests can never be generated from different inputs. **2. Scope to the adopted tags** `scripts/adopted.ts` lists each tag with its exact operationIds. Only those operations and the components they reach are generated, so an edit elsewhere in the contract cannot break the pipeline, and a renamed tag or operation fails it instead of silently generating less. **3. Normalize** `scripts/normalize.ts` rewrites the 3.1 idioms hey-api mis-generates: it flattens `allOf` + `unevaluatedProperties: false` into one closed object, collapses branches that only carry keywords the generator ignores, drops many-to-one discriminator mappings once the members' own enums prove them redundant, and strips `readOnly`. What may reach the generator is an **allowlist** of keywords; anything outside it, and any recursive schema, throws — a construct the generator silently drops is a validation hole. **4. Generate and format** hey-api runs in memory with two resolvers: `format: cuid2` becomes `z.cuid2()`, and `additionalProperties: false` becomes `z.strictObject`. Without the second, unknown keys would be stripped instead of answering 400 `unsupported_field` — a mass-assignment guard lost. The output is formatted with the repository's Prettier config into `src/generated/zod.gen.ts`. ## Guards * **Freshness.** `pnpm lint` runs `pnpm api:v3:check` (bundle vs `src/`) and `pnpm api:v3:schemas:check` (generated module vs bundle, byte for byte) on every PR. After editing the spec, `pnpm api:v3:sync` regenerates both. * **Fidelity.** `src/generated.contract.test.ts` diffs the JSON Schema of every generated component and operation schema against the spec, path by path: closedness, required, nullability, formats, bounds, enums, union members (each one, including duplicates), conditionals (fingerprinted) and closed `allOf` branches that others extend. Because JSON Schema shows a `z.unknown()` key as required while Zod accepts it missing, it also asks each required key at runtime. It does not model recursion — the normalizer refuses recursive schemas until it does. * **Pinned gaps.** hey-api cannot express `uniqueItems`, `minProperties`/`maxProperties`, `if/then`, or a required key with no type. Each such constraint is pinned in `src/testing/unenforced.ts` with the value the spec states and the module that enforces it. The fidelity test fails on any unpinned difference, on a pin whose value moved, and on a pin that no longer differs. ## Consuming The Schemas A route keeps its own small module (Responses: `apps/web/app/api/v3/responses/lib/schemas.ts` and `resources.ts`) that imports the generated schemas and adds only what they cannot carry: * refinements for the pinned constraints, with the messages clients read in `invalid_params[].reason`; * strict parameter objects (`z.strictObject(generated.shape)`), because OpenAPI cannot close a parameter list; * compositions the generator cannot emit, such as a many-to-one discriminated union rebuilt from the generated members (`z.discriminatedUnion("elementType", zResponseAnswer.options)`); * security declarations such as the ENG-2861 reference manifest. Query strings are the one exception. A query arrives as strings, sometimes repeated, and bracketed families such as `filter[finished][eq]` need coercion and repeated-key handling the generated typed schemas do not do. So `GET /api/v3/responses` and `/count` keep their hand-written parser (`parse-v3-responses-list-query.ts`), and the generated `zGetResponsesV3Query` / `zCountResponsesV3Query` are unused until a shared query adapter derives that parsing from them. Compose first, refine last: Zod 4 refuses to `.extend` over a key once a schema has refinements, and `.refine` returns a new instance — so anything keyed on schema identity must be attached to the final instance. ## Adopting A Resource 1. Add the tag and its operationIds to `packages/api-v3-schemas/scripts/adopted.ts`, then run `pnpm api:v3:sync`, which bundles `docs/api-v3-reference/src/` before generating, so spec edits made for the resource are included. If the normalizer throws, extend it deliberately, with a unit test. 2. Pin every new difference the fidelity test reports in `src/testing/unenforced.ts`, naming your module as the enforcer. 3. Rebuild the route schemas on the generated ones. Add a counterexample for each pin, a contract diff of each route schema, and parse the operation's examples through them (see `write-schemas.test.ts`). 4. **Before generating request bodies, the resource needs a reference-roster test** like Responses' `reference-manifest.test.ts`. Generation means a spec edit alone can add an accepted field, top-level or inside a nested object such as `meta`; the roster classifies both, by set equality, so it fails until that field's tenancy is classified and refuses fields the server derives. 5. Delete the resource's drift test once nothing in it is left that generation does not prove. ## Upgrading The Generator The version is exact-pinned and the output is committed, so an upgrade is a deliberate PR whose diff shows every change in the generated code. The fidelity and closedness tests are what catch a regression. The pipeline uses `ctx.gen.render()` with `dryRun`, which is not a documented API — check it on every bump. A TypeScript or Prettier catalog bump can also change the formatting and require a regenerate; `pnpm lint` reports it. The generator is a build-time dependency only. ESLint forbids importing it from `src/`, so no generator code can reach a served bundle, and a test fails if the generated module ever imports anything but `zod`. The `@formbricks/api-v3-schemas/testing` entry point reads the bundle from disk and is lint-banned outside tests in `apps/web`. The pipeline passes an explicit config file that does not exist, so hey-api's loader executes nothing it finds in the working directory — a test plants a throwing `openapi-ts.config.mjs` and `index.mjs` to keep it that way. The loader still reads a `.openapi-tsrc` from the working directory — hey-api offers no way to turn that off, and the file's keys survive wherever the pipeline sets none — so the renderer refuses to run when one is present. The generator's packages require Node 22.18 or newer, which the repository's Node 24 pin (`engines`, `.nvmrc`, CI and the Docker image) satisfies. Generator tooling must be under a permissive licence (MIT, Apache-2.0, BSD or ISC): the generated code is part of this AGPL repository, but the tool itself is never distributed. # Cube Tenant Isolation Source: https://formbricks.com/docs/development/technical-handbook/cube-tenant-isolation Threat model and controls for XM analytics tenant isolation in Cube ## Context XM analytics reads Hub feedback records through Cube. Hub stores all tenants in a shared `feedback_records` table and uses `tenant_id` to separate rows. Workspace access is the application authorization boundary. In the current Hub schema, `tenant_id` stores the authorized FeedbackDirectory ID, so every Cube query must be scoped to a directory that the authenticated workspace can access before data leaves Cube. ## Threat Model The main risk is cross-tenant read access through an unscoped Cube query. The attacker could be a regression in server code, an AI-generated query that includes malicious filters, a copied static token, or a direct request to Cube from inside the deployment network. The controls assume query bodies are attacker-influenced. Tenant identity is never trusted from the query JSON. ## Enforcement Flow **1. Authorize workspace access** Server actions and server components authorize workspace access in the Next.js app. **2. Validate the Cube query** The app validates the Cube query and rejects any `FeedbackRecords.tenantId` member supplied by users, saved charts, or AI output, including filters, dimensions, time dimensions, and order clauses. **3. Mint a short-lived JWT** The app mints a short-lived JWT per Cube request with `tenantId`, `feedbackDirectoryId`, `workspaceId`, `organizationId`, `userId`, `scope`, `iss`, `aud`, `jti`, and `exp` claims. **4. Verify the JWT in Cube** Cube verifies the JWT and exposes the claims through `securityContext`. **5. Enforce the tenant filter** Cube `queryRewrite` rejects missing tenant context, rejects caller-supplied tenant member usage, and appends `FeedbackRecords.tenantId = securityContext.tenantId` to every query. ## Audit Evidence The app records a sanitized `cubeQuery` audit event for each Cube query attempt, keyed by the JWT `jti`. Cube also emits a structured audit log line from `queryRewrite` with tenant, feedback directory, workspace, organization, user, request ID, source, and queried member names. Raw filter values are intentionally omitted from both logs. ## Operational Notes `CUBEJS_API_SECRET` is a signing secret, not an access token. Do not pass it to clients or reuse it as a bearer token. Set `CUBEJS_JWT_ISSUER` and `CUBEJS_JWT_AUDIENCE` consistently for the web app and Cube so Cube rejects tokens minted for any other audience or issuer. Set `CUBEJS_DEFAULT_API_SCOPES=meta,data` for Cube deployments so GraphQL, SQL, and orchestration APIs are not exposed unless explicitly needed. Network isolation for Cube remains recommended, but JWT-backed `queryRewrite` is the mandatory data boundary. # Custom CSS & Dark Mode Rollout Source: https://formbricks.com/docs/development/technical-handbook/custom-css-rollout Release order, cache purges and entitlements for shipping Custom CSS, dark mode and the SDK updates ## Context Custom CSS and dark mode touch the server, the survey renderer, the styling editors and five SDK packages. Mobile apps and self-hosted servers upgrade on their own schedule, so mixed versions are normal, not an edge case. This page is the release checklist; the customer-facing behavior lives in [Custom CSS](/docs/surveys/general-features/custom-css) and [SDK Compatibility](/docs/surveys/website-app-surveys/sdk-compatibility). ## What Ships Where | Component | Delivered by | Reaches users | | - | - | - | | Database columns `Workspace.customCss`, `Workspace.customCssPrevious`, `Survey.customCss` | Server migration (nullable, no backfill) | On deploy | | CSS processor, API v3 and MCP endpoints, delivery in the environment state | Server | On deploy | | Survey renderer (`/js/surveys.umd.cjs`): cascade layers, `customCss` prop, `setAppearance`, `data-fb-part` hooks | Server, cached by the CDN | On deploy **and** CDN purge | | js-core (`/js/formbricks.umd.cjs`): appearance state, passes both CSS scopes | Server, cached by the CDN | On deploy **and** CDN purge | | `@formbricks/js` wrapper: `appearance` option, `setAppearance` | npm release | When customers upgrade | | iOS, Android, React Native, Flutter SDKs: appearance, both CSS scopes | Package releases | When apps ship an update | | Editor cards (workspace Appearance, survey Styling) | Server | On deploy; on Cloud, saving needs the Scale plan | ## Deployment Order Data and renderer first, so nothing a creator saves reaches a renderer that does not understand it yet. 1. **Server and renderer.** Deploy the migration, processor, API, editor cards and renderer together. Existing surveys must look exactly the same: nothing is saved yet. 2. **Purge the CDN** for `/js/surveys.umd.cjs` and `/js/formbricks.umd.cjs`. Both URLs are unversioned and cached for up to 30 days at the edge, so without a purge some apps and websites keep the old renderer for weeks. Repeat the purge after any renderer rollback. 3. **Stripe entitlement on Cloud**, right after the purge (see below). Until it is attached, every Cloud organization sees the upgrade prompt in the editor cards, Scale included. 4. **SDK packages:** `@formbricks/js`, then the iOS, Android, React Native and Flutter SDKs, each from its own repository. Publication does not have to be atomic. Record every released version in [SDK Compatibility](/docs/surveys/website-app-surveys/sdk-compatibility), replacing "Pending release". Customers whose apps use the mobile SDKs need to ship an app update before their Custom CSS shows in the app; tell them early. 5. **Self-hosted** gets everything with the release that contains steps 1 and 2. There is no plan check, flag or environment variable. Add one release-note line: Custom CSS styles the card; Custom Head Scripts keep scripts, tags and page-level styles. ## Before Enabling On Cloud * **Stripe entitlement.** Attach the entitlement feature with lookup key `custom-css` to the Scale and Custom products. This is the only gate on Cloud: without it, saving Custom CSS fails with "plan required" for every organization, Scale included. Self-hosted instances skip the plan check. ## Turning It Off There is no feature flag, so stopping Custom CSS everywhere takes a deploy. | Problem | Action | Saved CSS | | - | - | - | | Custom CSS misbehaves in one survey | Turn off the survey's **Add custom styles**: its CSS stops applying, the workspace CSS stays | Kept | | Custom CSS misbehaves for one organization | With the customer, restore the previous workspace CSS or clear it in **Appearance** or through the API | Previous revision kept | | Renderer bug | Roll back the server deploy, then purge the CDN again | Kept | | Processor policy must change | Change the processor and bump `CUSTOM_CSS_PROCESSOR_VERSION` | Kept as source | | Delivery must stop everywhere | Deploy a change that withholds it in `resolveRespondentCustomCss` | Kept | Switching off is not instant: each SDK keeps its configuration until it refreshes (up to 30 minutes on the web, up to an hour in the mobile SDKs). A processor version bump marks every stored compiled output as stale. Delivery reprocesses stale CSS from its saved source; if the current processor rejects it, the CSS is withheld (never the old output) and creators see a warning in the editor. `BLOCK_EXTERNAL_CUSTOM_CSS_RESOURCES` in `apps/web/modules/custom-css/processor` is a code constant, deliberately without an environment variable or setting. It is part of the effective processor version, so changing it also requires the bump. ## Smoke Checks Run before each step above: 1. Existing surveys look exactly the same, in light mode, with no Custom CSS saved. 2. Old SDK with the new renderer: a survey opens and answers save, on web, iOS and Android. Mobile shows no Custom CSS. 3. New SDK with an old self-hosted server: surveys stay light, with no errors. 4. A survey with saved CSS and **Add custom styles** off: respondents get the workspace CSS only; turning it back on brings the survey's CSS back. 5. Self-hosted: existing Custom Head Scripts still run. 6. A CMS-style stylesheet (synthetic, never a customer's file) shows one removed-import warning, and its ported hooks style the preview and the live survey in light and dark. ## SDK Handoff | SDK | Repository | Package | Version | Status | | - | - | - | - | - | | JavaScript | `formbricks/js` | `@formbricks/js` | Pending release | Not published | | iOS | `formbricks/ios` | `FormbricksSDK` | Pending release | Not published | | Android | `formbricks/android` | `com.formbricks:android` | Pending release | Not published | | React Native | `formbricks/react-native` | `@formbricks/react-native` | Pending release | Not published | | Flutter | `formbricks/flutter` | `formbricks` | Pending release | Not published | Every mobile SDK must pass `customCss: { workspace, survey }` explicitly, from `workspaceSettings.customCss` and each `survey.customCss`, and feature-detect `formbricksSurveys.setAppearance`. The renderer applies Custom CSS only from that prop, so an SDK that does not pass it renders no Custom CSS at all rather than half of it. ## Styling Contract The `data-fb-part` hook names are declared once, in `FB_PART` (`packages/survey-ui/src/lib/parts.ts`), exported from `@formbricks/survey-ui` and, without any components, from `@formbricks/survey-ui/parts`. Customers' stylesheets depend on these names: renaming or removing one is a breaking change. `parts.test.ts` fails when the customer docs and the constant disagree. # Database Model Source: https://formbricks.com/docs/development/technical-handbook/database-model Overview of the Formbricks database schema and relationships Formbricks uses PostgreSQL as its primary database and [Prisma](https://www.prisma.io/) as the Object-Relational Mapping (ORM) tool. The database schema is designed to support multi-tenancy, survey management, and response collection while maintaining data isolation between organizations. ## Entity Relationship Diagram The following diagram shows the core entities and their relationships in the Formbricks database: ```mermaid theme={null} erDiagram Organization ||--o{ Workspace : "has many" Organization ||--o{ Membership : "has many" Organization ||--o{ Team : "has many" Organization ||--o{ Invite : "sends" Workspace ||--o{ Language : "supports" Workspace ||--o{ WorkspaceTeam : "has" Workspace ||--o{ Survey : "contains" Workspace ||--o{ Contact : "tracks" Workspace ||--o{ ActionClass : "defines" Workspace ||--o{ ApiKeyWorkspace : "has" Workspace ||--o{ Integration : "configures" Survey ||--o{ Response : "receives" Survey ||--o{ Display : "tracks" Survey ||--o{ SurveyTrigger : "configured by" Survey ||--o{ SurveyAttributeFilter : "filtered by" Survey ||--o{ SurveyLanguage : "translated to" Contact ||--o{ Response : "provides" Contact ||--o{ Display : "sees" Contact ||--o{ ContactAttribute : "has" User ||--o{ Membership : "belongs to" User ||--o{ Account : "has" User ||--o{ TeamUser : "member of" Team ||--o{ TeamUser : "includes" Team ||--o{ WorkspaceTeam : "has access to" ApiKey ||--o{ ApiKeyWorkspace : "scopes" Response ||--o{ TagsOnResponses : "tagged with" Tag ||--o{ TagsOnResponses : "applied to" ActionClass ||--o{ SurveyTrigger : "triggers" ContactAttributeKey ||--o{ ContactAttribute : "defines" ContactAttributeKey ||--o{ SurveyAttributeFilter : "used in" ``` ## Core Models ### Organization & Workspace Management 1. **Organization** * Top-level entity for multi-tenancy * Contains multiple Workspaces and team members * Manages billing and whitelabel settings 2. **Workspace** * Main grouping mechanism for surveys and related configuration * Belongs to a single organization * Controls branding and display settings 3. **WorkspaceTeam** * Maps teams to Workspaces * Controls Workspace-level access permissions * Enables scoped collaboration across teams ### Survey Management 1. **Survey** * Central model for questionnaires * Configurable with multiple questions and display rules * Supports multiple languages and targeting filters 2. **Response** * Records user answers to surveys * Links to contact information when available * Supports tagging for analysis 3. **ActionClass** * Defines triggering points for surveys * Can be code-based or no-code configurations * Links surveys to specific user actions ### User Management 1. **User** * Represents system users (admins/team members) * Manages authentication and preferences * Can belong to multiple organizations 2. **Contact** * Represents survey respondents * Stores attributes for targeting * Tracks survey displays and responses 3. **Team** * Groups users within organizations * Controls Workspace access permissions * Facilitates collaborative survey management ## Data Isolation The database schema ensures proper data isolation through: 1. **Organization-level isolation** * Each organization has its own Workspaces * Users can belong to multiple organizations * Resources are scoped to organizations 2. **Workspace-level isolation** * Independent surveys, contacts, action classes, and integrations * Isolated API key Workspace assignments * Workspace-specific configuration and styling defaults 3. **Team-based access isolation** * Teams are linked to Workspaces through `WorkspaceTeam` * Permissions are scoped per Workspace * Access can be delegated without exposing all organization resources ## Schema Management The database schema is managed through Prisma, which provides: * Type-safe database client * Automatic migration generation * Schema versioning * Data validation * Query optimization For detailed information about specific models and their properties, refer to the [schema.prisma](https://github.com/formbricks/formbricks/blob/main/packages/database/schema.prisma) file in the repository. ## PostgreSQL Database Tables Formbricks stores all data in PostgreSQL tables. Here's a comprehensive list of all database tables and their purposes: | Table Name | Description | | - | - | | Account | Stores third-party authentication accounts (OAuth) and their tokens | | ActionClass | Defines triggerable events that can launch surveys | | ApiKey | Stores API authentication keys for organization-level access | | ApiKeyWorkspace | Maps API keys to the Workspaces they can access | | Contact | Records information about user that can receive and respond to surveys | | ContactAttribute | Stores attribute values for contacts (e.g., role, company size) | | ContactAttributeKey | Defines available attribute types for contacts | | DataMigration | Tracks the status of database schema migrations | | Display | Records when and to whom surveys were shown | | Workspace | Main container for surveys, contacts, actions, integrations, and settings | | Integration | Stores configuration for third-party service integrations | | Invite | Manages pending invitations to join organizations | | Language | Defines supported languages for multi-lingual surveys | | Membership | Links users to organizations with specific roles | | Organization | Top-level container for Workspaces and team management | | Response | Stores survey responses and associated metadata | | Segment | Defines groups of contacts based on attributes | | Survey | Stores survey configurations, questions, and display rules | | SurveyAttributeFilter | Defines targeting rules for surveys based on contact attributes | | SurveyFollowUp | Configures automated actions based on survey responses | | SurveyLanguage | Links surveys to their supported languages | | SurveyTrigger | Connects surveys to their triggering actions | | Tag | Stores labels for categorizing responses | | TagsOnResponses | Junction table linking tags to responses | | Team | Groups users within organizations | | TeamUser | Links users to teams with specific roles | | WorkspaceTeam | Manages team access permissions to Workspaces | | User | Stores user account information and preferences | | Webhook | Manages webhook endpoints for event notifications | ## Schema Reference For detailed information about the database schema, including: * Complete field definitions * Relationships between tables * Enums and custom types * Field constraints and indices * JSON field structures Please refer to the [Prisma schema file](https://github.com/formbricks/formbricks/blob/main/packages/database/schema.prisma) in our GitHub repository. The schema.prisma file contains extensive documentation comments for each model, making it the authoritative reference for the database structure. # MCP Server Source: https://formbricks.com/docs/development/technical-handbook/mcp-server Configure and use the Formbricks v3 Surveys and Workflows MCP server ## Overview The Formbricks MCP server exposes v3 Surveys and Workflows tool surfaces for AI agents. It runs inside the Formbricks web app at `/api/mcp` and reuses the same v3 API authentication, authorization, rate limiting, response handling, and audit logging paths as the REST routes. > [!NOTE] > > OAuth 2.1 is the preferred authentication path for MCP clients. Formbricks API keys remain supported as a > backwards-compatible fallback for local development, self-hosters, and clients that do not support MCP OAuth > yet. > [!NOTE] > > Looking for step-by-step setup guides for Claude Code, the Claude apps, and Codex? See [Connect AI agents > (MCP)](/docs/platform/mcp/overview). This handbook covers the technical internals. ## Endpoint Use the streamable HTTP MCP endpoint on the Formbricks app: ```text theme={null} https://app.formbricks.com/api/mcp ``` For local development: ```text theme={null} http://localhost:3000/api/mcp ``` The route supports `POST` requests, runs with the Next.js Node.js runtime, and sets private no-store response headers. Browser-origin MCP requests must come from the configured Formbricks app origin. ### Protocol revisions The server implements protocol revision **2026-07-28** and keeps serving the 2025 era from the same endpoint, so a client on an older revision does not need to change anything. The MCP TypeScript SDK answers the legacy `initialize` handshake alongside `server/discover`, and `mcp-handler` serves with `legacy: "stateless"`. Three parts of the revision are handled by the SDK rather than by our code: the `server/discover` RPC, the `resultType` field now required on every result, and the `ttlMs` / `cacheScope` cache hints (which default conservatively to `ttlMs: 0` and `cacheScope: "private"`). Notable removals in the revision that used to be configured here: protocol-level sessions and the `Mcp-Session-Id` header, the `initialize` handshake as a precondition, and the HTTP+SSE transport. The handler therefore takes no `sessionIdGenerator`, `disableSse`, `basePath`, or `maxDuration` option — the route this handler is mounted on is the only mount point. OAuth clients discover the protected resource metadata here: ```text theme={null} https://app.formbricks.com/.well-known/oauth-protected-resource/api/mcp ``` The metadata advertises `/api/mcp` as the protected resource and points clients to the Better Auth issuer under `/api/auth`. ## Authentication ### OAuth 2.1 OAuth clients use Authorization Code + PKCE with Dynamic Client Registration. Registration is open (no initial access token — MCP clients self-register), so it accepts only redirect URIs an attacker can never receive an authorization code at: * `http` loopback — `localhost`, `127.0.0.1` or `[::1]` on any port — which local clients (Claude Code, Codex, MCP Inspector) use. * An exact hosted-connector callback: `https://claude.ai/api/mcp/auth_callback`, `https://claude.com/api/mcp/auth_callback` and `https://chatgpt.com/connector_platform_oauth_redirect` (`HOSTED_MCP_CLIENT_REDIRECT_URIS` in `apps/web/modules/auth/lib/mcp-dcr-redirect-policy.ts`), plus any a self-hoster adds with `MCP_DCR_ALLOWED_REDIRECT_URIS`. These match by exact string, so a code can only ever reach the vendor. Any other redirect URI is refused with `400 invalid_redirect_uri` before Better Auth sees the request. `post_logout_redirect_uris` stays loopback-only. The MCP protected resource is: ```text theme={null} https://app.formbricks.com/api/mcp ``` The authorization server issuer is: ```text theme={null} https://app.formbricks.com/api/auth ``` Discovery endpoints: | Endpoint | Purpose | | - | - | | `/api/auth/.well-known/oauth-authorization-server` | Better Auth authorization metadata | | `/api/auth/.well-known/openid-configuration` | OpenID Connect metadata | | `/.well-known/oauth-authorization-server/api/auth` | RFC 8414 path-insertion alias | | `/.well-known/openid-configuration/api/auth` | RFC 8414 OpenID path-insertion alias | | `/.well-known/oauth-protected-resource` | MCP protected resource metadata | | `/.well-known/oauth-protected-resource/api/mcp` | MCP resource-specific metadata | Supported scopes: | Scope | Use | | - | - | | `surveys:read` | `list_surveys`, `get_survey`, `validate_survey`, `get_workspace_custom_css` | | `surveys:write` | `create_survey`, `patch_survey`, `edit_survey_blocks`, `set_survey_block_order`, `delete_survey`, `patch_workspace_custom_css` | | `workflows:read` | `list_workflows`, `get_workflow`, `list_workflow_runs`, `get_workflow_run`, `test_workflow` | | `workflows:write` | `create_workflow`, `patch_workflow`, `duplicate_workflow`, `delete_workflow`, and the enable/disable/archive/unarchive mutations | | `feedbackRecords:read` | `list_feedback_datasets`, `list_feedback_records`, `count_feedback_records`, `get_feedback_record`, `search_feedback_records`, `find_similar_feedback_records` | | `feedbackRecords:write` | `create_feedback_record`, `create_feedback_records`, `update_feedback_record`, `delete_feedback_record` | | `responses:read` | `list_responses`, `count_responses`, `get_response` | | `responses:write` | `validate_response`, `create_response`, `update_response`, `delete_response`, `batch_delete_responses` | | `openid` | OpenID Connect subject interoperability | | `profile` | User profile claims | | `email` | User email claim | | `offline_access` | Refresh tokens for MCP clients | **The rule:** every MCP tool is registered through `registerScopedTool`, which takes the required scope(s) as a mandatory argument and runs the gate before the handler. Read tools declare `:read`; every mutating tool declares `:write`. A tool cannot be registered without declaring a scope, so a new tool inherits enforcement by construction — the gate returns a `403 insufficient_scope` before the handler touches a v3 operation. Tools that more than one scope group legitimately reaches pass `{ anyOf: [...] }` instead of a plain list, which keeps them on the same registration path rather than a hand-rolled gate. **There are no exceptions, and tests are what keep it that way.** The feedback-record tools were one for a while — they gated inside their own handler factories and registered through `server.registerTool` directly, which meant every handler was checked but a *new* tool added outside those factories would have registered unguarded. ENG-2119 moved all ten onto `registerScopedTool` and made `guardMcpScopes` / `guardMcpAnyScope` private again, so the guards are no longer reachable from a tool module. Be precise about what that guarantees. Privacy removes the hand-rolled gate, and the compiler stops you forgetting `registerScopedTool`'s scope argument — but it cannot stop a module calling `server.registerTool(...)` directly, because `server` is an argument to every tool module. No type system reaches that. The checks that do: a test pins `registerScopedTool` as the only export of `guard-scopes.ts`, and `feedback-records.test.ts` drives all ten tools with the opposite scope, which goes red if a tool is registered unguarded *or* wired to the wrong scope. **A new scope is advertised only together with a migration that grants it to existing clients.** `MCP_RESOURCE_SCOPES` is what the protected-resource metadata and the 401 challenge publish, and a spec-following client (the MCP SDK takes its scope from exactly those) asks for everything in it. The provider validates that request against the scopes the client *registered* with, so advertising a scope to clients that registered before it existed earns them `invalid_scope`. `responses:read` / `responses:write` show the full sequence: added to `MCP_OAUTH_SCOPES` and to the resource's `allowedScopes` (ENG-2862), then to each registered client's `scopes` by a data migration that mirrors what the client already holds and skips `skipConsent` clients, and only then to `MCP_RESOURCE_SCOPES` (ENG-3470). Skip the client migration and every integration registered before the scope existed breaks at its next sign-in. **There is no single mandatory baseline scope.** Authentication requires *at least one* resource scope (`MCP_RESOURCE_SCOPES`), so a workflows-only or `feedbackRecords:read`-only grant is a legitimate MCP client. `list_workspaces` — the workspaceId-discovery prerequisite for every resource tool — therefore gates on any resource read scope rather than one specific one; its result is derived from the caller's own memberships and key grants, so admitting any read scope exposes nothing extra. The authorization server supports all of the above, but the MCP protected-resource metadata (`/.well-known/oauth-protected-resource/api/mcp`) advertises only the resource scopes an MCP client needs — `surveys:read`, `surveys:write`, `workflows:read`, `workflows:write`, `feedbackRecords:read`, `feedbackRecords:write`, `responses:read`, `responses:write`, and `offline_access`. Clients derive their Dynamic Client Registration scopes from that list, so `offline_access` must be advertised there for clients to be issued refresh tokens (`openid`/`profile`/`email` are OIDC scopes the MCP resource does not require). > [!WARNING] > > Never advertise a new resource scope without a data migration that grants it to existing `oauthClient` > rows. The authorization server validates `/authorize` against the scopes the **client** registered > with, so a client registered before the change requests the newly advertised scope and is rejected with > `invalid_scope`. It does not fall back to the scopes it already holds, and re-consenting does not help, > because the same `client_id` is reused. Ship the migration in the same release as the list change, as > `responses:*` did (see [A new scope family](#a-new-scope-family)), and nothing breaks: users see one > consent screen naming the new scopes. If a client is already stuck on `invalid_scope`, it recovers by > registering again: remove and re-add the MCP server (for example `claude mcp remove `, then > `claude mcp add …`). OAuth scopes gate MCP tool categories at the token layer. Actual workspace access is still evaluated at tool execution through the existing v3 authorization checks for the signed-in Formbricks user, so a token scope and a workspace role are independent gates — a call must satisfy both. Scope groups are **independent**: a token authenticates as long as it holds at least one resource scope, so a `feedbackRecords:read`-only grant is valid and simply can't reach the survey tools. `list_workspaces` is the shared discovery tool and accepts either read scope. ### API-key fallback API-key MCP access remains supported. Authenticate with a Formbricks API key in a request header: ```http theme={null} Authorization: Bearer fbk_... ``` or: ```http theme={null} x-api-key: fbk_... ``` Do not pass credentials in the query string. The MCP route rejects query credential names such as `api_key`, `x-api-key`, `access_token`, `token`, and `authorization` case-insensitively. API key permissions are enforced through the same workspace access checks as the v3 REST API: | Tool | Minimum Workspace Permission | | - | - | | `list_responses` | `read` | | `count_responses` | `read` | | `get_response` | `read` | | `validate_response` | `write` or `manage` — a dry run, but it resolves the same references the write does | | `create_response` | `write` or `manage` | | `update_response` | `write` or `manage` | | `delete_response` | `manage` | | `batch_delete_responses` | `manage` | | `list_surveys` | `read` | | `get_survey` | `read` | | `create_survey` | `write` or `manage` | | `validate_survey` | `read` — a dry run; it validates a create or patch payload without writing | | `patch_survey` | `write` or `manage` | | `edit_survey_blocks` | `write` or `manage` | | `set_survey_block_order` | `write` or `manage` | | `delete_survey` | `write` or `manage` | | `get_workspace_custom_css` | `read` | | `patch_workspace_custom_css` | `manage` for an API key; an organization owner or manager for an OAuth user — stricter than `surveys:write` | | `list_workflows` | `read` | | `get_workflow` | `read` | | `list_workflow_runs` | `read` | | `get_workflow_run` | `read` | | `test_workflow` | `read` — a dry run; it validates the definition and resolves its trigger references, creating no run | | `create_workflow` | `write` or `manage` | | `patch_workflow` | `write` or `manage` | | `duplicate_workflow` | `write` or `manage` | | `delete_workflow` | `write` or `manage` | | `enable_workflow` | `write` or `manage` | | `disable_workflow` | `write` or `manage` | | `archive_workflow` | `write` or `manage` | | `unarchive_workflow` | `write` or `manage` | | `list_feedback_datasets` | `read` | | `list_feedback_records` | `read` | | `count_feedback_records` | `read` | | `get_feedback_record` | `read` | | `search_feedback_records` | `read` | | `find_similar_feedback_records` | `read` | | `create_feedback_record` | `write` or `manage` | | `create_feedback_records` | `write` or `manage` | | `update_feedback_record` | `write` or `manage` | | `delete_feedback_record` | `manage` | Synthesized MCP scopes for an API key: `surveys:read` + `workflows:read` + `feedbackRecords:read` always; the matching `:write` scopes when the key has `write` or `manage` on any workspace. The scope gate and the per-workspace access check above are independent — a `:write` tool requires **both** the `:write` scope on the token and write/manage on the target workspace. > [!WARNING] > > Store fallback MCP API keys as environment variables or client secrets. Do not commit API keys into MCP > client config files. ## Local Setup Start Formbricks and prepare the database: ```bash theme={null} pnpm db:up pnpm db:migrate:dev pnpm --filter @formbricks/web dev ``` > [!NOTE] > > Restart the dev server after changing tool registrations. The MCP server is built once at module scope by > `createMcpHandler`, so hot reload does not pick up an added, removed or renamed tool — `tools/list` keeps > serving the previous set until the process restarts. Verify OAuth discovery: ```bash theme={null} curl -sS http://localhost:3000/.well-known/oauth-protected-resource/api/mcp curl -sS http://localhost:3000/.well-known/oauth-authorization-server/api/auth ``` OAuth-capable MCP clients should dynamically register a public client and request `resource` equal to the MCP URL: ```text theme={null} http://localhost:3000/api/mcp ``` Manual Dynamic Client Registration smoke test: ```bash theme={null} curl -sS -X POST http://localhost:3000/api/auth/oauth2/register \ -H "Content-Type: application/json" \ --data '{ "client_name": "MCP Inspector", "redirect_uris": ["http://127.0.0.1:6274/oauth/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "openid profile email offline_access surveys:read surveys:write workflows:read workflows:write feedbackRecords:read feedbackRecords:write" }' ``` > [!NOTE] > > This passes `scope` explicitly, so it does **not** reproduce a real client's behavior — real MCP clients > register with the scopes from the protected-resource metadata's `scopes_supported` (`surveys:read > surveys:write workflows:read workflows:write feedbackRecords:read feedbackRecords:write offline_access`). > Because the authorization server validates the `/authorize` request against the client's **registered** > scopes, a client that registers with a narrower set than it later requests (e.g. it registers surveys-only > but requests `offline_access`) is rejected with `invalid_scope`. To smoke-test the real path, omit `scope` > and let the client adopt the advertised set, or pass exactly what the metadata advertises. > [!NOTE] > > For the same reason, the `scope` in the MCP endpoint's 401 `WWW-Authenticate` challenge is exactly > the metadata's `scopes_supported`, not a subset — a client that hits the 401 before fetching the > metadata uses the challenge string as its registration scope. The two are derived from one constant > (`MCP_CHALLENGE_SCOPE`) and a test asserts they stay equal; when they diverged, every new client > failed its first connect with `invalid_scope` and only succeeded on retry. The consent screen is served at `/account/authorize`. Users can revoke approved MCP clients from `/account/settings/authorized-apps`. For API-key fallback, create an API key in the Formbricks app with access to the target workspace. Use the least privileged permission needed by the agent workflow. Verify that the MCP endpoint can list tools: ```bash theme={null} export FORMBRICKS_MCP_API_KEY="fbk_..." curl -sS -X POST http://localhost:3000/api/mcp \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $FORMBRICKS_MCP_API_KEY" \ --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' ``` ## Codex Configuration ### OAuth Add the HTTP MCP server. Include `--oauth-resource` so the OAuth access token is audience-bound to the MCP resource URL: ```bash theme={null} codex mcp add formbricks-local \ --url http://localhost:3000/api/mcp \ --oauth-resource http://localhost:3000/api/mcp ``` Authenticate and request the scopes the agent needs: ```bash theme={null} codex mcp login formbricks-local \ --scopes openid,profile,email,offline_access,surveys:read,surveys:write,workflows:read,workflows:write,feedbackRecords:read,feedbackRecords:write ``` For read-only usage, omit the `:write` scopes: ```bash theme={null} codex mcp login formbricks-local \ --scopes openid,profile,email,offline_access,surveys:read,workflows:read,feedbackRecords:read ``` Scope groups are independent — a token needs at least one resource scope, but not all of them. To use only the feedback-record tools, request `feedbackRecords:read` (plus `feedbackRecords:write` to create) and omit the survey scopes. Codex opens the browser to Formbricks, completes Dynamic Client Registration, and stores the OAuth client and tokens in Codex's credential store. The user approves the requested scopes on the Formbricks consent screen. Equivalent Codex config for the server entry: ```toml theme={null} [mcp_servers.formbricks-local] url = "http://localhost:3000/api/mcp" oauth_resource = "http://localhost:3000/api/mcp" ``` Verify the registration: ```bash theme={null} codex mcp list codex mcp get formbricks-local ``` Then ask Codex to use the configured server: ```text theme={null} Use the formbricks-local MCP server to list surveys for workspace clxx1234567890123456789012. ``` ### API-key fallback Store the API key in the shell environment: ```bash theme={null} export FORMBRICKS_MCP_API_KEY="fbk_..." ``` For Codex Desktop on macOS, persist the value in the launch environment and restart Codex Desktop: ```bash theme={null} launchctl setenv FORMBRICKS_MCP_API_KEY "fbk_..." ``` Register the local MCP server with a bearer-token environment variable: ```bash theme={null} codex mcp add formbricks-local-api-key \ --url http://localhost:3000/api/mcp \ --bearer-token-env-var FORMBRICKS_MCP_API_KEY ``` ## Claude Configuration ### Claude Code #### OAuth Add the remote HTTP MCP server: ```bash theme={null} claude mcp add --transport http formbricks-local http://localhost:3000/api/mcp ``` Run `/mcp` and authenticate `formbricks-local`. Claude Code discovers the MCP protected-resource metadata, registers a public client whose scopes are taken from that metadata's `scopes_supported` (`surveys:read surveys:write workflows:read workflows:write feedbackRecords:read feedbackRecords:write offline_access`), and launches the browser-based OAuth flow — there is no scope-entry step. You approve the requested scopes on the Formbricks consent screen. A `:write` tool requires both the matching `:write` scope on the token and write/manage permission on the target workspace at execution time (see [Authentication](#authentication)). Verify it: ```bash theme={null} claude mcp list claude mcp get formbricks-local ``` For project-shared Claude Code configuration, use `.mcp.json` without static credentials: ```json theme={null} { "mcpServers": { "formbricks-local": { "type": "http", "url": "http://localhost:3000/api/mcp" } } } ``` If the installed Claude Code version does not start the OAuth flow for remote HTTP servers, use the API-key fallback below until that client is updated. #### API-key fallback Set the API key: ```bash theme={null} export FORMBRICKS_MCP_API_KEY="fbk_..." ``` Add the HTTP MCP server: ```bash theme={null} claude mcp add --transport http formbricks-local-api-key http://localhost:3000/api/mcp \ --header "Authorization: Bearer $FORMBRICKS_MCP_API_KEY" ``` For a project-shared fallback configuration, keep the API key outside git: ```json theme={null} { "mcpServers": { "formbricks-local-api-key": { "headers": { "Authorization": "Bearer ${FORMBRICKS_MCP_API_KEY}" }, "type": "http", "url": "http://localhost:3000/api/mcp" } } } ``` Claude Code will fail to parse this fallback config if `FORMBRICKS_MCP_API_KEY` is not set. ### Claude Desktop If the installed Claude Desktop build supports remote HTTP MCP server entries, add the same server definition to the Claude Desktop config file and restart Claude Desktop. Prefer the OAuth entry without headers when supported; use the API-key header entry only as a fallback. macOS config path: ```text theme={null} ~/Library/Application Support/Claude/claude_desktop_config.json ``` Example config: ```json theme={null} { "mcpServers": { "formbricks-local": { "type": "http", "url": "http://localhost:3000/api/mcp" } } } ``` Fallback config with an API key: ```json theme={null} { "mcpServers": { "formbricks-local-api-key": { "headers": { "Authorization": "Bearer ${FORMBRICKS_MCP_API_KEY}" }, "type": "http", "url": "http://localhost:3000/api/mcp" } } } ``` Set the API key in the Desktop launch environment before opening Claude Desktop when using the fallback config: ```bash theme={null} launchctl setenv FORMBRICKS_MCP_API_KEY "fbk_..." ``` If a Claude Desktop version only supports stdio MCP servers, use Claude Code for the HTTP endpoint or add a local stdio-to-HTTP bridge. ## Tool Responses Tool results include both `structuredContent` and a text content item containing the same JSON string. Successful results mirror the v3 REST response body and add `requestId` for correlation. Errors are returned as MCP error tool results with a structured v3 problem payload: ```json theme={null} { "error": { "code": "bad_request", "detail": "Invalid survey document", "invalid_params": [ { "name": "blocks.0.elements.0.headline", "reason": "Required" } ], "requestId": "req_...", "status": 400, "title": "Bad Request" } } ``` ### Declared result shapes The response tools advertise an `outputSchema`, which no other tool does yet. A client can read the result shape off `tools/list` rather than inferring it from an example, and the SDK checks the structured result against the same schema it advertised. One object root with every branch optional, built by `mcpToolOutput`: a tool answers either the success payload or the error one, which reads like a union — but a union converts to a root-level `anyOf`, and the SDK then wraps the result for a 2025-era client to keep the wire shape legal. An object root is identity on both eras, so the same structured payload reaches every client. The cost is that the schema cannot say "exactly one of these", which is why the error branch is described in full: a client can still tell the two apart by which key is present. ## Tool Arguments Every tool input schema is **strict**: an argument a tool does not declare is rejected, not ignored. The advertised JSON Schema carries `additionalProperties: false`, and the SDK validates the call before the handler runs, so an undeclared or misspelled key comes back as an input-validation error result and the underlying v3 operation is never reached. This matters most on filters. A dropped filter does not narrow, so the pre-strict behaviour ran the query wider than asked and reported success — `count_feedback_records` with a misspelled `userId` (the correct key is `user_id`) returned the count for every record in the dataset, which an agent has no way to tell from a real answer. Strictness applies at every depth, not just to the outermost object: a misspelled key inside `filter.status` is rejected the same way a misspelled top-level argument is. This matters because a dropped nested filter key does not merely lose the key — it leaves the filter object empty, so the query runs wider than asked. Two kinds of exception: * **Free-form by design.** `blocks`, `metadata`, `welcomeCard` and friends on `create_survey`, and the `data` payload on `patch_survey` / `validate_survey`, accept any nested shape. They are validated by the v3 survey document contract once the call reaches the operation. * **The workflow `definition`.** Everything below `definition` on `create_workflow` and `patch_workflow` is still open, so a misspelled key inside a trigger, node, edge or node `config` is dropped rather than rejected. That schema is shared with the v3 Workflows REST API and the workflow builder, so tightening it is a v3 API change rather than an MCP one; it is tracked as ENG-2437. Treat a `create_workflow` result as confirming only what it echoes back. > [!NOTE] > > A client that adds its own keys to a tool call's `arguments` will be rejected. Nothing in the MCP spec > invites that, but it is a behaviour change from earlier Formbricks releases, which silently dropped > such keys. > > Two consequences worth knowing. **Read-modify-write needs trimming:** `update_feedback_record` accepts > only the eight mutable fields, so echoing a record straight back from `get_feedback_record` is rejected > — strip the provenance (`source_*`, `field_*`, `submission_id`, `collected_at`) and the derived > sentiment/emotions/translation first. The error names every key to remove. And **`list_workspaces` > takes no arguments at all**, so a client that pads zero-argument calls with a placeholder key will fail > on the one tool every other workspace-scoped tool depends on for its `workspaceId`. Array arguments are bounded. No array in a tool call may hold more than 1 000 items, and all the arrays in one call together at most 50 000 elements, at any depth; and a call may nest at most 256 levels of objects and arrays. A call over any of these is refused with a JSON-RPC `-32602` error before its arguments are parsed. Fields with a tighter bound advertise it as `maxItems` in the tool's input schema — `create_survey`'s `blocks`, `endings`, `variables` and `languages`, `get_survey`'s `lang`, the list filters' `in` arrays, and `create_feedback_records`' `records`. A request body may be at most 2 MB, whether or not it declares a `Content-Length`. ## Adding a tool A tool is a thin adapter over a v3 operation: it parses its input, calls the operation with the caller's authentication, and relays the result. It never queries the database or checks tenancy itself — the operation owns both — so the MCP surface follows the v3 API rather than growing semantics of its own. **1. Start from the operation** Find or add the operation in `apps/web/app/api/v3//lib/operations.ts`, with its REST route and OpenAPI entry. Operations **return** a `Response` for every outcome, errors included, and never throw: MCP calls them without the route wrapper. Two families differ: workflow tools call the `@formbricks/workflows` handlers through `app/api/v3/workflows/lib/context.ts`, and feedback-record tools call operations over the Hub service while the REST route proxies straight to the Hub, so they have no one-to-one REST twin. **2. Declare the input** In `tools/schemas.ts` (or `tools/-schemas.ts`). Use `.strict()` on the object and `z.strictObject` on nested ones, `lengthBoundedArray` for arrays, `.describe()` on every field, and `.extend()` the v3 body schema rather than restating it. `schemas.test.ts` fails on any structured object that is not strict, but only in the modules it spreads into `allExports` — add a new schema module there. Never take a tenant id from input. **3. Declare the output** `outputSchema: mcpToolOutput()`, built from the v3 resource schema and never retyped. The SDK validates every successful result against it (error results are skipped), so a schema that drifts fails every call that would otherwise have succeeded. **4. Register it** In `tools/.ts`, through `registerScopedTool` — the only registration path, which runs the scope gate before the handler. Reads call the operation directly: ```ts theme={null} registerScopedTool( server, "get_response", { title: "Get response", description: "Read one survey response in full. Operates on responses, not feedback records.", inputSchema: ZMcpGetResponseInput, outputSchema: ZMcpResponseOutput, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, }, ["responses:read"], async (input: TMcpGetResponseInput, ctx) => { const authInfo = getMcpToolAuthInfo(ctx); const requestId = getMcpRequestId(authInfo); const response = await getV3Response({ responseId: input.responseId, authentication: getMcpAuthentication(authInfo), requestId, instance: MCP_API_ROUTE, }); return await responseToMcpToolResult(response, requestId); } ); ``` A mutation differs in two places, and both are needed: `audit: { action, targetType, targetIdArg? }` in the config (records a call the scope gate refused) and `runMcpMutation(ctx, { action, resource }, ({ authentication, requestId, auditLog }) => operation(...))` in the handler (records the outcome). Gate writes on `:write`. A dry run is `read` only if it is a pure function of its input (`validate_survey`); one that resolves references is `write` (`validate_response`). **5. Test it** Next to the tool, in `tools/.test.ts`: drive the handler with the opposite scope and assert the 403 detail, and assert the roster of registered names (see `responses.test.ts` and `feedback-records.test.ts`). Run `pnpm test`; restart the dev server to see the tool in `tools/list`. **6. Document it** Add its section under [Available Tools](#available-tools), a row in the scope, permission and REST-mapping tables on this page, and in the scope table of `platform/mcp/overview.mdx` if it adds a tool to a scope. ### A new scope family Reusing `:read` / `:write` needs nothing more. A new resource family also needs: 1. The scope pair in `MCP_OAUTH_SCOPES` (`modules/auth/lib/oauth-urls.ts`), and a data migration that appends it to existing `oauthResource.allowedScopes` rows — `mcp-oauth-resource-seed.test.ts` fails until the migration is listed in its `REPAIR_MIGRATIONS`. Without it, on every instance that already upgraded, a client asking only for the new scope gets `invalid_scope`, and one asking for it alongside others is silently granted less than it asked for. Neither logs. 2. API-key scopes in `getMcpScopes` (`modules/mcp/auth.ts`), the consent label in `getOAuthScopeLabel` plus its en-US string (then `pnpm i18n`), and the `anyOf` list on `list_workspaces`. 3. `registerXTools(server)` in `modules/mcp/server.ts`, before the final `instrumentMcpServerWithTracing`. 4. Last, `MCP_RESOURCE_SCOPES`, which advertises the scope, in the same release as a data migration that appends the pair to existing `oauthClient.scopes` rows. Mirror read/write (`:read` only for clients that hold a read scope) and skip `skipConsent` clients, as `20261005130000_eng_3470_grant_responses_scopes_to_clients` does. Without it, every client registered before the scope existed requests it and gets `invalid_scope` at its next sign-in (see [Authentication](#authentication)). ### What makes a tool good * **One tool per operation.** An MCP-only convenience tool is a second surface to document, test and keep in step. When an operation's shape costs the agent real tokens or errors, add a better v3 operation instead — `edit_survey_blocks` is one (`PATCH /api/v3/surveys/{surveyId}/blocks`), addressing blocks by id rather than resending the whole array. * **Descriptions are paid for on every session.** `tools/list` ships every description and every field `.describe()` to the model each time. State what the tool does, its side effects, and when to prefer another tool. Spend a long description only where the wrong pick is likely *and* silent (`list_responses` against feedback records); everywhere else use the one-line form. * **Small pages, cheap counts.** Cap `limit` below the REST maximum (default 20, max 50–100 against 250), keep expensive totals opt-in, use opaque cursors, and give list-shaped resources a `count_*` tool so "how many" never means paging. * **Concise by default.** Return the handle for the next call, not the whole resource: `response_format: "concise"` returns `id` and `updatedAt`, which is the next call's `expectedUpdatedAt`. The projection is MCP-only; REST keeps the full resource. * **Errors that say what to do next.** Relay the v3 problem document unchanged: `invalid_params` names the field, a `409` carries `currentUpdatedAt`. Reject unknown keys instead of dropping them. * **Honest annotations.** `destructiveHint: true` whenever the previous value is unrecoverable from the result, including whole-subtree replaces. For an irreversible delete, consider confirming first the way `delete_response` does (elicitation, with a `confirm` argument for clients that cannot answer prompts). ## Available Tools ### list\_surveys Lists surveys in one workspace. The tool is read-only and idempotent. Input: ```json theme={null} { "cursor": "opaque-cursor-from-previous-response", "filter": { "name": { "contains": "feedback" }, "status": { "in": ["draft", "inProgress"] }, "type": { "in": ["link"] } }, "includeTotalCount": true, "limit": 20, "sortBy": "updatedAt", "workspaceId": "clxx1234567890123456789012" } ``` Output: ```json theme={null} { "data": [ { "createdAt": "2026-04-21T10:00:00.000Z", "creator": { "name": "Ada Lovelace" }, "id": "clsv1234567890123456789012", "name": "Product Feedback", "responseCount": 0, "status": "draft", "type": "link", "updatedAt": "2026-04-21T11:00:00.000Z", "workspaceId": "clxx1234567890123456789012" } ], "meta": { "limit": 20, "nextCursor": null, "totalCount": 1, "workspaceSurveyCount": 3 }, "requestId": "req_..." } ``` `totalCount` is the number of surveys matching the filters; `workspaceSurveyCount` is every survey in the workspace, archived ones included and independent of the filters, so it can be larger. Both are `null` when `includeTotalCount` is `false`. ### get\_survey Gets one survey by ID. The tool is read-only and idempotent. Input: ```json theme={null} { "lang": ["en-US"], "surveyId": "clsv1234567890123456789012" } ``` `lang` is optional. When supplied, it filters translatable survey fields to the requested language codes or configured aliases. ### create\_survey Creates a block-based link survey using the v3 survey document contract. The tool writes data and is not idempotent. A block is `{ name, elements[], id? }`; an element is `{ id, type, headline, ... }`. The element `type` is one of `fileUpload`, `openText`, `multipleChoiceSingle`, `multipleChoiceMulti`, `nps`, `cta`, `rating`, `consent`, `pictureSelection`, `cal`, `date`, `matrix`, `address`, `ranking`, `contactInfo`, `csat`, `ces`. Element ids are caller-supplied and become immutable once the survey leaves draft; block ids are generated when omitted. Translatable fields are keyed by locale code and must carry every configured language — the internal `default` key is rejected. The same list is carried on the tool's own `blocks` description, generated from `TSurveyElementTypeEnum` so the two cannot drift. Per-type required fields are not restated here. `validate_survey` will reject an element that is missing them, but it reports the element **by its position** rather than naming the field: the element schema is an undiscriminated union, so a wrong or absent `type` makes every branch fail and the message is a generic `Invalid input`. Send the type's own fields with the element rather than expecting the validator to name them. Input: ```json theme={null} { "blocks": [ { "elements": [ { "headline": { "de-DE": "Was sollen wir verbessern?", "en-US": "What should we improve?" }, "id": "satisfaction", "required": true, "type": "openText" } ], "name": "Main Block" } ], "defaultLanguage": "en-US", "endings": [], "hiddenFields": { "enabled": false }, "languages": [ { "code": "de-DE", "enabled": true } ], "metadata": { "cx_operation": "enterprise_onboarding", "title": { "de-DE": "Produktfeedback", "en-US": "Product Feedback" } }, "name": "Product Feedback Survey", "status": "draft", "variables": [], "welcomeCard": { "enabled": true, "headline": { "de-DE": "Willkommen", "en-US": "Welcome" } }, "workspaceId": "clxx1234567890123456789012" } ``` Output uses the same survey resource shape as `GET /api/v3/surveys/{surveyId}` and includes the MCP `requestId`. ### validate\_survey Validates a create or patch payload without writing survey changes. The tool is read-only and idempotent; workspace access is still checked when `workspaceId` is present, at `read` level — matching the `surveys:read` scope the tool declares. Create validation input: ```json theme={null} { "data": { "blocks": [ { "elements": [ { "headline": { "en-US": "What should we improve?" }, "id": "satisfaction", "required": true, "type": "openText" } ], "name": "Main Block" } ], "defaultLanguage": "en-US", "name": "Product Feedback Survey", "workspaceId": "clxx1234567890123456789012" }, "operation": "create" } ``` Patch validation input: ```json theme={null} { "data": { "name": "Updated Product Feedback Survey" }, "operation": "patch", "surveyId": "clsv1234567890123456789012" } ``` Validation failures return `200` with `valid: false` and structured `invalid_params`, matching `POST /api/v3/surveys/validate`. Custom CSS validation input — processes CSS alone, for a preview, without saving anything: ```json theme={null} { "data": { "customCss": { "dark": null, "light": "[data-fb-part=\"headline\"] { font-weight: 600; }" } }, "operation": "customCss", "scope": "survey", "surveyId": "clsv1234567890123456789012", "workspaceId": "clxx1234567890123456789012" } ``` `scope` is `workspace` or `survey`; `surveyId` is optional, survey scope only, and must belong to `workspaceId`. A valid result carries the compiled `customCss` and `warnings` (removed constructs, each with a stable `code`, `appearance`, `line`, `column` and `reason`); an invalid one carries `errors` and no compiled output. A create or patch payload that includes `customCss` is processed the same way, additively. ### patch\_survey Updates a survey by ID using the v3 survey patch contract. The tool writes data, can be destructive, and is not idempotent. Omitted top-level fields are preserved. Provided top-level objects and arrays replace that whole subtree, so omitted nested entries inside a provided subtree can be removed. The patch tool does not deep-merge nested objects and does not implement JSON Patch. For a change confined to one or a few blocks, prefer `edit_survey_blocks`, which does not require resending the others. The full `get_survey` output may be sent straight back: server-owned fields (`id`, `workspaceId`, `type`, `createdAt`, `archivedAt`, `defaultLanguage`, `languages[].alias`) are accepted and verified, and changing one is a `422` `read_only_field` rather than a silent ignore. A round-tripped `updatedAt` acts as an optimistic-concurrency precondition, so the patch is rejected with `409` if the survey changed since your read. > [!NOTE] > > For agent workflows, fetch the current survey first, modify only the intended top-level fields, run > `validate_survey` with `operation: "patch"`, and then submit the same patch with `patch_survey`. If > the change is confined to blocks, stop here and use `edit_survey_blocks` or > `set_survey_block_order` instead — they are cheaper and cannot drop a block by omission. Input: ```json theme={null} { "data": { "metadata": { "cx_operation": "enterprise_onboarding", "title": { "en-US": "Updated Product Feedback" } }, "name": "Updated Product Feedback" }, "surveyId": "clsv1234567890123456789012" } ``` Output uses the same survey resource shape as `GET /api/v3/surveys/{surveyId}` and includes the MCP `requestId`. `customCss` on `create_survey` and `patch_survey` is source only — `{ "light": "…", "dark": "…" }`, both keys, each a string or `null`; `null` clears it, and on a patch an omitted `customCss` is kept. Compiled output is computed by the server, and a payload carrying `compiled` or `processorVersion` is rejected. A successful write that processed CSS returns the removed constructs as a top-level `warnings` array beside `data`; adding or editing CSS on a Cloud organization without the Scale plan is a `403` `custom_css_plan_required`, clearing it never is. `get_survey` returns the source in `customCss`. ### get\_workspace\_custom\_css Reads a workspace's shared survey CSS: `customCss` and `previous` (the one recoverable revision) as source, `status` (`ok`, `stale` — recompiled from source because the processor changed — or `withheld`, when that source no longer passes and respondents get none of it), and `canEdit` / `planAllowed` for the caller. Read-only and idempotent; `surveys:read` plus read access to the workspace. Input: ```json theme={null} { "workspaceId": "clxx1234567890123456789012" } ``` ### patch\_workspace\_custom\_css Saves or clears the workspace's shared survey CSS. `customCss` replaces both fields; `null` clears all of it, and unchanged source writes nothing. Removed constructs come back as top-level `warnings`; CSS the processor rejects is a `422` with `details.errors`, and the saved CSS stays in effect. The replaced value becomes `previous`, restored by sending its source back. The scope is `surveys:write` because this is shared survey CSS, but the scope is only the first gate: the operation still requires an **organization owner or manager** (OAuth or session user) or an API key with **`manage`** on the workspace — a `write` grant is refused — and, on Cloud, the Scale plan to add or edit. Both refusals, like a scope refusal, are audited. Input: ```json theme={null} { "customCss": { "dark": "#fbjs[data-appearance=\"dark\"] { --acme-ink: #e6eef5; }", "light": "[data-fb-part=\"button-primary\"] { border-radius: 999px; }" }, "workspaceId": "clxx1234567890123456789012" } ``` Both tools declare an `outputSchema`: the workspace custom CSS resource under `data`, plus `warnings` on a write. ### edit\_survey\_blocks Edits a survey's blocks in place — update, insert or remove whole blocks without resending the ones you are not changing. The tool writes data, can be destructive, and is not idempotent. Operations apply in order against a single snapshot and land atomically: either all of them do or none do. Blocks are addressed by id, never by position, so a concurrent edit cannot redirect an operation onto a different block. An `update` replaces the target block entirely, and the replacement must carry every language the survey has configured. An `insert` anchors at `start`, `end`, or `after` a block id — including one an earlier operation in the same request inserted. `block.id` is optional on both: an insert without one gets a server-generated id, returned in the concise response's `applied` list, and an update takes it from the operation's `id`. Removing a block orphans any answers already collected for its elements, and the API cannot undo that. The editor shows a human a caution before this; an agent has no equivalent, so confirm with the user before removing a block from a survey that is not a draft. > [!NOTE] > > Fetch the survey first and pass its `updatedAt` as `expectedUpdatedAt`. If the survey changed since > your read the call returns `409` with both timestamps in `details` — re-read and retry. The concise > response carries the new `updatedAt`, so a run of edits chains without fetching again. Input: ```json theme={null} { "expectedUpdatedAt": "2026-04-21T10:00:00.000Z", "ops": [ { "id": "k1p9wq2m4x7c3v8b5n6t0j2r", "op": "update", "block": { "id": "k1p9wq2m4x7c3v8b5n6t0j2r", "name": "Satisfaction", "elements": [ { "headline": { "en-US": "How satisfied were you?" }, "id": "satisfaction", "inputType": "text", "required": true, "type": "openText" } ] } } ], "response_format": "concise", "surveyId": "clsv1234567890123456789012" } ``` Output defaults to a concise acknowledgement — `id`, `updatedAt`, `blockCount` and the operations applied — plus the MCP `requestId`. The full survey resource is \~15k tokens on a large survey, which would refill an agent's context as fast as resending the blocks did, so it is opt-in via `response_format: "detailed"`. `REST` always returns the full resource. ### set\_survey\_block\_order Replaces the order of a survey's blocks by listing every current block id exactly once. Block content is untouched. The tool writes data and can be destructive, but unlike every other survey write it is **idempotent**: the same order yields the same survey, and an order that already matches performs no write at all, so `updatedAt` does not move and other callers' preconditions stay valid. A stale `expectedUpdatedAt` still returns `409` on that path: the precondition is evaluated before the method, so a no-op outcome never reports success to a caller whose view is out of date. Because the list must be a permutation, a dropped or duplicated block is rejected rather than silently applied — the failure that resending the whole `blocks` array cannot catch. Input: ```json theme={null} { "expectedUpdatedAt": "2026-04-21T10:00:00.000Z", "order": [ "b4h8s2d6f0g3j5k7l9z1x3c5", "k1p9wq2m4x7c3v8b5n6t0j2r" ], "response_format": "concise", "surveyId": "clsv1234567890123456789012" } ``` Output matches `edit_survey_blocks`: concise by default, echoing the applied `order`. ### delete\_survey Deletes one survey by ID. The tool is destructive, writes data, and is not idempotent. Input: ```json theme={null} { "surveyId": "clsv1234567890123456789012" } ``` The v3 REST delete operation returns `204 No Content`. The MCP tool result contains the `requestId` so callers can correlate the audit trail: ```json theme={null} { "requestId": "req_..." } ``` ### Workflow tools Workflow tools operate on the v3 Workflows API (trigger → condition → action automations). They reuse the same authentication, authorization, audit logging, and error mapping as the survey tools. #### list\_workflows Lists workflows in one workspace. Read-only and idempotent. Input: ```json theme={null} { "cursor": "opaque-cursor-from-previous-response", "filter": { "name": { "contains": "welcome" }, "status": { "in": ["draft", "enabled"] } }, "limit": 20, "sortBy": "updatedAt", "workspaceId": "clxx1234567890123456789012" } ``` Output mirrors the v3 list envelope: `{ "data": [...], "meta": { "limit", "nextCursor" }, "requestId" }`. Omitting `filter.status.in` returns every status except archived. #### get\_workflow Gets one workflow by ID. Read-only and idempotent. Unknown or cross-workspace ids return `403` (never `404`) so existence is not leaked. ```json theme={null} { "workflowId": "clwf1234567890123456789012" } ``` #### list\_workflow\_runs Lists workflow runs for a workspace, newest first. Read-only and idempotent. ```json theme={null} { "filter": { "isDryRun": false, "status": { "in": ["completed"] } }, "limit": 20, "responseId": "clrs1234567890123456789012", "workflowId": "clwf1234567890123456789012", "workspaceId": "clxx1234567890123456789012" } ``` Only `workspaceId` is required. Omit `filter.isDryRun` to return both real and dry runs. #### get\_workflow\_run Gets one workflow run with its ordered step logs. Read-only and idempotent. ```json theme={null} { "runId": "clrn1234567890123456789012" } ``` #### test\_workflow Dry-runs a workflow: validates its live definition would execute and resolves the trigger's survey + ending cards. No run is persisted and no side effects occur; the result reports `{ ok, problems }`. Annotated read-only (no world mutation). **Drafts are testable** — checking the setup before going live is the point of a dry run — so a workflow can be tested straight after `create_workflow`. Only **archived** workflows are rejected, with `422 invalid_workflow_state`, since they are soft-deleted. ```json theme={null} { "workflowId": "clwf1234567890123456789012" } ``` #### create\_workflow Creates a workflow, always as a draft (only `enable_workflow` makes it live). Writes data; not idempotent. Takes the full v3 create payload: ```json theme={null} { "definition": { "edges": [], "entryNodeId": "trigger", "nodes": [], "schemaVersion": 1, "trigger": { "config": { "endingCardIds": ["ending-1"], "surveyId": "clsv1234567890123456789012" }, "id": "trigger", "triggerType": "response.completed", "type": "trigger" } }, "name": "Notify on churn survey completion", "workspaceId": "clxx1234567890123456789012" } ``` #### patch\_workflow Updates a workflow (v3 PATCH contract: top-level partial merge, no deep merge). Destructive; not idempotent. `definition` edits are only accepted while the workflow is draft or disabled. ```json theme={null} { "data": { "name": "Renamed workflow" }, "workflowId": "clwf1234567890123456789012" } ``` #### duplicate\_workflow Duplicates a workflow as a new draft with empty run and version history. Writes data; not idempotent. ```json theme={null} { "name": "Copy of workflow", "workflowId": "clwf1234567890123456789012" } ``` `name` is optional; if omitted the server picks a non-conflicting copy name. #### Lifecycle tools `delete_workflow`, `enable_workflow`, `disable_workflow`, `archive_workflow`, and `unarchive_workflow` each take only a workflow id: ```json theme={null} { "workflowId": "clwf1234567890123456789012" } ``` * `enable_workflow` — validates executability, snapshots an immutable version, and makes the workflow live. A non-executable definition is refused with `422 workflow_not_executable`. > [!WARNING] > > Once live, the workflow runs on matching survey responses and can send emails. * `disable_workflow` — stops future runs. * `archive_workflow` / `unarchive_workflow` — soft archive and restore (to draft). * `delete_workflow` — the v3 delete returns `204 No Content`; the MCP result contains the `requestId`. ### Response tools Eight tools, one per documented v3 response operation. The set mirrors the API deliberately: what an agent can do through MCP is what an API key can do over HTTP, read off one list rather than two. Every tool description states the boundary against the feedback-record tools, because `list_feedback_records(source_id=)` looks like it answers the same question and does not — see **Feedback Records And The Hub** below. The full paragraph goes on `list_responses` and `count_responses`, where the wrong pick is both likely and quiet; the others carry a one-line form, since a description is context every client pays for on every `tools/list`. #### list\_responses / count\_responses / get\_response Read-only and idempotent. `workspaceId` is always required; `surveyId` or `contactId` narrows it, and the `finished` and `language` filters require one of those two anchors because without one they are unbounded scans. `list_responses` caps `limit` at 50 — below the API's 250, because an agent's binding constraint is its context window and a response carries every answer. ```json theme={null} { "workspaceId": "clxx1234567890123456789012", "surveyId": "clsv1234567890123456789012", "finished": true, "limit": 20 } ``` #### validate\_response A dry run of a create or patch: reports `valid`, `invalid_params`, and — when valid — the `effects` a write would have, including the language that would be stamped and the quotas that would count. It declares `responses:write` although it writes nothing, because it resolves the same references the write resolves; gating it at read would make it a cheaper existence probe than the operation it describes. ```json theme={null} { "operation": "create", "data": { "surveyId": "clsv…", "finished": true, "data": {} } } ``` #### create\_response / update\_response `create_response` records a real submission: webhooks, integrations, follow-ups, quotas and metering all run. `update_response` replaces `data` and `tags` wholesale rather than merging, which is why it is annotated `destructiveHint: true` — to add one tag, read the response and send every tag it should end up with. Both take the v3 body as an opaque `data` argument and let the operation parse it, so the tool and the route answer the same thing to a malformed body. #### delete\_response / batch\_delete\_responses Both **ask before they delete**, over the multi-round-trip `input_required` flow: the first call returns an `elicitation/create` request and an opaque `requestState`, and the client retries with the answer. The pending confirmation is HMAC-sealed by `createRequestStateCodec` and bound to the caller, and the handler compares the sealed `resourceId` against the arguments on re-entry. Both come back through the client, so without that comparison a client could be asked about response A and retry the confirmation against response B. The batch tool binds the exact id list, so a confirmation for two ids does not carry over to a third. `confirm: true` skips the prompt. That is not a convenience bolted on afterwards — it is the path a 2025-era client and a headless caller use, and without it those clients could not delete at all. ```json theme={null} { "responseId": "clrs1234567890123456789012", "confirm": true } ``` Both are `idempotentHint: true`: a response that is already gone answers the same `403` as one that was never this caller's, so repeating the call converges rather than compounding. ### list\_feedback\_datasets Lists the active feedback datasets assigned to a workspace. Read-only and idempotent. Use the returned `id` as `datasetId` for the other feedback-record tools. Input: ```json theme={null} { "workspaceId": "clxx1234567890123456789012" } ``` Output: ```json theme={null} { "data": [{ "id": "clfd1234567890123456789012", "name": "Support" }], "meta": { "nextCursor": null, "totalCount": 1 }, "requestId": "req_..." } ``` ### list\_feedback\_records Lists feedback records in a workspace's feedback dataset. Read-only and idempotent, with opaque cursor pagination. `datasetId` is optional when the workspace has exactly one active dataset (the common case) and required when it has more than one. Input: ```json theme={null} { "cursor": "opaque-cursor-from-previous-response", "datasetId": "clfd1234567890123456789012", "field_group_id": "grp_1", "field_id": "q1", "field_type": ["text", "rating"], "has_sentiment": true, "limit": 50, "order": "desc", "sentiment": ["negative", "very_negative"], "since": "2026-01-01T00:00:00Z", "sort": "collected_at", "source_id": "svy_1", "source_type": ["survey", "review"], "submission_id": "sub_1", "until": "2026-12-31T23:59:59Z", "user_id": "user_1", "value_id": "opt_1", "workspaceId": "clxx1234567890123456789012" } ``` All filters are optional. They mirror the Hub's own `GET /v1/feedback-records` parameters, and each is named after the record field it filters — so filtering by a `user_id` you just read in a response is spelled the same way. An unknown filter key is rejected with a 422 rather than ignored, since a silently dropped filter would widen the result set without saying so. **How they combine.** Every identity filter accepts one value or a list of them. Repeating one filter **OR**s its values; different filters are **AND**ed. So `source_type: ["survey", "review"]` with `sentiment: ["negative"]` reads as *"(survey OR review) AND negative"*. There is no way to OR across different filters. | Filter | Selects | | - | - | | `source_type` | a kind of source, e.g. `survey`, `review`, `call_notes` | | `source_id` | one survey/form/ticket | | `source_name` | one source by display name | | `field_type` | one field type (`text`, `nps`, `rating`, …) | | `field_id` | all answers to one question | | `field_group_id` | one grouped question (ranking, matrix, grid) | | `submission_id` | the sibling answers given in one submission | | `user_id` | everything one end user submitted | | `value_id` | everyone who picked one particular choice | | `language` | the language the feedback was given in | | `sentiment` | a sentiment label; only enriched records carry one | | `emotions` | **any** of the listed emotion labels, never all of them | | `since` / `until` | a `collected_at` range (must fall between 1970-01-01 and 2080-12-31) | | `created_since` / `created_until` | a `created_at` range — "what did this import bring in" | | `updated_since` / `updated_until` | an `updated_at` range — "what was created or changed since" | | `value_date_min` / `value_date_max` | a range over the date *answer*, not the collection time | | `value_number_min` / `value_number_max` | a range over the numeric answer | | `sentiment_score_min` / `sentiment_score_max` | a sentiment score range, from -1 to 1 | | `has_sentiment` | records that do (`true`) or do not (`false`) carry a sentiment | | `has_emotions` | records that do or do not carry emotion labels | | `has_translation` | records that do or do not have a translation | Value limits mirror the Hub's: at most 100 values per filter (the enum filters cap at their own label count instead), 255 characters per value, and 10 for a `language` tag. Crossing either bound is a 422 naming the filter, never a silent truncation to the first 100. An empty string is **not** the same thing here as on the Hub directly: the Hub treats `?source_type=` as identical to omitting the filter, but every string filter on this surface requires at least one character, so an empty value is rejected rather than ignored. > [!WARNING] > > **Every range filter excludes records whose column is empty.** `value_number_min: 0` is not > "everything" — it drops every text answer, because they carry no number. Likewise > `sentiment_score_min: -1` means "every *enriched* record", not every record. To find the records > enrichment has not reached, use `has_sentiment: false` rather than a score range. > [!WARNING] > > **A backwards range is rejected, not run as an empty query.** `value_number_min: 5, value_number_max: 1` > is a `400` naming both bounds (e.g. `value_number_min` — "must be less than or equal to > value\_number\_max"). This applies to every range pair, including the timestamp ones; it is the Hub's own > check relayed as-is, not something validated here, so the message always names the Hub's parameters. **Ordering.** `sort` accepts `collected_at` (the default), `created_at` or `updated_at`, and `order` accepts `asc` or `desc` (default `desc`). `updated_at` is ascending-only: pass `order: asc` explicitly, since the Hub answers 400 to `desc` and to an omitted `order`. Neither applies to `count_feedback_records`, which rejects them. A cursor marks a position *within one specific ordering*, so keep `sort` and `order` identical for the whole traversal — presenting a cursor under a different ordering is rejected rather than silently returning a page that looks like a continuation. `collected_at` and `created_at` diverge whenever historical data is imported: the feedback was collected months ago but stored today. Use `created_since` for "what did this import bring in", and `since` for "what did people tell us in this period". `updated_at` is the third timestamp: it is stamped on create, on every correction and on every translation, sentiment and emotion result (not on embeddings or topic assignment), so `updated_since` answers "what was created or changed since" — incremental extraction. Pair it with `sort: updated_at, order: asc`: each page is one index range, and a record that changes mid-traversal normally moves ahead of the cursor (returned again). A write that started before the cursor's position and commits after it still lands behind; the run-start watermark picks it up next run. The next run's `updated_since` is when the previous run *started*, minus an overlap — not the newest `updated_at` received, which skips a write that was still committing when the traversal read past its timestamp. It never returns a deleted record, since a delete leaves nothing to match; the full procedure, deletions included, is in the v3 API introduction. The workspace/dataset/pagination parameters (`workspaceId`, `datasetId`, `limit`, `cursor`) stay camelCase: they name nothing in the record. Output mirrors the Hub feedback-record shape and paginates with `meta.nextCursor`. `meta` also names the dataset that was searched, so an empty `data` array unambiguously means that dataset holds no matching records — a caller that let the dataset auto-resolve does not need a second call to find out which one it was: ```json theme={null} { "data": [ { "collected_at": "2026-04-21T10:00:00.000Z", "dataset_id": "clfd1234567890123456789012", "field_id": "q1", "field_type": "text", "id": "019fa338-f494-7384-b34e-01739783d280", "source_type": "survey", "submission_id": "…", "value_text": "Great support!" } ], "meta": { "datasetId": "clfd1234567890123456789012", "datasetName": "Support", "limit": 50, "nextCursor": null }, "requestId": "req_..." } ``` ### count\_feedback\_records Counts the feedback records matching a filter set, without fetching them — for "how many" questions that would otherwise mean paging through records. Read-only and idempotent. Takes the same filters as `list_feedback_records` (no `limit`/`cursor`, and no `sort`/`order` — the Hub's count endpoint does not accept ordering and they are rejected here), because the Hub documents its count endpoint as accepting the same query parameters as its list endpoint; both go through one mapper in `lib/operations.ts`, so a count always describes the same set as the equivalent list. Input: ```json theme={null} { "has_sentiment": false, "since": "2026-01-01T00:00:00Z", "source_type": ["survey", "review"], "user_id": "user_1", "workspaceId": "clxx1234567890123456789012" } ``` Output is the total and the dataset it came from — **no record content**, which is the point: a caller asking "how many" never pulls end-user text into its context to find out. ```json theme={null} { "data": { "count": 42, "dataset_id": "clfd1234567890123456789012", "dataset_name": "Support" }, "requestId": "req_..." } ``` ### get\_feedback\_record Gets one feedback record by its Hub UUID. Read-only and idempotent. The record must belong to a feedback dataset assigned to the workspace; otherwise the tool returns a generic authorization error and never reveals whether a record id exists in another tenant. Input: ```json theme={null} { "feedbackRecordId": "019fa338-f494-7384-b34e-01739783d280", "workspaceId": "clxx1234567890123456789012" } ``` ### create\_feedback\_record Creates a feedback record in a workspace's feedback dataset. Writes data and is not idempotent, and requires `feedbackRecords:write` (API keys need `write` or `manage`). The tenant is derived from the resolved feedback dataset and is never taken from the request body. `submission_id` is optional — a UUID is generated when omitted. Input: ```json theme={null} { "field_id": "note", "field_label": "Call summary", "field_type": "text", "source_type": "call_notes", "value_text": "Customer asked for SSO and a longer trial.", "workspaceId": "clxx1234567890123456789012" } ``` Output is the created feedback record (Hub shape) plus the MCP `requestId`. ### create\_feedback\_records Creates several feedback records in one call — the batch form of `create_feedback_record`, for imports. Writes data, is not idempotent, and requires `feedbackRecords:write`. Between 1 and 50 records per call. The Hub has no bulk-create endpoint (its only bulk write is the delete-by-user erasure path), so this fans out to one Hub create per record, in parallel. Two consequences are deliberate: * **Validation is all-or-nothing.** Every record is validated before any is written, so a malformed batch is rejected without leaving half of it stored. `invalid_params` names the offending index, e.g. `records.3.value_text`. * **Partial success is reported, not hidden.** If the Hub rejects some records — a duplicate `(submission_id, field_id)`, say — the created ones are returned and `meta.failures` accounts for the rest by index, so only those need retrying. If *nothing* could be created, the upstream failure is returned as the response instead, because an empty success would read as "there was nothing to do". The 50-record cap is an amplification bound as much as a payload one: one authorized request must not become an unbounded burst of upstream writes. > [!WARNING] > > **A batch is not a submission.** Each record without a `submission_id` gets its own generated one, exactly > as in the single-record case — so several answers that belong to the same submission (a survey response, or > a call with both a rating and a comment) must carry the *same* `submission_id`, set by the caller. Omit it > and they are stored as unrelated submissions, which nothing downstream can distinguish from the intended > shape. Input: ```json theme={null} { "records": [ { "field_id": "note", "field_type": "text", "source_type": "call_notes", "value_text": "Asked for SSO." }, { "field_id": "score", "field_type": "nps", "source_type": "call_notes", "value_number": 9 } ], "workspaceId": "clxx1234567890123456789012" } ``` Output: ```json theme={null} { "data": [{ "dataset_id": "clfd…", "id": "019fa338-…", "value_text": "Asked for SSO." }], "meta": { "created": 1, "datasetId": "clfd1234567890123456789012", "datasetName": "Support", "failed": 1, "failures": [{ "detail": "duplicate record for (tenant_id, submission_id, field_id)", "index": 1 }], "requested": 2 }, "requestId": "req_..." } ``` Per-record failure text goes through the same relay rules as a whole-request failure: a Hub 4xx explains itself, anything else becomes a fixed message. Each record actually created produces its own `created` audit event — N creations are N events, not one summary. ### update\_feedback\_record Corrects the value of an existing feedback record. Writes data, is annotated `destructiveHint: true` (it overwrites a stored value; the previous one survives only in the audit log), and requires `feedbackRecords:write` (API keys need `write` or `manage`). Only the fields sent are changed; at least one is required. For API keys, the same dataset-exclusivity rule applies as for deletes: the key may update only a record in a dataset assigned to exactly one workspace, where its permission unambiguously covers every record present (ENG-2189). A shared dataset returns 403; an integration needing to update records in both workspaces should use a workspace-scoped key per workspace. Session, OAuth and MCP-person principals are unaffected and authorize through their organization role instead. Updatable — the Hub's own mutable set: `value_text`, `value_number`, `value_boolean`, `value_date`, `value_id`, `user_id`, `language`, `metadata`. The schema is `.pick()`ed from the create fields, so bounds can't drift between creating and correcting a record. The `value_*` field being set must be one the record's `field_type` accepts — the same table `create` enforces (`text` takes `value_text`, `nps`/`rating`/`number` take `value_number`, `categorical` takes `value_text` and/or `value_id`, and so on). Because `field_type` is immutable it is not part of the patch, so this is checked against the *stored* record and therefore reported after the ownership check, as a 422 naming the offending field. Without it a patch could assemble what `create` rejects: putting `value_number` on a `text` record would leave both a text and a number set, with nothing to say which one the record means. The Hub does not enforce this itself. **Not** updatable: a record's provenance — `source_type`, `source_id`, `source_name`, `field_id`, `field_type`, `field_label`, `field_group_*`, `submission_id`, `collected_at`. Correcting those means deleting the record and creating it again. The derived enrichment fields (`sentiment`, `sentiment_score`, `emotions`, `value_text_translated`, `translation_lang_key`) are not accepted from callers either — they are the Hub's to compute. `metadata` is the one field that is **replaced, not merged** — the Hub assigns it wholesale, so adding a key means sending the existing ones too. Everything else is left untouched when omitted. Ownership is verified before the update, the same way as for get and delete: `PATCH /{id}` is another Hub endpoint that derives the tenant from the stored record. A record deleted in the window between that check and the write returns the same generic authorization error, not a 502 — nothing was updated and the service is fine. Input: ```json theme={null} { "feedbackRecordId": "019fa338-f494-7384-b34e-01739783d280", "value_text": "Actually the export works fine, it was the filter that confused me", "workspaceId": "clxx1234567890123456789012" } ``` Output is the updated record. > [!WARNING] > > **Editing the text resets what was derived from it.** Per the Hub's contract, changing `value_text` clears > `sentiment`, `sentiment_score`, `emotions`, `value_text_translated` and `translation_lang_key` and queues > re-enrichment; changing `language` re-queues the translation pair only. The response reflects the > **cleared** state, so those fields being absent right after an update means "being recomputed", not "none". > Changing `value_text` (or a field label) also re-queues the embedding, so semantic search catches up > asynchronously — and clearing a record's text removes its embedding, making it unsearchable. ### delete\_feedback\_record Permanently deletes one feedback record. Writes data, is not idempotent, is annotated `destructiveHint: true`, and requires `feedbackRecords:write` (API keys need `manage`). The record and its derived embedding are removed with no soft delete, so this cannot be undone — the audit log entry keeps the deleted record as its `oldObject` and is the only remaining trace. For API keys, the dataset must be assigned to exactly one workspace — the caller's — because a key's workspace permission can only identify whose records these are when the dataset is not shared (ENG-2189). A shared dataset returns 403 with an explanation; an integration needing to delete from both workspaces should use a workspace-scoped key per workspace. Session, OAuth and MCP-person principals are unaffected and authorize through their organization role instead. Ownership is verified before the delete: the record must belong to a feedback dataset assigned to the workspace, and a record in another tenant is refused with the same generic authorization error as an unknown id, without deleting anything. Single-record only — there is no bulk delete tool. Input: ```json theme={null} { "feedbackRecordId": "019fa338-f494-7384-b34e-01739783d280", "workspaceId": "clxx1234567890123456789012" } ``` Returns `204 No Content` on success (the tool result carries only the `requestId`). ### search\_feedback\_records Searches a workspace's feedback dataset semantically: the query is embedded and compared to record embeddings by cosine similarity, so it matches meaning rather than keywords. Read-only and idempotent. Input: ```json theme={null} { "cursor": "opaque-cursor-from-previous-response", "limit": 10, "minScore": 0.5, "query": "checkout is confusing", "workspaceId": "clxx1234567890123456789012" } ``` Output is scored matches, best first — record ids with the embedded text, not full records. Pass a `feedback_record_id` to `get_feedback_record` for the rest of a record: ```json theme={null} { "data": [ { "feedback_record_id": "019fa338-f494-7384-b34e-01739783d280", "field_label": "What can we improve?", "score": 0.82, "value_text": "I couldn't figure out how to pay" } ], "meta": { "datasetId": "clfd1234567890123456789012", "datasetName": "Support", "limit": 10, "minScore": 0.5, "nextCursor": null }, "requestId": "req_..." } ``` ### find\_similar\_feedback\_records Finds the records most similar to a given one, by embedding distance — useful for gauging how widely a piece of feedback is echoed. Read-only and idempotent. Same output shape as `search_feedback_records`; the anchor record is excluded from its own results. Input: ```json theme={null} { "feedbackRecordId": "019fa338-f494-7384-b34e-01739783d280", "limit": 10, "minScore": 0.5, "workspaceId": "clxx1234567890123456789012" } ``` Ownership of the anchor record is verified before any neighbour is fetched (see [Feedback Records And The Hub](#feedback-records-and-the-hub)). > [!NOTE] > > Both search tools need embeddings, which are optional in the Hub. Without `EMBEDDING_PROVIDER` and > `EMBEDDING_MODEL` configured on **both** the Hub API and the Hub worker they return `503` with that > instruction as the detail. Embedding is also asynchronous and only covers records that have text, so a > record created moments ago is not searchable yet; `find_similar_feedback_records` reports that as a `409` > rather than an empty result, distinguishing "still being embedded, retry" from "no text, so there is no > embedding to wait for" — the latter also covers text cleared by an update. `limit` (1–100, default 10) and `minScore` (0–1, default 0.5) are validated by Formbricks rather than passed straight through: the Hub silently coerces out-of-range values to its own defaults, which would return something other than what was asked for. The default `minScore` of 0.5 is Formbricks' own — the Hub defaults to 0.7, which is strict enough that a fair paraphrase often falls just below it. ## Relationship to V3 Workflows API Like the survey tools, workflow tools run no custom database queries — each calls the shared, framework-agnostic `@formbricks/workflows` handlers used by the v3 REST routes: | MCP Tool | REST Contract | | - | - | | `list_workflows` | `GET /api/v3/workflows` | | `get_workflow` | `GET /api/v3/workflows/{workflowId}` | | `list_workflow_runs` | `GET /api/v3/workflows/runs` | | `get_workflow_run` | `GET /api/v3/workflows/runs/{runId}` | | `test_workflow` | `POST /api/v3/workflows/{workflowId}/test` | | `create_workflow` | `POST /api/v3/workflows` | | `patch_workflow` | `PATCH /api/v3/workflows/{workflowId}` | | `duplicate_workflow` | `POST /api/v3/workflows/{workflowId}/duplicate` | | `delete_workflow` | `DELETE /api/v3/workflows/{workflowId}` | | `enable_workflow` | `POST /api/v3/workflows/{workflowId}/enable` | | `disable_workflow` | `POST /api/v3/workflows/{workflowId}/disable` | | `archive_workflow` | `POST /api/v3/workflows/{workflowId}/archive` | | `unarchive_workflow` | `POST /api/v3/workflows/{workflowId}/unarchive` | ## Relationship to V3 Surveys API The MCP server does not run custom survey database queries. Each tool calls the shared server-only v3 survey operations used by the REST routes: | MCP Tool | REST Contract | | - | - | | `list_surveys` | `GET /api/v3/surveys` | | `get_survey` | `GET /api/v3/surveys/{surveyId}` | | `create_survey` | `POST /api/v3/surveys` | | `validate_survey` | `POST /api/v3/surveys/validate` | | `patch_survey` | `PATCH /api/v3/surveys/{surveyId}` | | `edit_survey_blocks` | `PATCH /api/v3/surveys/{surveyId}/blocks` | | `set_survey_block_order` | `PUT /api/v3/surveys/{surveyId}/blocks/order` | | `delete_survey` | `DELETE /api/v3/surveys/{surveyId}` | | `get_workspace_custom_css` | `GET /api/v3/workspaces/{workspaceId}/custom-css` | | `patch_workspace_custom_css` | `PATCH /api/v3/workspaces/{workspaceId}/custom-css` | When the v3 OpenAPI contract changes, update the MCP schemas and this page together. The v3 spec is hand-authored under `docs/api-v3-reference/src/` and bundled to `docs/api-v3-reference/openapi.yml`. For resources whose schemas are generated (Responses today), the tools' output schemas follow the contract through `pnpm api:v3:sync`; their input schemas and this page are still updated by hand. See [API v3 Schema Generation](/docs/development/technical-handbook/api-v3-schema-generation). ## Feedback Records And The Hub Feedback-record tools do not map to a v3 REST route. They call the shared server-only Hub service (`@/modules/hub/service`) — the same client the Unify Feedback UI uses — and enforce the same `feedbackDirectories` Enterprise entitlement. A feedback record lives in the Formbricks Hub, addressed by an opaque tenant id. Every tool resolves that tenant server-side: it authorizes the caller's access to `workspaceId`, checks the `feedbackDirectories` license, then maps the workspace to its assigned feedback dataset — the `FeedbackDirectory` id **is** the Hub tenant id, and it is surfaced to callers as `dataset_id`. Assignment is a join table, but the application enforces at most one *non-archived* directory per workspace, so in practice `datasetId` can be omitted and the single active dataset is used. It becomes required only if a workspace somehow has several active directories, in which case the tools return `400` rather than guessing. A tenant id is never accepted from tool input. Three Hub endpoints — get, delete, and similar — take a bare record id and derive the tenant from the stored record, delegating record-level authorization to the product. So `get_feedback_record`, `delete_feedback_record` and `find_similar_feedback_records` all retrieve the record first and verify its tenant — the named dataset when one was given, otherwise any dataset the workspace owns — before acting. A foreign record and an unknown record produce the same generic authorization error, so record ids cannot be probed across tenants. `search_feedback_records` instead has the resolved tenant injected into the Hub query, like `create_feedback_record`. ## Limitations * OAuth is user-delegated only. Machine-to-machine client credentials for MCP are not supported. * OAuth access tokens must be JWTs audience-bound to `/api/mcp`; opaque MCP access token introspection is not accepted by the MCP route. * API-key authentication remains supported for compatibility and fallback use. * The MCP server exposes only the survey, workflow, response and feedback-record operations listed on this page. * Survey and workflow tool coverage depends on the current v3 Surveys and Workflows REST endpoint coverage; feedback-record tool coverage depends on the Hub feedback-records API. * `enable_workflow` makes a workflow live and can trigger email sending; treat it as a high-impact mutation when granting agents write access. * `create_workflow` requires a complete workflow `definition` (schema version, trigger, entry node); it is created as a draft and only `enable_workflow` can make it live. * Feedback-record tools require the `feedbackDirectories` Enterprise entitlement and a feedback directory assigned to the workspace; without either they return 403 / 422. * A feedback record's **provenance** is immutable: `update_feedback_record` changes values, users, language and metadata, but not which source, question or submission a record belongs to, nor when it was collected. The derived enrichment fields are the Hub's to compute and are never accepted from callers. * `delete_feedback_record` deletes one record at a time. The Hub's bulk and delete-by-user endpoints are deliberately not exposed: they are erasure operations whose blast radius does not belong on an agent surface. There is deliberately no batch *delete* to match `create_feedback_records`. * Counting and filtering cover the Hub's own filter set only. There is no aggregation by sentiment or emotion, and semantic search cannot be narrowed by source or date — the Hub's search endpoint takes only a query and a tenant. Those need Hub-side support first. * The search tools require an embedding model configured on the Hub API **and** the Hub worker; without one they return 503. Embedding is asynchronous and covers only records with text. * `outputSchema` is declared on the response tools only. The survey, workflow and feedback-record tools still advertise no result shape, so a client has to infer theirs from an example. * The response tools cover the v3 operations and nothing more: there is no tool that adds or removes a single tag, because `PATCH` replaces the tag set wholesale and such a tool would be a read-modify-write wrapper with its own race rather than an operation. * `create_survey` creates link surveys only. In-app survey creation and distribution settings are not part of the current v3 create operation. * `edit_survey_blocks` and `set_survey_block_order` operate on whole blocks. There is no element-level operation: elements travel inside the block payload, and going finer would reintroduce the same resend problem one level down. * Ordering is validated as a delta on the **patch family only**: a change may not *introduce* a `#recall:` that points forwards, a logic condition reading a later block, or a `requireAnswer` targeting an earlier one (`misordered_reference`). Violations a survey already contains are left alone, so an existing survey never becomes unpatchable — enforcing the full set would repeat the ENG-3070 failure. `create_survey` is deliberately not covered: tightening it would reject payloads that are valid today, which needs its own versioned rollout. * `stored_survey_invalid` (422) means the *stored* survey cannot be read as a v3 document (legacy questions, no v3 block list, a shape that does not parse); the reported paths are into the survey, not the request — repair it in the editor. A survey that reads fine but already fails validation stays patchable: issues it already had are not refused, only issues a patch newly introduces (ENG-3975). Publishing a draft is the exception — it is refused as `stored_survey_invalid` until the survey passes. * `patch_survey` follows the v3 PATCH contract: top-level partial document updates only, no JSON Patch, and no nested deep merge. Provided top-level objects and arrays replace their whole subtree and can remove omitted nested entries. * `validate_survey` validates payload shape and references; it does not create languages, survey versions, or surveys. * Query-string credentials are rejected; use headers for API keys. * Large request bodies are rejected before the MCP handler using the same body-size policy as v3 APIs. * Tool arguments are strict: undeclared keys are rejected rather than ignored (see [Tool Arguments](#tool-arguments)). * Resources and prompts are not exposed — the server registers tools only, so there is no MCP resource for the survey document contract yet. * `subscriptions/listen` is refused (`maxSubscriptions: 0`). The 2026-07-28 revision replaced the GET SSE endpoint with a long-lived POST-response stream, but with no resources registered and no list-changed notifications emitted, such a stream could never deliver anything — it would just hold a connection. A client that opens one gets `Subscription limit reached`; the list endpoints remain the way to see current tools, prompts and resources. ## Implementation Files * `apps/web/app/api/mcp/route.ts` * `apps/web/modules/mcp/auth.ts` * `apps/web/modules/mcp/server.ts` * `apps/web/modules/mcp/tools/surveys.ts` * `apps/web/modules/mcp/tools/workspaces.ts` (workspace discovery and the workspace custom CSS tools) * `apps/web/modules/mcp/tools/feedback-records.ts` * `apps/web/modules/mcp/tools/schemas.ts` * `apps/web/modules/mcp/tools/workflows.ts` * `apps/web/modules/mcp/tools/workflow-schemas.ts` * `apps/web/app/api/v3/surveys/lib/operations.ts` * `apps/web/app/api/v3/workspaces/lib/custom-css.ts` (workspace custom CSS operations) * `apps/web/app/api/v3/surveys/blocks.ts` (pure block op-application and reorder logic) * `apps/web/app/api/v3/workflows/lib/context.ts` (adapter to the `@formbricks/workflows` handlers) * `apps/web/app/api/v3/feedbackRecords/lib/operations.ts` * `apps/web/app/api/v3/feedbackRecords/lib/access.ts` (tenant resolution + per-record ownership guard) * `apps/web/app/api/v3/feedbackRecords/lib/errors.ts` (Hub error → v3 problem mapping) # Solution Overview Source: https://formbricks.com/docs/development/technical-handbook/overview High-level architecture and technical details of the Formbricks platform The Formbricks platform is designed with a modern, unified architecture that prioritizes developer experience and performance. This overview outlines the system's architecture, key technology choices, and how different components interact. ## System Architecture Formbricks uses a unified architecture with Next.js at its core, serving both the frontend and backend capabilities. Here's an interactive overview of the system: ```mermaid theme={null} graph TD subgraph Users MU[Mobile User] WU[Web User] LSU[Link Survey User] AD[Admin] end subgraph Client Applications MA[Mobile App\niOS/Android SDK] SW[Survey Widget\nJavaScript SDK] end subgraph Formbricks Platform NS[Next.js Server\nAPI Routes + SSR\nBusiness Logic] subgraph Storage DB[(PostgreSQL\nSurveys & Data)] RC[(Redis\nPerformance Cache)] FS[File Storage\nUploads] end end MU --> |Uses| MA WU --> |Interacts| SW LSU --> |Direct Access| NS AD --> |Manages| NS MA --> |REST API| NS SW --> |REST API| NS NS --> |Cache Data| RC NS --> |Read/Write| DB NS --> |File Upload| FS style DB fill:#00C4B8,color:#ffffff style RC fill:#00C4B8,color:#ffffff style FS fill:#00C4B8,color:#ffffff style NS fill:#0D9373,color:#ffffff style MA fill:#07C983,color:#ffffff style SW fill:#07C983,color:#ffffff classDef user fill:#666,color:#fff,stroke:#333 class MU,WU,LSU,AD user ``` ### Key Components #### Users * **Mobile Users**: Access surveys through native mobile applications * **Web Users**: Interact with embedded survey widgets on websites * **Link Survey Users**: Access surveys directly through shared URLs * **Admins**: Manage surveys and view responses through the web dashboard #### Client Applications * **Survey Widget**: A JavaScript component that can be embedded in web applications * **Mobile Application**: Native iOS/Android apps that integrate with the Formbricks SDK * **Web Dashboard**: The admin interface for managing surveys and viewing responses #### Core Platform * **Next.js Server**: The central component that handles: * Frontend rendering and SSR * API routes for client communication * Business logic implementation * Survey display and response collection #### Data Storage * **PostgreSQL Database**: Primary data store for: * Survey definitions * Response data * User and organization information * **Redis Cache**: Performance optimization through: * Caching frequently accessed data * Reducing database load * Improving response times ### Communication Flow 1. **Client Interaction** * Web users interact with embedded survey widgets * Mobile users engage with surveys through native apps * Link survey users access surveys directly via URLs * Admins manage the system through the web dashboard 2. **Data Flow** * Clients communicate with the Next.js server via REST APIs * Survey data is fetched and responses are submitted over HTTPS * The server processes requests and interacts with the database using Prisma ORM * Frequently accessed data is cached in Redis for performance 3. **Data Storage** * Persistent data is stored in PostgreSQL * Frequently accessed data is cached in Redis * File attachments are handled through the configured storage provider ## Technology Stack * **Frontend**: React, TailwindCSS, Radix UI * **Backend**: Next.js App Router with API Routes * **Database**: PostgreSQL with Prisma ORM * **Caching**: Redis * **API**: REST with OpenAPI specification * **Testing**: Playwright for E2E, Vitest for unit tests # Tenant Separation Source: https://formbricks.com/docs/development/technical-handbook/tenant-separation How Formbricks handles tenant separation on Formbricks Cloud Formbricks Cloud is designed to support multiple tenants, each with their own set of surveys and data. This page describes the different ways to configure and use Formbricks for multi-tenancy. > [!NOTE] > > This documentation only applies to Formbricks Cloud instances. On-premise deployments handle tenant separation differently based on your specific setup and requirements. ## Multi-Tenancy in Formbricks Cloud Formbricks Cloud is architected as a true multi-tenant system where each organization contains one or more isolated Workspaces while sharing the underlying infrastructure. This approach allows multiple organizations to use the platform independently without visibility into each other's data. ### Organizational Structure ```mermaid theme={null} graph TD Organization[Organization] --> Workspace1[Workspace 1] Organization --> Workspace2[Workspace 2] Organization --> WorkspaceN[Workspace n] Workspace1 --> Survey1[Surveys] Workspace1 --> Contact1[Contacts] Workspace1 --> Action1[Action Classes] Workspace1 --> ApiKeyScope1[API Key Scopes] Workspace1 --> Webhook1[Webhooks] Workspace1 --> Integration1[Integrations] Workspace1 --> Segment1[Segments] Workspace2 --> Survey2[Surveys] Workspace2 --> Contact2[Contacts] Workspace2 --> Action2[Action Classes] Workspace2 --> ApiKeyScope2[API Key Scopes] Workspace2 --> Webhook2[Webhooks] Workspace2 --> Integration2[Integrations] Workspace2 --> Segment2[Segments] ``` The multi-tenant architecture in Formbricks Cloud is built around three key levels of isolation: ### 1. Organization-Level Isolation * Each tenant is represented by an Organization entity * Organizations are completely separated from each other * Users can be members of multiple organizations simultaneously * All resources and data belong exclusively to a single organization * Role-based access control (RBAC) with specific roles: * Owner: Full access to all organization resources * Manager: Can manage members and billing * Member: Basic access to organization resources * Billing: Access to billing information only * Billing and subscription management occurs at the organization level ### 2. Workspace-Level Isolation Within each organization, further isolation is maintained through Workspaces: * Organizations can have multiple Workspaces to separate different applications or product lines * Complete separation of resources between Workspaces: * Surveys and responses * Contacts and attributes * Action classes and triggers * API key scopes and integrations * Webhooks and notifications * Segments and targeting rules * Workspace-specific configuration, branding, and style settings * Language settings and customizations are Workspace-specific ### 3. Team-Based Access Isolation Team access is scoped per Workspace: * Teams can be granted access to specific Workspaces via Workspace-team mapping * Permissions are applied at the Workspace level for finer-grained access control * Users can collaborate in one Workspace without being granted access to all organization resources ## Data Security in the Multi-Tenant Model Formbricks ensures data security in its multi-tenant Workspace model through: * **Database Layer Isolation**: * Foreign key constraints enforce data isolation * Each resource is scoped to its organization * Cascading deletes maintain referential integrity * **Authentication Boundaries**: * Role-based access control (RBAC) * Session management per organization * Multi-factor authentication support * **API Access Control**: * API keys are scoped to specific Workspaces * Rate limiting per organization * Request validation and sanitization * **Resource Quotas**: * Organization-level limits based on billing plan This multi-layered approach to tenant separation ensures that organizations can safely use Formbricks Cloud with complete data privacy and isolation from other tenants. # Accessibility Source: https://formbricks.com/docs/platform/accessibility How the Formbricks survey UI supports respondents with disabilities, which standards we measure against, and where we currently fall short. Formbricks is used to ask people questions. A survey that some people cannot answer is a survey that returns incomplete data, so accessibility is not a compliance exercise for us — it is part of the product working correctly. This page describes the accessibility of the **public survey UI**: the interface a respondent sees when they open a link survey or are shown a website or in-app survey. It covers what already works, what does not, and how to reach us. > [!NOTE] > > This page covers the respondent-facing survey UI only. The Formbricks application that survey creators use > to build surveys, and the self-hosting and administration interfaces, have not been assessed to the same > standard and are not described here. *** ## Standards We Measure Against Formbricks assesses the public survey UI against two standards: | Standard | Level assessed | | - | - | | Web Content Accessibility Guidelines (WCAG) 2.0 | Level A and Level AA | | Revised Section 508 standards (published 18 January 2017, corrected 22 January 2018) | Chapters 3, 5 and 6 | Our assessment is published as a Voluntary Product Accessibility Template (VPAT) using the **VPAT 2.5Rev, Revised Section 508 Edition** format. The most recent report was completed on **9 August 2026**. To request the full report, ask in [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). *** ## Conformance Status The public survey UI **partially conforms** to WCAG 2.0 Level AA. Partial conformance means that most of the standard is met, but some content does not fully conform. The known gaps are listed under [Known Limitations](#known-limitations) below. We publish them rather than summarising them away, because a procurement team or an individual respondent needs to know what will not work before they rely on it, not after. > [!NOTE] > > The 9 August 2026 report and the current product have since diverged, in both directions. Three gaps the > report records as *Partially Supports* — page titles, the language switcher, and semantic headings — were > fixed in Formbricks 5.4; those entries are marked **Fixed in 5.4** below. Image alt text and the top-level > heading on website and in-app surveys followed in 6.1, marked **Fixed in 6.1**. Two areas run the other way: > the report records them as supported, but a later review of the code found limitations we now publish below, > marked **Not in the 9 August 2026 report**. If you are assessing a version older than 5.4, the report remains > authoritative for the entries marked as fixed here; for the two areas it records as supported, this page is > the more accurate description. *** ## Accessibility Features Everything in this table was assessed as supported in the most recent report. Where a row carries an exception, it names it and links to the entry describing it. | Area | What the survey UI does | WCAG 2.0 criterion | | - | - | - | | Keyboard operation | Every question type, navigation button, and control can be operated with a keyboard alone. Keyboard focus is never trapped in a component — it can always be moved away using standard keys. | 2.1.1, 2.1.2 | | Visible focus | The element that currently has keyboard focus is shown with a visible focus indicator. | 2.4.7 | | Focus order | Focus moves through the survey in an order that preserves meaning and operability. | 2.4.3 | | Contrast | Text and images of text in the default survey theme meet the minimum contrast ratio. A survey creator can override every colour, and Formbricks does not check the contrast of a custom theme. | 1.4.3 | | Resizing text | Text can be resized up to 200% without assistive technology, and without loss of content or functionality. | 1.4.4 | | No time limits | There is no time limit on completing a survey, except when a creator enables [Auto close](#auto-close-countdown), which is off by default. | 2.2.1 | | No auto-playing media | No audio or video ever plays on its own. The [Auto close](#auto-close-countdown) countdown is the only thing that animates by itself. | 2.2.2 | | Error identification | When an answer is rejected, the error is identified and described to the respondent in text. | 3.3.1 | | Error suggestion | Where we know how an input should be corrected, the survey suggests the correction. | 3.3.3 | | Labels and instructions | Every input field has a descriptive label. | 3.3.2 | | Review and correction | A **Back** button is shown by default, so respondents can return to an earlier question, review their answer, and change it before submitting. | 3.3.4 | | Not relying on colour alone | Instructions are written in plain language, and error messages carry both a visual cue and a text cue. | 1.4.1 | *** ## Known Limitations The following do not fully conform. Each entry states what a respondent experiences and what a survey creator can do about it. Three markers say where an entry differs from the 9 August 2026 report. **Fixed in 5.4** means the gap was closed in Formbricks 5.4, and **Fixed in 6.1** that it was closed in 6.1; either way the workaround applies only to older versions. **Not in the 9 August 2026 report** means the report records that criterion as supported, and a later review of the code found otherwise. ### Image Text Alternatives **Affected criterion:** 1.1.1 — **Not in the 9 August 2026 report**, **Fixed in 6.1** Formbricks lets a survey creator add an image to a question or to an ending card. As assessed, those images were announced only as "Image", with nothing about what they show, and a survey creator had no way to change that. Since 6.1, question images, ending card images and each Picture Selection option take alt text: select the **Alt** button on the image in the editor. It is translated per survey language like the headline. The text is read out as the image's alternative. An image whose alt text is left empty is marked decorative, so a screen reader skips it instead of announcing a meaningless "Image"; a Picture Selection option without alt text is still named by position — "Option 1", "Option 2" — so a respondent can tell the options apart. The field is optional, so whether an informative image is described is up to the survey creator. The welcome card's logo and video both carry a fixed text alternative. Uploaded file names are never used as text alternatives, because a file name can carry personal data. **Workaround for versions before 6.1:** Without the field, treat question and ending images as illustration. Put anything a respondent needs in order to answer into the headline or the description, both of which are always read out. For a Picture Selection question, describe the options in the headline or description as well — for example "Option 1 is the blue design, option 2 the green one" — wherever the image carries the meaning. ### Embedded Third-Party Video **Affected criteria:** 1.2.1, 1.2.2, 1.2.3, 1.2.5 Formbricks lets survey creators embed a video from YouTube, Vimeo, or Loom into a question. Formbricks provides no way to upload a transcript, add captions, or supply an audio description or text alternative for that video. A respondent who is deaf, hard of hearing, blind, or has low vision may not be able to access information that is only presented in the video. Adding captions on the hosting platform does not fully close the gap either, because Formbricks reduces the embedded player's controls: | Platform | What the embedded player hides | | - | - | | YouTube | The whole control bar — so no captions button, and no visible play or pause control | | Vimeo | The captions button and the transcript panel | | Loom | The share button, the top bar, and the title. Playback controls, including captions, stay reachable | Every video carries an **Open in new tab** control in its bottom-right corner. It is reachable by keyboard and becomes visible when it has focus, and it opens the video in the platform's own player, where captions, transcripts, and full playback controls are available. For a YouTube or Vimeo video, that is currently the only route a respondent has to turn captions on. **Workaround:** Repeat the essential information as text in the question headline or description — that is the part that always works. Do not put information in a video that a respondent needs in order to answer the question, unless that information also appears as text. Add captions and a transcript on the hosting platform as well: for YouTube and Vimeo they will not be reachable from the embedded player, but they will be there for a respondent who opens the video in its own tab. ### Auto-Close Countdown **Affected criteria:** 2.2.1, 2.2.2 — **Not in the 9 August 2026 report.** Applies only when a survey creator enables **Auto close**. Website and in-app surveys have an optional **Auto close** setting that dismisses an unanswered survey prompt after a set number of seconds. It is off by default, it is not available on link surveys, and it applies only to the survey's first screen. With it off, nothing described here happens: there is no countdown, no automatic animation, and no time limit anywhere in the survey. With it on, the first screen carries a time limit — a respondent who needs longer to read the prompt than the configured number of seconds loses the survey. While the countdown runs it is shown as a shrinking progress bar, which animates for as long as the creator configured, and there is no control to pause, stop, or hide it. Formbricks does not cap the configured value, so that animation can run well beyond the five seconds after which an automatic animation needs a pause control. The countdown is cancelled by the respondent's first interaction of any kind — moving the pointer over the survey, clicking, tapping, or pressing a key — and once cancelled it does not restart. A respondent who does anything at all keeps the survey. The respondent most likely to lose it is one who is reading or listening before touching anything, which includes screen reader users. Once past the first screen there is no time limit on answering. **Workaround:** Leave **Auto close** off, which is the default. If you need it, set it generously — long enough that a respondent reading at their own pace is not cut off. ### Page Titles and Survey Instructions **Affected criterion:** 2.4.2 — **Fixed in 5.4** As assessed, surveys carried no form title and survey instructions were not repeated after the welcome card, so a respondent using a screen reader was not given a clear description of the page they were on. A link survey now sets its document title per step, appending the respondent's position — "Page 3 of 7" — to the survey's own title, localized in the survey's language. Where a survey has instructions, they are kept reachable on every page instead of disappearing once the respondent advances past the welcome card. The per-step document title applies to link surveys, which own the page they are shown on. A website or in-app survey is embedded in a page belonging to the site that shows it, and does not change that page's title. **Workaround for versions before 5.4:** Write question headlines that make sense on their own, without depending on a title or on instructions given earlier in the survey. ### Current Language Not Identified in the Language Switcher **Affected criterion:** 3.1.1 — **Fixed in 5.4** As assessed, the language switcher was an unlabelled globe: it listed the available languages but gave no indication of which one was active, so neither a sighted nor a screen-reader respondent could tell what language the survey was being presented in. The switcher now names the active language, in that language rather than in translation — "Deutsch", not "German" — both visibly and in its accessible name. Each option in the list carries its own language tag, so a screen reader pronounces every language name using that language's rules. **Workaround for versions before 5.4:** For link surveys, the `lang` URL parameter sends a respondent straight to the correct language, so they do not need to use the switcher. See [Multi-language Surveys](/docs/surveys/general-features/multi-language-surveys). ### Semantic Headings **Affected criterion:** 2.4.6 — **Fixed in 5.4**; the top-level heading on website and in-app surveys is **Fixed in 6.1**. Website and in-app surveys use a generic top-level heading rather than the survey's name. As assessed, the survey UI used no semantic heading elements, so a respondent using a screen reader could not navigate the survey by heading and question headlines were not exposed as headings. Card headlines — the welcome card, each question prompt, and the ending — are now second-level headings on every survey, so a respondent can navigate between them by heading. Every survey has a single top-level heading above them. On a link survey it is the survey's name. A website or in-app survey is delivered by the JavaScript widget, which loads the survey from an endpoint that deliberately withholds survey names, so that a survey's name is not readable by anyone who can reach that endpoint. The widget has no name to use, so it uses the generic label "Survey Dialog" instead: * **Shown as a pop-up** (the widget's default): "Survey Dialog" names the dialog and is its top-level heading. * **Rendered inline** into a container on the page: "Survey Dialog" is the top-level heading and names the form landmark, so the landmark is always named. Either way the card headings always sit under a top-level heading, but on a website or in-app survey that heading does not name the survey being answered. Before 6.1, a website or in-app survey has the card headings only, with no top-level heading above them. **Workaround for versions before 5.4, and for website and in-app surveys:** Keeping surveys short and putting one question on each screen reduces the amount of navigation a respondent has to do. Repeating the survey's purpose in the first question's headline gives a respondent the context that a heading naming the survey would otherwise carry. ### Language of Parts **Affected criterion:** 3.1.2 Formbricks declares the survey's language for the survey as a whole, and only when the survey has languages configured. Where a survey uses the multi-language feature, its root element carries a `lang` attribute resolved from the active language, updated when the respondent uses the language switcher — so an embedded survey shown in a language other than its host page's is still announced correctly, without Formbricks altering the page it is embedded in. Link surveys additionally set `lang` and `dir` on the page's `` element, so right-to-left languages read in the right direction. A survey that does not use the multi-language feature has no configured language for Formbricks to resolve from, so it declares no language of its own. It inherits whatever the surrounding page declares — the respondent's app locale for a link survey, or the host site's `lang` for an embedded one. A survey written in one language and opened where the page declares another is then announced using the wrong pronunciation rules. The workaround is to enable the multi-language feature and set the survey's language explicitly, even for a survey that only ever needs one. What a survey creator cannot do is mark up an individual passage. There is no way to set a language on a single question, description, label, or choice option, and the language switcher's own options are the only individually tagged text in the survey. So where one screen mixes languages — an English question with an untranslated choice option, or a term left in its original language — the part in the other language is not programmatically identified, and a screen reader may pronounce it using the wrong language rules. **Workaround:** Keep every part of a question in one language, and use the multi-language feature to offer the whole survey in each language rather than mixing languages inside a single question. *** ## Compatibility The survey UI is built as a standard web application. It requires no plugin, no extension, and no separate accessible version, and it targets current versions of Chrome, Edge, Firefox, and Safari on desktop and on mobile. Our automated browser tests run on Chromium only, so the other engines are a design target rather than a tested guarantee. ### How the Assessment Was Carried Out The most recent evaluation combined automated and manual testing: * **IBM Equal Access Accessibility Checker** — automated rule-based scanning * **ANDI (Accessible Name & Description Inspector)** — inspection of accessible names, descriptions, and roles * **Manual testing** — keyboard-only operation, focus order, and visual inspection ### Assistive Technology We have **not** formally tested the survey UI against specific named combinations of assistive technology and browser — for example a particular screen reader paired with a particular browser version. We do not claim support for combinations we have not evidenced. If you use a specific assistive technology and hit a barrier in a Formbricks survey, we want to hear about it. See [Contact](#contact) below. *** ## Requesting This Documentation in Another Format This page and the full accessibility report are available in alternate formats on request, at no charge. If the format here does not work for you, tell us which format you need and we will provide it. See [Contact](#contact) below. *** ## Contact For accessibility questions about Formbricks, to request the full accessibility report, to ask for this documentation in another format, or to report an accessibility barrier in the survey UI, reach us in [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). If you are a **survey respondent** and you cannot complete a survey that someone has sent you, contact the organisation that sent you the survey — they own the survey content and can offer you another way to respond. You are also welcome to raise it with us so we can fix the underlying barrier. *** ## Guidance for Survey Creators Formbricks handles the parts of accessibility that belong to the survey UI. The content you put into a survey is yours, and it decides whether the finished survey is usable. The following practices make a measurable difference. **Write question headlines that stand on their own.** A respondent using a screen reader may hear the headline without the surrounding context. "How satisfied were you with the onboarding call?" works; "And this one?" does not. **Describe every image that carries information.** Select the **Alt** button on a question image, an ending card image, or each Picture Selection option, and translate the text like the headline. Say what the image shows that matters for the answer — "Bar chart: sign-ups doubled from May to June", not "chart.png". Leave the field empty only for an image that is pure decoration. Before 6.1, put that information in the headline or the description instead. See [Image Text Alternatives](#image-text-alternatives) above. **Do not convey meaning with colour alone.** If a rating scale, an option, or an instruction depends on a respondent seeing red versus green, add a label, a number, or a word that carries the same meaning. **Caption your videos on the hosting platform, and summarise them as text.** See [Embedded Third-Party Video](#embedded-third-party-video) above. **Set the survey language correctly.** Choose the right default language and add translations for every language you send the survey in, so that assistive technology pronounces the content correctly. See [Multi-language Surveys](/docs/surveys/general-features/multi-language-surveys). **Leave the Back button enabled.** It is on by default, and it is what allows a respondent to review and correct an answer before submitting. Turn it off only when the survey design genuinely requires it — for example a quiz where going back would let a respondent change an answer after seeing the result. See [Hide Back Button](/docs/surveys/general-features/hide-back-button). **Keep questions short and ask one thing at a time.** This helps every respondent, and it particularly helps people using screen readers, screen magnification, or switch access, who move through content more slowly. # Changelog Source: https://formbricks.com/docs/platform/changelog What changed in each Formbricks release, mirroring the release notes on GitHub. Each release lists what changed, what to watch out for when upgrading, and every merged pull request. The same notes are published on [GitHub](https://github.com/formbricks/formbricks/releases). Self-hosting? Follow the [upgrade steps](/docs/self-hosting/advanced/upgrade) for every upgrade. **6.1.0** 19 October 2026 ### Overview Formbricks 6.1 adds survey visibility, so organizations can restrict who sees each survey and its responses, and brings dark mode and Custom CSS to surveys. It also adds Qualtrics survey import from .qsf files, Embedded Data V2 with a shared field library, the v3 Responses API with matching MCP tools, and new chart types and filters. Self-hosters: follow the [upgrade steps](/docs/self-hosting/advanced/upgrade), and see the [migration guide](/docs/self-hosting/advanced/migration#v6) for details on each change. The tested upgrade pair for this release is **6.0.2 → 6.1.0**. Kubernetes installs can opt into the [online upgrade mode](/docs/self-hosting/configuration/online-upgrade) instead of a maintenance window; it is still under validation, so the maintenance path remains the default. Formbricks 6.1 receives bug fixes and security fixes until **19 January 2027**. ### ⚠️ Breaking changes 6.1 is a minor release. It has no major breaking changes, only the smaller ones below, each of which affects a specific setup. As with every upgrade, follow the [upgrade steps](/docs/self-hosting/advanced/upgrade), which include a short maintenance window. **Self-hosting** * **Encrypted single-use links stop working.** Links created before 6.1 with URL encryption on (the default) are rejected after the upgrade. Re-create and re-send them. If you need more time, set `SINGLE_USE_LEGACY_UNSIGNED_UNTIL` to a date in `YYYY-MM-DD` format, for example `2026-11-15`: old links keep working until 00:00 UTC on that day. Use it only on an instance that serves a single organization, because it re-opens the issue this release fixes. Unencrypted links and custom single-use IDs are not affected ([#9131](https://github.com/formbricks/formbricks/pull/9131)) * **Helm: the web container is locked down.** It now runs with a read-only root filesystem, as non-root user `1001`, with all Linux capabilities dropped. This only affects custom images or sidecars that write inside the container: mount a writable path with `deployment.extraVolumes` and `deployment.extraVolumeMounts`, or set `deployment.containerSecurityContext.readOnlyRootFilesystem: false`. If you set `deployment.securityContext.runAsUser`, move it to `deployment.containerSecurityContext.runAsUser`, which now takes precedence ([#9450](https://github.com/formbricks/formbricks/pull/9450)) * **Helm: AuthZed hooks run as user `1001`.** If your custom image needs another user, set `authzed.initialization.securityContext.runAsUser` ([#9516](https://github.com/formbricks/formbricks/pull/9516)) * **Helm: taxonomy timeout overrides are validated.** With `taxonomy.enabled=true`, rendering fails unless `taxonomy.terminationGracePeriodSeconds` is at least `taxonomy.runDeadlineSeconds` + 30, and `taxonomy.hubStaleRunTimeoutSeconds` is greater than `taxonomy.runDeadlineSeconds`. The defaults (900, 930 and 1800 seconds) pass ([#9451](https://github.com/formbricks/formbricks/pull/9451)) **API** * **Ending-card URLs need a real host.** `buttonLink` and `url` on ending cards (v1, v2 and v3 survey create and update) must use a hostname with a dot (`intranet.example.com`), `localhost` or an IP address. A host like `http://intranet` now returns 400. Existing surveys keep loading; the rule applies when they are next saved ([#9399](https://github.com/formbricks/formbricks/pull/9399)) * **Hidden fields can't share a name with a question.** Adding one on `POST` or `PUT /api/v1/management/surveys` returns 400. Existing surveys keep saving ([#9467](https://github.com/formbricks/formbricks/pull/9467)) * **New survey limit per workspace.** `SURVEY_WORKSPACE_LIMIT` (a number, default `10000`, archived surveys included) caps the surveys in one workspace. Creating or copying a survey past it returns `422 workspace_survey_limit_reached` on v1 and v3. Raise it before upgrading if a workspace is close ([#9412](https://github.com/formbricks/formbricks/pull/9412)) > [accordion] All 273 changes > > #### 🚀 Features > > * feat(webhooks): fan out webhook delivery into per-webhook background jobs by @xernobyl in [#9123](https://github.com/formbricks/formbricks/pull/9123) > * feat(api-v3): OpenAPI contract for the v3 responses API by @xernobyl in [#9167](https://github.com/formbricks/formbricks/pull/9167) > * feat(api-v3): shared response service, and both delete endpoints on top of it by @xernobyl in [#9183](https://github.com/formbricks/formbricks/pull/9183) > * feat(api): edit and reorder survey blocks without resending the whole array by @xernobyl in [#9186](https://github.com/formbricks/formbricks/pull/9186) > * feat(api-v3): keyset cursor helper, its Response indexes, and Sentry on v3 5xx by @xernobyl in [#9222](https://github.com/formbricks/formbricks/pull/9222) > * feat(api-v3): response serializer and the three read endpoints by @xernobyl in [#9237](https://github.com/formbricks/formbricks/pull/9237) > * feat(charts): add nested filter groups to chart filters \[ENG-3149] by @Dhruwang in [#9241](https://github.com/formbricks/formbricks/pull/9241) > * feat(surveys): report the survey card's rect to native hosts by @pandeymangg in [#9242](https://github.com/formbricks/formbricks/pull/9242) > * feat(api-v3): response writes — create and patch by @xernobyl in [#9252](https://github.com/formbricks/formbricks/pull/9252) > * feat: add explicit AuthZed maintenance preparation by @BhagyaAmarasinghe in [#9265](https://github.com/formbricks/formbricks/pull/9265) > * feat(mcp): add responses:read and responses:write scopes by @xernobyl in [#9274](https://github.com/formbricks/formbricks/pull/9274) > * feat(mcp): name the survey element types on the tool surface by @xernobyl in [#9320](https://github.com/formbricks/formbricks/pull/9320) > * feat(mcp): expose responses through the MCP server by @xernobyl in [#9326](https://github.com/formbricks/formbricks/pull/9326) > * feat(i18n): support the full European language/locale matrix in surveys by @Dhruwang in [#9332](https://github.com/formbricks/formbricks/pull/9332) > * feat(surveys): keep New Survey available while the list loads \[ENG-2579] by @Dhruwang in [#9344](https://github.com/formbricks/formbricks/pull/9344) > * feat: offer the Lite license at 2FA and the workspace limit instead of branding removal by @harshsbhat in [#9347](https://github.com/formbricks/formbricks/pull/9347) > * feat(helm): support external embedding runtimes by @BhagyaAmarasinghe in [#9363](https://github.com/formbricks/formbricks/pull/9363) > * feat(settings): organization usage page for self-hosted owners and managers by @Dhruwang in [#9393](https://github.com/formbricks/formbricks/pull/9393) > * feat(api): record read-path metrics for the v3 responses API by @mattinannt in [#9401](https://github.com/formbricks/formbricks/pull/9401) > * feat(surveys): allow mailto: links in survey text and ending buttons \[ENG-3392] by @itsjavi in [#9403](https://github.com/formbricks/formbricks/pull/9403) > * feat(authorization): survey visibility and its operational model \[ENG-3282] by @Dhruwang in [#9412](https://github.com/formbricks/formbricks/pull/9412) > * feat(charts): matrix chart — statements × scale points grid (ENG-3312) by @Dhruwang in [#9415](https://github.com/formbricks/formbricks/pull/9415) > * feat(surveys): support an "Other" option in ranking questions by @Dhruwang in [#9429](https://github.com/formbricks/formbricks/pull/9429) > * feat(ai): OAuth2 client-credentials auth for the openai-compatible provider \[ENG-3226] by @Dhruwang in [#9438](https://github.com/formbricks/formbricks/pull/9438) > * feat: show feedback record taxonomy in API and drawer by @BhagyaAmarasinghe in [#9446](https://github.com/formbricks/formbricks/pull/9446) > * feat(charts): NPS & CSAT band dimension, fixed score axes, metric presets and response base \[ENG-3331] by @Dhruwang in [#9448](https://github.com/formbricks/formbricks/pull/9448) > * feat(helm): give the taxonomy pod its own ServiceAccount for workload identity by @BhagyaAmarasinghe in [#9453](https://github.com/formbricks/formbricks/pull/9453) > * feat(embedded-data): Embedded Data V2 — field library, one Embedded Data card, typed fields by @pandeymangg in [#9467](https://github.com/formbricks/formbricks/pull/9467) > * feat(mcp): offer responses:read / responses:write to OAuth MCP clients by @xernobyl in [#9479](https://github.com/formbricks/formbricks/pull/9479) > * feat: add custom overlay color and opacity for app surveys by @pandeymangg in [#9485](https://github.com/formbricks/formbricks/pull/9485) > * feat(email): tag SES messages by type and environment by @BhagyaAmarasinghe in [#9502](https://github.com/formbricks/formbricks/pull/9502) > * feat(surveys): open multi-language surveys in the browser language, on one shared matcher by @Dhruwang in [#9508](https://github.com/formbricks/formbricks/pull/9508) > * feat(auth): tell SSO users how to sign in and make forgot-password enumeration-safe \[ENG-3262]\[ENG-3639]\[ENG-3640] by @xernobyl in [#9511](https://github.com/formbricks/formbricks/pull/9511) > * feat(feedback-records): expose updated\_since/updated\_until for incremental extraction \[ENG-3420] by @xernobyl in [#9515](https://github.com/formbricks/formbricks/pull/9515) > * feat(i18n): ship Belgian Dutch and Swiss Italian survey bundles by @Dhruwang in [#9539](https://github.com/formbricks/formbricks/pull/9539) > * feat: dark mode and Custom CSS for surveys by @itsjavi in [#9549](https://github.com/formbricks/formbricks/pull/9549) > * feat: support taxonomy thinking levels and verify provider compatibility by @BhagyaAmarasinghe in [#9561](https://github.com/formbricks/formbricks/pull/9561) > * feat(surveys): let creators set alt text for survey images by @Dhruwang in [#9574](https://github.com/formbricks/formbricks/pull/9574) > * feat(actions): explain CSS selector syntax in the no-code click action by @jobenjada in [#9575](https://github.com/formbricks/formbricks/pull/9575) > * feat(nav): remove Beta badge from the Analyze section by @jobenjada in [#9583](https://github.com/formbricks/formbricks/pull/9583) > * feat(surveys): import Qualtrics surveys from .qsf files by @pandeymangg in [#9595](https://github.com/formbricks/formbricks/pull/9595) > * feat: add guarded online 6.1 upgrades by @BhagyaAmarasinghe in [#9609](https://github.com/formbricks/formbricks/pull/9609) > > #### 🐛 Fixes > > * fix(surveys): bind encrypted single-use links to their survey by @xernobyl in [#9131](https://github.com/formbricks/formbricks/pull/9131) > * fix(survey-editor): name the field behind a blocked publish \[ENG-2833] by @Dhruwang in [#9138](https://github.com/formbricks/formbricks/pull/9138) > * fix(sso): stop SSO recovery retries growing the URL into a 414 by @xernobyl in [#9144](https://github.com/formbricks/formbricks/pull/9144) > * fix(surveys): settle navigation from an off-block blockId instead of throwing \[ENG-2818] by @Dhruwang in [#9149](https://github.com/formbricks/formbricks/pull/9149) > * fix: prompt to reload when a tab outlives its deployment \[ENG-2330] by @Dhruwang in [#9154](https://github.com/formbricks/formbricks/pull/9154) > * fix: respect PostgreSQL Helm overrides by @BhagyaAmarasinghe in [#9221](https://github.com/formbricks/formbricks/pull/9221) > * fix(organization): mirror the server's owner count in the members table \[ENG-2616] by @pandeymangg in [#9226](https://github.com/formbricks/formbricks/pull/9226) > * fix(unify): translate the strings frozen in English on Unify surfaces \[ENG-2605] by @pandeymangg in [#9227](https://github.com/formbricks/formbricks/pull/9227) > * fix(integrations): stop the disabled integration action from navigating \[ENG-2608] by @pandeymangg in [#9228](https://github.com/formbricks/formbricks/pull/9228) > * fix(i18n): correct mistranslated Dutch back/save buttons by @jobenjada in [#9229](https://github.com/formbricks/formbricks/pull/9229) > * fix: terminate AuthZed health CLI after failures by @BhagyaAmarasinghe in [#9232](https://github.com/formbricks/formbricks/pull/9232) > * fix(i18n): update Hungarian translations by @Dhruwang in [#9234](https://github.com/formbricks/formbricks/pull/9234) > * fix(charts): resolve option labels from every mapped question \[ENG-3140] by @Dhruwang in [#9235](https://github.com/formbricks/formbricks/pull/9235) > * fix(charts): drop grouped rows no selected measure answers \[ENG-3150] by @Dhruwang in [#9239](https://github.com/formbricks/formbricks/pull/9239) > * fix(charts): keep one category label treatment on flipped bar charts \[ENG-3148] by @Dhruwang in [#9240](https://github.com/formbricks/formbricks/pull/9240) > * fix(ui): cap combobox option list inside its popover \[ENG-3158] by @Dhruwang in [#9243](https://github.com/formbricks/formbricks/pull/9243) > * fix(ui): match combobox search against the option label by @Dhruwang in [#9245](https://github.com/formbricks/formbricks/pull/9245) > * fix(survey-link): stop a mounted gate fighting the language picker \[ENG-3160] by @Dhruwang in [#9246](https://github.com/formbricks/formbricks/pull/9246) > * fix(analysis): partition NPS and CSAT buckets exhaustively \[ENG-3147] by @Dhruwang in [#9248](https://github.com/formbricks/formbricks/pull/9248) > * fix(survey-editor): stop a disabled unit select covering the rule delete button \[ENG-3175] by @Dhruwang in [#9250](https://github.com/formbricks/formbricks/pull/9250) > * fix(responses): bound the "Other" response filter instead of permuting every subset by @xernobyl in [#9253](https://github.com/formbricks/formbricks/pull/9253) > * fix(logger): resolve process handle through globalThis in Edge bundles \[ENG-2602] by @itsjavi in [#9267](https://github.com/formbricks/formbricks/pull/9267) > * fix(contacts): restore the clear control on date pickers \[ENG-3084] by @itsjavi in [#9289](https://github.com/formbricks/formbricks/pull/9289) > * fix(helm): support Gateway API v1.5 clusters by @BhagyaAmarasinghe in [#9291](https://github.com/formbricks/formbricks/pull/9291) > * fix(sso): label provisioning rejections in the callback-outcome log by @xernobyl in [#9294](https://github.com/formbricks/formbricks/pull/9294) > * fix(turbo): restore the copied SDK bundles from cache and hash the shared vite plugins by @xernobyl in [#9297](https://github.com/formbricks/formbricks/pull/9297) > * fix(auth): restrict OAuth dynamic client registration to loopback redirect URIs by @xernobyl in [#9300](https://github.com/formbricks/formbricks/pull/9300) > * fix(i18n): unify the Japanese term for Survey and translate the strings left in English \[ENG-2393] by @Dhruwang in [#9308](https://github.com/formbricks/formbricks/pull/9308) > * fix(i18n): translate the team permission label, membership status badges and organization roles \[ENG-2481] by @Dhruwang in [#9309](https://github.com/formbricks/formbricks/pull/9309) > * fix(surveys): strip trailing colon from validation field labels \[ENG-1797] by @Dhruwang in [#9311](https://github.com/formbricks/formbricks/pull/9311) > * fix(responses): keep a column labelled `__proto__` in the export by @itsjavi in [#9315](https://github.com/formbricks/formbricks/pull/9315) > * fix(storage): delete workspace files when an organization or account is deleted \[ENG-3197] by @pandeymangg in [#9316](https://github.com/formbricks/formbricks/pull/9316) > * fix(security): gate API key organization write access at mint time by @pandeymangg in [#9317](https://github.com/formbricks/formbricks/pull/9317) > * fix(account): send a relative callbackURL on the SSO account-deletion link by @xernobyl in [#9318](https://github.com/formbricks/formbricks/pull/9318) > * fix(auth): look users up by the canonical email address by @xernobyl in [#9319](https://github.com/formbricks/formbricks/pull/9319) > * fix(surveys): address respondents formally in the German and Russian survey UI by @mattinannt in [#9321](https://github.com/formbricks/formbricks/pull/9321) > * fix(storage): delete the old logo file when a workspace logo is removed or replaced \[ENG-2418] by @pandeymangg in [#9322](https://github.com/formbricks/formbricks/pull/9322) > * fix(editor): seed the rich text editor once per mount, not twice by @xernobyl in [#9328](https://github.com/formbricks/formbricks/pull/9328) > * fix(deps): raise the fast-xml-parser floor to 5.7.2 so S3 XML responses parse \[ENG-3263] by @pandeymangg in [#9329](https://github.com/formbricks/formbricks/pull/9329) > * fix(js-core): hold the survey concurrency guard once a survey has rendered (ENG-2849) by @pandeymangg in [#9331](https://github.com/formbricks/formbricks/pull/9331) > * fix(auth): keep logout on the admin domain when PUBLIC\_URL is set \[ENG-3286] by @jobenjada in [#9333](https://github.com/formbricks/formbricks/pull/9333) > * fix(helm): make v6 upgrades safer for self-hosters by @BhagyaAmarasinghe in [#9339](https://github.com/formbricks/formbricks/pull/9339) > * fix(unify-feedback): pluralize feedback-record counts in the records table \[ENG-2606] by @Dhruwang in [#9343](https://github.com/formbricks/formbricks/pull/9343) > * fix(unify-feedback): keep a held Enter to a single dataset purge \[ENG-2604] by @Dhruwang in [#9345](https://github.com/formbricks/formbricks/pull/9345) > * fix(survey-link): serve a same-script sibling for a requested survey language \[ENG-3083] by @Dhruwang in [#9353](https://github.com/formbricks/formbricks/pull/9353) > * fix(security): make the fresh-instance sign-up exception single-use \[ENG-2247] by @pandeymangg in [#9354](https://github.com/formbricks/formbricks/pull/9354) > * fix(ui): give link-buttons a hover state \[ENG-3138] by @Dhruwang in [#9355](https://github.com/formbricks/formbricks/pull/9355) > * fix(auth): name what the MCP feedbackRecords:write scope grants \[ENG-3192] by @Dhruwang in [#9356](https://github.com/formbricks/formbricks/pull/9356) > * fix(auth): stop serving Better Auth's /update-user over HTTP \[ENG-3189] by @Dhruwang in [#9358](https://github.com/formbricks/formbricks/pull/9358) > * fix(analysis): resolve date presets in the organization's time zone on summary and charts \[ENG-3215] by @itsjavi in [#9361](https://github.com/formbricks/formbricks/pull/9361) > * fix: refund failed invite rate-limit usage by @BhagyaAmarasinghe in [#9362](https://github.com/formbricks/formbricks/pull/9362) > * fix(surveys): close the language switcher on Escape and return focus to its trigger by @Dhruwang in [#9365](https://github.com/formbricks/formbricks/pull/9365) > * fix(i18n): use Unicode punctuation and remove contractions in English copy by @Dhruwang in [#9367](https://github.com/formbricks/formbricks/pull/9367) > * fix(workspace-settings): disable manage-gated settings for read/write members \[ENG-3191] by @itsjavi in [#9368](https://github.com/formbricks/formbricks/pull/9368) > * fix(auth): unlock password users whose credential row has no issuer \[ENG-3258] by @pandeymangg in [#9369](https://github.com/formbricks/formbricks/pull/9369) > * fix: correct doesNotIncludeAllOf, surface impressions load errors, delete removed survey languages by @mattinannt in [#9371](https://github.com/formbricks/formbricks/pull/9371) > * fix(sso): revoke the squatter's API keys on SSO recovery by @pandeymangg in [#9372](https://github.com/formbricks/formbricks/pull/9372) > * fix(surveys): open each cardless survey page at the top \[ENG-3379] by @Dhruwang in [#9374](https://github.com/formbricks/formbricks/pull/9374) > * fix(surveys): stop naming survey images and name inline surveys \[ENG-3154] by @itsjavi in [#9376](https://github.com/formbricks/formbricks/pull/9376) > * fix(web): single-brand link survey titles and render ICU placeholders \[ENG-3154] by @itsjavi in [#9377](https://github.com/formbricks/formbricks/pull/9377) > * fix(editor): group question types and clear settings tab axe violations \[ENG-3154] by @itsjavi in [#9378](https://github.com/formbricks/formbricks/pull/9378) > * fix(docker): run hub worker in self-hosted compose by @BhagyaAmarasinghe in [#9379](https://github.com/formbricks/formbricks/pull/9379) > * fix(analysis): thin and relabel time axes for hourly granularity \[ENG-3211] by @itsjavi in [#9380](https://github.com/formbricks/formbricks/pull/9380) > * fix(survey-ui): keep out-of-month date picker days at full contrast \[ENG-1296] by @itsjavi in [#9381](https://github.com/formbricks/formbricks/pull/9381) > * fix(mcp): log JWKS load failures as jwks\_fetch by @jobenjada in [#9382](https://github.com/formbricks/formbricks/pull/9382) > * fix(integrations): show a reconnect message when Google Sheets lacks the scope \[ENG-2807] by @Dhruwang in [#9383](https://github.com/formbricks/formbricks/pull/9383) > * fix(ai-translation): explain output token limit overflow instead of a generic failure \[ENG-2831] by @Dhruwang in [#9384](https://github.com/formbricks/formbricks/pull/9384) > * fix(surveys): only ring the close and language buttons on keyboard focus \[ENG-1830] by @itsjavi in [#9385](https://github.com/formbricks/formbricks/pull/9385) > * fix(settings): hide the integrations tip when the user has no workspace \[ENG-1781] by @Dhruwang in [#9387](https://github.com/formbricks/formbricks/pull/9387) > * fix(dashboards): add new charts to the next open slot \[ENG-3209] by @Dhruwang in [#9390](https://github.com/formbricks/formbricks/pull/9390) > * fix(helm): prevent TEI API key logging by @BhagyaAmarasinghe in [#9391](https://github.com/formbricks/formbricks/pull/9391) > * fix: rate-limit AI chart generation by @BhagyaAmarasinghe in [#9392](https://github.com/formbricks/formbricks/pull/9392) > * fix: replace MinIO client with RustFS CLI by @BhagyaAmarasinghe in [#9395](https://github.com/formbricks/formbricks/pull/9395) > * fix: sanitize v1 contact list database errors by @BhagyaAmarasinghe in [#9396](https://github.com/formbricks/formbricks/pull/9396) > * fix(surveys): require a valid web address for ending card button and redirect URLs \[ENG-2585] by @Dhruwang in [#9399](https://github.com/formbricks/formbricks/pull/9399) > * fix(audit): keep respondent content out of the audit log, and record refused MCP mutations by @pandeymangg in [#9402](https://github.com/formbricks/formbricks/pull/9402) > * fix(surveys): pin --spacing inside #fbjs against host overrides \[ENG-833] by @itsjavi in [#9405](https://github.com/formbricks/formbricks/pull/9405) > * fix(analysis): reject nonsensical prompts in AI chart generation \[ENG-3210] by @itsjavi in [#9406](https://github.com/formbricks/formbricks/pull/9406) > * fix(database): harden postgres connection reliability by @BhagyaAmarasinghe in [#9407](https://github.com/formbricks/formbricks/pull/9407) > * fix(survey-list): keep settings when a survey is duplicated \[ENG-2144] by @pandeymangg in [#9409](https://github.com/formbricks/formbricks/pull/9409) > * fix(survey): reject JSON literals as numeric prefill values (ENG-1146) by @Dhruwang in [#9410](https://github.com/formbricks/formbricks/pull/9410) > * fix(web): typecheck Playwright specs in pnpm typecheck \[ENG-2239] by @itsjavi in [#9413](https://github.com/formbricks/formbricks/pull/9413) > * fix(telemetry): send usage updates through the configured HTTPS\_PROXY by @Dhruwang in [#9414](https://github.com/formbricks/formbricks/pull/9414) > * fix(charts): scale the flipped category gutter with the chart width \[ENG-3223] by @Dhruwang in [#9418](https://github.com/formbricks/formbricks/pull/9418) > * fix(surveys): drop image minimum height once media has loaded \[ENG-3421] by @Dhruwang in [#9420](https://github.com/formbricks/formbricks/pull/9420) > * fix(surveys): use "Skicka in" for the Swedish submit button by @jobenjada in [#9422](https://github.com/formbricks/formbricks/pull/9422) > * fix(api): bound request arrays and cap invalid\_params on v3 and MCP \[ENG-3384] by @pandeymangg in [#9423](https://github.com/formbricks/formbricks/pull/9423) > * fix(web): validate brandColor before it reaches the OG image SVG \[ENG-2563] by @itsjavi in [#9425](https://github.com/formbricks/formbricks/pull/9425) > * fix(web): attribute Sentry errors to the signed-in user by id \[ENG-2326] by @itsjavi in [#9426](https://github.com/formbricks/formbricks/pull/9426) > * fix: block 10 personal email domains on Cloud by @jobenjada in [#9427](https://github.com/formbricks/formbricks/pull/9427) > * fix(storage): delete respondent uploads when a survey is deleted \[ENG-3373] by @pandeymangg in [#9428](https://github.com/formbricks/formbricks/pull/9428) > * fix(web): require Manage access to change survey custom head scripts by @mattinannt in [#9432](https://github.com/formbricks/formbricks/pull/9432) > * fix(surveys): 44px close button touch area, inset from the card corner \[ENG-3429] (a11y) by @itsjavi in [#9433](https://github.com/formbricks/formbricks/pull/9433) > * fix(survey-editor): name the block, not its id, when a logic destination is gone \[ENG-3443] by @itsjavi in [#9440](https://github.com/formbricks/formbricks/pull/9440) > * fix(security): bump nodemailer, undici, fast-uri and ip-address and patch 8 advisories \[ENG-3435]\[ENG-3442] by @Dhruwang in [#9444](https://github.com/formbricks/formbricks/pull/9444) > * fix(survey-editor): stop recall tag edits hanging the editor in an update loop \[ENG-2931] by @Dhruwang in [#9447](https://github.com/formbricks/formbricks/pull/9447) > * fix(helm): render containerSecurityContext on the web container \[ENG-2922] by @BhagyaAmarasinghe in [#9450](https://github.com/formbricks/formbricks/pull/9450) > * fix(helm): validate the two cross-process taxonomy timing invariants \[ENG-2813] by @BhagyaAmarasinghe in [#9451](https://github.com/formbricks/formbricks/pull/9451) > * fix(docker): ship a slim Cube image without known CVEs \[ENG-3431] by @BhagyaAmarasinghe in [#9457](https://github.com/formbricks/formbricks/pull/9457) > * fix(helm): run Cube with a read-only root filesystem and no capabilities by @BhagyaAmarasinghe in [#9461](https://github.com/formbricks/formbricks/pull/9461) > * fix(security): bump markdown-it, engine.io and brace-expansion and patch 6 advisories \[ENG-3463]\[ENG-3462]\[ENG-3461]\[ENG-3460]\[ENG-3459]\[ENG-3458] by @Dhruwang in [#9462](https://github.com/formbricks/formbricks/pull/9462) > * fix(taxonomy): wire TAXONOMY\_MAX\_RECORDS in compose and fail fast on empty LLM base URL \[ENG-1522] by @BhagyaAmarasinghe in [#9463](https://github.com/formbricks/formbricks/pull/9463) > * fix(billing): replace legacy EUR subscriptions instead of swapping USD prices onto them by @Dhruwang in [#9464](https://github.com/formbricks/formbricks/pull/9464) > * fix(settings): keep a workspace-less organization active in account settings by @Dhruwang in [#9465](https://github.com/formbricks/formbricks/pull/9465) > * fix(helm): harden the migration Job's containers \[ENG-3480] by @BhagyaAmarasinghe in [#9468](https://github.com/formbricks/formbricks/pull/9468) > * fix(analysis): translate response filter criteria \[ENG-645] by @Dhruwang in [#9470](https://github.com/formbricks/formbricks/pull/9470) > * fix(auth): revoke an OAuth app's tokens when its consent is revoked by @xernobyl in [#9472](https://github.com/formbricks/formbricks/pull/9472) > * fix(responses): fold a contact's identical resubmission within a minute into the first response by @Dhruwang in [#9477](https://github.com/formbricks/formbricks/pull/9477) > * fix(deps): bump next to 16.3.6 for GHSA-vcvr-r3jv-pc5j by @Dhruwang in [#9478](https://github.com/formbricks/formbricks/pull/9478) > * fix: restrict survey reset to workspace managers by @jobenjada in [#9480](https://github.com/formbricks/formbricks/pull/9480) > * fix(i18n): translate 76 strings left in English in 12 locales by @xernobyl in [#9486](https://github.com/formbricks/formbricks/pull/9486) > * fix(docker): rebuild the Cube image on the fixed distroless base (1.7.47-2) by @BhagyaAmarasinghe in [#9492](https://github.com/formbricks/formbricks/pull/9492) > * fix(auth): let claude.ai and ChatGPT MCP connectors register through DCR by @xernobyl in [#9494](https://github.com/formbricks/formbricks/pull/9494) > * fix(contacts): derive activity timeline read-only state on the server by @mattinannt in [#9495](https://github.com/formbricks/formbricks/pull/9495) > * fix(database): stop write transactions expiring on Prisma's 5 s default \[ENG-3285] by @xernobyl in [#9499](https://github.com/formbricks/formbricks/pull/9499) > * fix(api-v3): refuse NULL bytes in list filters and cursors with a 400 by @xernobyl in [#9501](https://github.com/formbricks/formbricks/pull/9501) > * fix(helm): restore writable migration jobs for older images by @BhagyaAmarasinghe in [#9503](https://github.com/formbricks/formbricks/pull/9503) > * fix(security): bump hono to 4.13.7 and patch 1 advisory \[ENG-3486] by @Dhruwang in [#9505](https://github.com/formbricks/formbricks/pull/9505) > * fix(docker): pin basic-ftp 6.2.2 in the Cube image for CVE-2026-102990 (1.7.47-3) by @Dhruwang in [#9506](https://github.com/formbricks/formbricks/pull/9506) > * fix(setup): fit the setup forms inside their card on narrow screens by @Dhruwang in [#9507](https://github.com/formbricks/formbricks/pull/9507) > * fix(storage): delete removed-element uploads by their survey-scoped key \[ENG-2546] by @pandeymangg in [#9509](https://github.com/formbricks/formbricks/pull/9509) > * fix(survey-editor): mount the workspace context in the editor layout \[ENG-2601] by @pandeymangg in [#9510](https://github.com/formbricks/formbricks/pull/9510) > * fix(web): tell the user when a server action gets an unexpected response \[ENG-2899] by @xernobyl in [#9513](https://github.com/formbricks/formbricks/pull/9513) > * fix(helm): set numeric UID for AuthZed hooks by @BhagyaAmarasinghe in [#9516](https://github.com/formbricks/formbricks/pull/9516) > * fix(contacts): bind bulk-upload attribute-key arrays as typed text\[] params \[ENG-3549] by @Dhruwang in [#9520](https://github.com/formbricks/formbricks/pull/9520) > * fix(og): leave right-to-left survey names off the preview card by @pandeymangg in [#9521](https://github.com/formbricks/formbricks/pull/9521) > * fix(charts): drop option-less groups from charts grouped by value option by @Dhruwang in [#9523](https://github.com/formbricks/formbricks/pull/9523) > * fix(survey-link): stop a superseded language switch landing after the respondent moved on \[ENG-3170] by @Dhruwang in [#9524](https://github.com/formbricks/formbricks/pull/9524) > * fix(hub): stop passing Next's proxied request to the Request constructor in the feedback-records dev proxy \[ENG-3225] by @xernobyl in [#9525](https://github.com/formbricks/formbricks/pull/9525) > * fix(gateway): refuse ambiguous JSON bodies before authorizing feedback records \[ENG-3658] by @xernobyl in [#9532](https://github.com/formbricks/formbricks/pull/9532) > * fix(surveys): give unnamed pop-up surveys a top-level heading by @itsjavi in [#9533](https://github.com/formbricks/formbricks/pull/9533) > * fix(segments): let interaction filters target the survey being edited by @jobenjada in [#9534](https://github.com/formbricks/formbricks/pull/9534) > * fix(security): bump source-map-js to 1.2.2 and patch 1 advisory \[ENG-3661] by @Dhruwang in [#9536](https://github.com/formbricks/formbricks/pull/9536) > * fix(docs): point anchor links at Mintlify heading ids by @jobenjada in [#9540](https://github.com/formbricks/formbricks/pull/9540) > * fix(web): report a rejected clipboard write instead of a false "Copied" toast \[ENG-3239] by @Dhruwang in [#9542](https://github.com/formbricks/formbricks/pull/9542) > * fix(ai): stop logging prompts and model output when an AI call fails \[ENG-3720] by @xernobyl in [#9550](https://github.com/formbricks/formbricks/pull/9550) > * fix(responses): read organization and contact before the management create transactions \[ENG-3722] by @xernobyl in [#9551](https://github.com/formbricks/formbricks/pull/9551) > * fix(web): drop inert Access-Control-Allow-Credentials from public client API CORS by @pandeymangg in [#9553](https://github.com/formbricks/formbricks/pull/9553) > * fix: remediate Formbricks image vulnerabilities by @BhagyaAmarasinghe in [#9558](https://github.com/formbricks/formbricks/pull/9558) > * fix(billing): charge VAT through Stripe automatic tax on paid plans by @Dhruwang in [#9568](https://github.com/formbricks/formbricks/pull/9568) > * fix(web): allow blob: workers in the CSP so Sentry Replay can compress by @pandeymangg in [#9573](https://github.com/formbricks/formbricks/pull/9573) > * fix(teams): expire pending invites when their creator leaves the organization by @BhagyaAmarasinghe in [#9576](https://github.com/formbricks/formbricks/pull/9576) > * fix(security): bump next to 16.3.8 and patch 2 advisories \[ENG-3737]\[ENG-3743] by @Dhruwang in [#9579](https://github.com/formbricks/formbricks/pull/9579) > * fix(database): build the keyset Response indexes with lock\_timeout = 0 \[ENG-3701] by @BhagyaAmarasinghe in [#9580](https://github.com/formbricks/formbricks/pull/9580) > * fix(docker): reset install-input timestamps after the source copy so a cached install passes pnpm's check \[ENG-3801] by @xernobyl in [#9581](https://github.com/formbricks/formbricks/pull/9581) > * fix(deps): pin handlebars 4.7.10 and shell-quote 1.12.0 for critical advisories \[ENG-3806] by @xernobyl in [#9584](https://github.com/formbricks/formbricks/pull/9584) > * fix(invites): limit invites per user and org creation, bound inviter name by @mattinannt in [#9585](https://github.com/formbricks/formbricks/pull/9585) > * fix(survey-link): give link survey routes their own error boundary \[ENG-3171] by @pandeymangg in [#9586](https://github.com/formbricks/formbricks/pull/9586) > * fix: create Dependabot Linear tickets as vulnerability-labelled Triage items by @mattinannt in [#9589](https://github.com/formbricks/formbricks/pull/9589) > * fix(auth): keep the OAuth state cookie alive as long as the state it guards \[ENG-3314] by @xernobyl in [#9600](https://github.com/formbricks/formbricks/pull/9600) > * fix: page survey summary and response export in sort order by @itsjavi in [#9601](https://github.com/formbricks/formbricks/pull/9601) > * fix(database): keep the legacy Survey columns until Formbricks 7 by @pandeymangg in [#9603](https://github.com/formbricks/formbricks/pull/9603) > * fix(database): make the idle-transaction backstop opt-in through DATABASE\_URL \[ENG-3285] by @xernobyl in [#9604](https://github.com/formbricks/formbricks/pull/9604) > * fix(docker): warn instead of blocking when the Compose is missing hub-worker \[ENG-2484] by @xernobyl in [#9606](https://github.com/formbricks/formbricks/pull/9606) > * fix(surveys): keep renderer line-heights unitless so iOS Dynamic Type scales them once by @itsjavi in [#9608](https://github.com/formbricks/formbricks/pull/9608) > * fix: keep Next.js server and browser assets in sync by @BhagyaAmarasinghe in [#9614](https://github.com/formbricks/formbricks/pull/9614) > * fix(survey-ui): keep smiley rating line art readable in dark mode \[ENG-3937] by @Dhruwang in [#9626](https://github.com/formbricks/formbricks/pull/9626) > * fix: sign Plain chat external ID with customerDetailsSignature (backport #9628 to release/6.1) by @Dhruwang in [#9630](https://github.com/formbricks/formbricks/pull/9630) > * fix(api-v3): refuse survey patches and block edits that introduce cyclic logic by @Dhruwang in [#9634](https://github.com/formbricks/formbricks/pull/9634) > * fix(surveys): resolve bare language codes to the canonical survey language \[ENG-3961] by @itsjavi in [#9637](https://github.com/formbricks/formbricks/pull/9637) > * fix: run the JS SDK journey under a customer CSP and stop Zod's eval probe \[ENG-3969] by @Dhruwang in [#9640](https://github.com/formbricks/formbricks/pull/9640) > * fix(helm): skip deferred migrations in the Hub migration wait \[ENG-3948] by @BhagyaAmarasinghe in [#9642](https://github.com/formbricks/formbricks/pull/9642) > * fix(docker): refresh the bundled Cube model on update \[ENG-3951] by @BhagyaAmarasinghe in [#9645](https://github.com/formbricks/formbricks/pull/9645) > * fix(authzed): document the prepare Job's full environment and name invalid variables \[ENG-3953] by @BhagyaAmarasinghe in [#9650](https://github.com/formbricks/formbricks/pull/9650) > * fix(api-v3): accept survey patches that leave a stored survey's existing issues untouched \[ENG-3975] by @Dhruwang in [#9651](https://github.com/formbricks/formbricks/pull/9651) > * fix(workspaces): enforce the workspace limit inside the creating transaction (backport #9613 to release/6.1) \[ENG-3921] by @xernobyl in [#9654](https://github.com/formbricks/formbricks/pull/9654) > * fix(upgrade): run the online migration script from the bundled CLI's image path \[ENG-3949] by @BhagyaAmarasinghe in [#9656](https://github.com/formbricks/formbricks/pull/9656) > * fix(upgrade): compare survey edges as sets in online finalize \[ENG-3950] by @BhagyaAmarasinghe in [#9662](https://github.com/formbricks/formbricks/pull/9662) > * fix(chart): let online mode keep a single Cube replica \[ENG-3955] by @BhagyaAmarasinghe in [#9663](https://github.com/formbricks/formbricks/pull/9663) > * fix(surveys): keep every answer when file uploads overlap \[ENG-3945] (backport #9672 to release/6.1) by @pandeymangg in [#9674](https://github.com/formbricks/formbricks/pull/9674) > > #### 🔧 Refactors > > * refactor(api-v3): consolidate error handling into one thrown-error mapper, one Hub mapper and a problem-code registry by @xernobyl in [#9147](https://github.com/formbricks/formbricks/pull/9147) > * refactor(mcp): put the feedback-record tools back on registerScopedTool by @xernobyl in [#9290](https://github.com/formbricks/formbricks/pull/9290) > * refactor(auth): make BETTER\_AUTH\_\* the documented env var names, keep NEXTAUTH\_\* as an alias by @xernobyl in [#9307](https://github.com/formbricks/formbricks/pull/9307) > * refactor(api-v3): one shared list `meta` across the v3 collection endpoints by @pandeymangg in [#9336](https://github.com/formbricks/formbricks/pull/9336) > * refactor: clear AuthZed cutover SonarQube findings by @BhagyaAmarasinghe in [#9452](https://github.com/formbricks/formbricks/pull/9452) > * refactor(web): keep service modules server-only and guard "use server" exports by @mattinannt in [#9497](https://github.com/formbricks/formbricks/pull/9497) > * refactor(api-v3): generate the Responses Zod schemas from the OpenAPI spec by @xernobyl in [#9500](https://github.com/formbricks/formbricks/pull/9500) > * refactor(surveys): pull the block-flow decision out of the survey component by @mattinannt in [#9531](https://github.com/formbricks/formbricks/pull/9531) > * refactor(hub): adopt @formbricks/hub 0.14.0 and drop the query-serialization workaround \[ENG-2536] by @xernobyl in [#9594](https://github.com/formbricks/formbricks/pull/9594) > > #### ⚡ Performance > > * perf(survey-editor): debounce preview updates while editing \[ENG-991] by @itsjavi in [#9370](https://github.com/formbricks/formbricks/pull/9370) > * perf(survey-editor): memoize block cards to skip unchanged blocks on edit \[ENG-992] by @itsjavi in [#9373](https://github.com/formbricks/formbricks/pull/9373) > * perf(docker): shrink the build context and cache the install layer \[ENG-587] by @BhagyaAmarasinghe in [#9466](https://github.com/formbricks/formbricks/pull/9466) > > #### 📚 Docs > > * docs: rename Connect Your App to Web & Mobile SDK, document install methods by @jobenjada in [#9168](https://github.com/formbricks/formbricks/pull/9168) > * docs(review): make performance an explicit review dimension (ENG-3179) by @Dhruwang in [#9251](https://github.com/formbricks/formbricks/pull/9251) > * docs: add release and maintenance policy page by @mattinannt in [#9273](https://github.com/formbricks/formbricks/pull/9273) > * docs: add Okta OIDC setup guide by @jobenjada in [#9275](https://github.com/formbricks/formbricks/pull/9275) > * docs: clarify Kubernetes v6 maintenance upgrades by @BhagyaAmarasinghe in [#9282](https://github.com/formbricks/formbricks/pull/9282) > * docs: move AuthZed Operations, Rate Limiting and AI Features into Configuration by @jobenjada in [#9306](https://github.com/formbricks/formbricks/pull/9306) > * docs: correct the conformance claims on the accessibility page by @jobenjada in [#9348](https://github.com/formbricks/formbricks/pull/9348) > * docs: inline local setup instructions by @mattinannt in [#9359](https://github.com/formbricks/formbricks/pull/9359) > * docs: forbid agent session links in PRs and commits by @itsjavi in [#9388](https://github.com/formbricks/formbricks/pull/9388) > * docs: add performance testing guidance by @BhagyaAmarasinghe in [#9408](https://github.com/formbricks/formbricks/pull/9408) > * docs: add workspaceSurveyCount to the MCP list\_surveys example by @pandeymangg in [#9417](https://github.com/formbricks/formbricks/pull/9417) > * docs: remove leftover merge-conflict marker from v6 migration guide by @BhagyaAmarasinghe in [#9458](https://github.com/formbricks/formbricks/pull/9458) > * docs: add Attio and Salesforce integration guides by @harshsbhat in [#9473](https://github.com/formbricks/formbricks/pull/9473) > * docs(mcp): add an Adding A Tool guide to the MCP handbook by @xernobyl in [#9481](https://github.com/formbricks/formbricks/pull/9481) > * docs(self-hosting): say which patch releases carry the bundled Cube image by @BhagyaAmarasinghe in [#9491](https://github.com/formbricks/formbricks/pull/9491) > * docs: fix dead links, stray anchors and an unclosed div in the readme by @pandeymangg in [#9528](https://github.com/formbricks/formbricks/pull/9528) > * docs: correct how Prisma applies migrations and document failed-migration recovery \[ENG-2820] by @xernobyl in [#9529](https://github.com/formbricks/formbricks/pull/9529) > * docs(mcp): troubleshoot Cloudflare blocking self-hosted MCP connections by @BhagyaAmarasinghe in [#9554](https://github.com/formbricks/formbricks/pull/9554) > * docs: mark the 5.4 accessibility fixes as released by @jobenjada in [#9597](https://github.com/formbricks/formbricks/pull/9597) > * docs: remove v6.1 section from the self-hosting migration guide by @mattinannt in [#9599](https://github.com/formbricks/formbricks/pull/9599) > * docs(self-hosting): pin Cube by digest on 6.0.x before an online upgrade by @Dhruwang in [#9658](https://github.com/formbricks/formbricks/pull/9658) > > #### ⚙️ CI > > * fix(ci): pull the MinIO images from quay.io instead of Docker Hub by @xernobyl in [#9260](https://github.com/formbricks/formbricks/pull/9260) > * chore(ci): stop inheriting secrets into the PR gate's reusable workflows by @pandeymangg in [#9330](https://github.com/formbricks/formbricks/pull/9330) > * feat(ci): sync the release-branch cut to Linear by @mattinannt in [#9346](https://github.com/formbricks/formbricks/pull/9346) > * chore(ci): add Dependabot for GitHub Actions and unify harden-runner pins (ENG-2544) by @Dhruwang in [#9411](https://github.com/formbricks/formbricks/pull/9411) > * chore(ci): retire orphaned Formbricks Cloud helmfile deploy workflow by @BhagyaAmarasinghe in [#9442](https://github.com/formbricks/formbricks/pull/9442) > * fix(ci): scan the published release image by digest instead of a dead workflow\_run trigger by @BhagyaAmarasinghe in [#9443](https://github.com/formbricks/formbricks/pull/9443) > * fix(ci): stop maintenance releases rolling GHCR major/minor tags back \[ENG-2926] by @BhagyaAmarasinghe in [#9449](https://github.com/formbricks/formbricks/pull/9449) > * fix(ci): exclude nested lockfiles from the PR size check by @BhagyaAmarasinghe in [#9459](https://github.com/formbricks/formbricks/pull/9459) > * fix(ci): fail the latest-release check closed instead of promoting on API errors \[ENG-2927] by @xernobyl in [#9496](https://github.com/formbricks/formbricks/pull/9496) > * chore(ci): bump the github-actions group across 4 directories with 24 updates by @mattinannt in [#9522](https://github.com/formbricks/formbricks/pull/9522) > > #### 🧹 Chores > > * chore: A/B test shortening the Pro trial from 14 to 7 days by @harshsbhat in [#9224](https://github.com/formbricks/formbricks/pull/9224) > * chore(eslint): widen the package lint gates past ./src by @xernobyl in [#9286](https://github.com/formbricks/formbricks/pull/9286) > * chore(sonar): enrol eight packages and the route/action layer in coverage \[ENG-2432] by @Dhruwang in [#9310](https://github.com/formbricks/formbricks/pull/9310) > * chore(deps): replace the deprecated otplib 12 and @react-email/components by @Dhruwang in [#9313](https://github.com/formbricks/formbricks/pull/9313) > * test(attachments): stop the headers test leaking its stream into the next test by @itsjavi in [#9314](https://github.com/formbricks/formbricks/pull/9314) > * chore(api-v3): mark the generated OpenAPI bundle linguist-generated by @mattinannt in [#9349](https://github.com/formbricks/formbricks/pull/9349) > * chore(i18n): drop the retroactivity sentence from the anonymize toggle by @jobenjada in [#9357](https://github.com/formbricks/formbricks/pull/9357) > * chore: update Helm app version to 6.0.0 by @BhagyaAmarasinghe in [#9366](https://github.com/formbricks/formbricks/pull/9366) > * chore(email): map react-email components for jsx-a11y \[ENG-3154] by @itsjavi in [#9375](https://github.com/formbricks/formbricks/pull/9375) > * chore: dedupe lockfile and clean up stale repository configuration by @mattinannt in [#9400](https://github.com/formbricks/formbricks/pull/9400) > * test: run repo-level script tests as part of pnpm test by @xernobyl in [#9469](https://github.com/formbricks/formbricks/pull/9469) > * chore(billing): ship the trial and response-limit nudges to everyone by @harshsbhat in [#9471](https://github.com/formbricks/formbricks/pull/9471) > * chore: align Node 24 across CI, engines and the devcontainer by @xernobyl in [#9474](https://github.com/formbricks/formbricks/pull/9474) > * chore(deps): bump Prisma to 7.10.0 to fix leaked transactions after a maxWait overrun by @xernobyl in [#9498](https://github.com/formbricks/formbricks/pull/9498) > * test(billing): cover subscription\_cancelled on both plan-downgrade paths by @Dhruwang in [#9527](https://github.com/formbricks/formbricks/pull/9527) > * chore(sentry): drop scanner multipart noise at ingest \[ENG-1745] by @pandeymangg in [#9537](https://github.com/formbricks/formbricks/pull/9537) > * chore: remove CODEOWNERS and automatic PR reviewer assignment by @mattinannt in [#9590](https://github.com/formbricks/formbricks/pull/9590) > * chore(docker): bump the cube group in /docker/cube-image with 2 updates by @Dhruwang in [#9605](https://github.com/formbricks/formbricks/pull/9605) ### 🔒 Security credits Thanks to the following researchers, who reported issues fixed in this release through responsible disclosure: * Kareem Mahmoud — concurrent requests could create workspaces past the plan's workspace limit ([#9654](https://github.com/formbricks/formbricks/pull/9654)) **Full Changelog**: [https://github.com/formbricks/formbricks/compare/6.0.2...6.1.0](https://github.com/formbricks/formbricks/compare/6.0.2...6.1.0) # AI Features Source: https://formbricks.com/docs/platform/features/ai-features How AI features are organized, hosted, and controlled in Formbricks. > [!NOTE] > > AI features are part of the [Enterprise Edition](/docs/self-hosting/advanced/license). Formbricks ships a single organization-wide toggle that turns on AI-powered helpers across the app: **Settings → Organization → General → Smart functionality (AI)**. ## AI Principles 1. **Always optional**: AI is disabled until your organization enables. You can run Formbricks fully without AI. 2. **We separate AI**: We distinguish between: * **Smart Functionality**: helps teams build and operate faster (for example [AI Survey Translation](/docs/surveys/general-features/multi-language-surveys#translate-with-ai) or [AI Chart Creation](/docs/unify-feedback/dashboards-charts#ai-builder)). * **Data AI**: features that work directly with your feedback data (creating embeddings for Unify Feedback semantic search). ### Privacy-first and self-hosted where possible We prioritize self-hosted AI, especially for capabilities that process customer feedback data. Formbricks supports AI in self-hosted and on-premise environments, and we prefer open-weight models whenever feasible. For Unify Feedback semantic search, we host the embeddings model ourselves. This means feedback data is not shared with third-party model providers for that capability, and your collected feedback/response data is never used as AI training input. ## Model Hosting Status * **Current Smart Functionality model**: Gemini 3.5 Flash hosted on Google Cloud Platform in Germany. * **Current Embeddings model**: Alibaba GTE embeddings hosted by Formbricks in Germany. * **In progress**: evaluation of self-hosted Kimi 2.5 to replace Gemini 3.5 Flash for Smart Functionality. ## AI Features by Category ### Smart Functionality * **[AI Survey Translation](/docs/surveys/general-features/multi-language-surveys#translate-with-ai)**: auto-translate survey questions, options, and prompts into enabled languages. * **[AI Chart Creation](/docs/unify-feedback/dashboards-charts#ai-builder)**: describe a chart in natural language and Formbricks generates the underlying query. * **[Qualtrics Import](/docs/surveys/general-features/migrate-from-qualtrics)**: turn a Qualtrics survey export (.qsf) into a draft survey. ### Data AI * **Embeddings creation**: create embeddings for feedback records so they can be used for semantic search, clustering, and retrieval. ## Permissions Only **Owners** and **Managers** can change the AI toggle. Other roles see a read-only state. # Contacts Source: https://formbricks.com/docs/platform/features/contacts Contacts are the people you survey. Store what you already know about them, then use it to decide who sees a survey and to read responses in context. A **contact** is one person in a workspace, with a set of attributes you supply. Contacts let you do two things you cannot do with anonymous responses: target a survey at a specific group, and see who said what. Contacts live under **Contacts** in the main navigation, which has three tabs — Contacts, Attributes and Segments. > [!NOTE] > > Contacts are part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license). ## Contacts The Contacts tab lists everyone in the workspace. ![The Contacts tab, listing contacts with their default attributes](https://mintcdn.com/formbricks/ApCFvCRngQDbcTWu/images/platform/features/contacts/contacts-list.webp?fit=max\&auto=format\&n=ApCFvCRngQDbcTWu\&q=85\&s=f015010e7fc0cb34c7d5233d6ad59a45) Contacts arrive in three ways: * **From your app**, when the SDK identifies someone. See [User Identification](/docs/surveys/website-app-surveys/user-identification) for `setUserId`, `setAttribute` and friends. * **From a CSV**, using **Upload CSV**. Useful for a list you already hold outside your product. * **From the API** — `POST /api/v2/management/contacts` for one, `PUT /api/v2/management/contacts/bulk` for many. Both need every attribute key to exist already. See the [API v2 reference](/docs/api-v2-reference/introduction). Contacts are scoped to a **workspace**. A person known in one workspace is not automatically known in another. ## Attributes An attribute is one field on a contact — a plan, a branch, a signup date. The Attributes tab lists every attribute key the workspace knows about. ![The Attributes tab, listing every attribute key in the workspace](https://mintcdn.com/formbricks/ApCFvCRngQDbcTWu/images/platform/features/contacts/attribute-keys.webp?fit=max\&auto=format\&n=ApCFvCRngQDbcTWu\&q=85\&s=43d8fc332c147507c74861de5820b245) Two kinds: * **Default attributes** — `email`, `userId`, `firstName`, `lastName`. Formbricks creates these itself and they cannot be deleted, which is why they have no checkbox in the table. * **Custom attributes** — anything you send. Create them ahead of time with **Create attribute**, or let them appear the first time the SDK sends one. Each key carries a label, the key your code uses, and a data type. > [!NOTE] > > A workspace can hold up to **150 attribute keys**. That is a limit on the number of distinct fields, not on how many contacts have them. ## Segments A segment is a saved group of contacts, defined by a filter rather than a fixed list. Membership is evaluated when it is used, so a contact joins or leaves as their attributes change. ![The Segments tab, showing a saved segment](https://mintcdn.com/formbricks/ApCFvCRngQDbcTWu/images/platform/features/contacts/segments.webp?fit=max\&auto=format\&n=ApCFvCRngQDbcTWu\&q=85\&s=0b3b6b46eff64febbecc9acb9fc86848) Filters combine attributes, devices and previous survey interaction, and can be grouped with **and** / **or**. A segment built on "plan equals premium" always means today's premium customers, without anyone maintaining a list. Segments are what [attribute-based targeting](/docs/surveys/website-app-surveys/attribute-based-targeting) uses to decide who sees an app survey. ## What Contacts change about a response Once a response is linked to a contact, it stops being anonymous: * The response table shows who answered instead of "Anonymous". * You can filter and segment responses by any attribute the contact carries. * [Personal Links](/docs/surveys/link-surveys/personal-links) can be generated per contact, so a link survey attributes its answers too. # Email Branding Source: https://formbricks.com/docs/platform/features/email-customization Branding the emails that are sent to your respondents. > [!NOTE] > > **Self-Hosting Requirements**: Uploading custom organization logos for emails requires file upload storage > to be configured. If you're self-hosting Formbricks, make sure to [configure file > uploads](/docs/self-hosting/configuration/file-uploads) before using this feature. Email branding is a white-label feature that allows you to customize the email that is sent to your users. You can upload a logo of your company and use it in the email. > [!NOTE] > > Email branding is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license). > [!NOTE] > > Only the Owner and Managers of the organization can modify the logo. ## How to upload a logo 1. Go to **Settings → Organization → General**. 2. You will see a card called **Email Customization**. ![Email Customization Settings](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/email-customization/email-customization-card.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=a9d0180bdf38ca2d5a8f8b9645c64b34) 3. Upload a logo of your company. Logos must be 5 MB or less. 4. Click on the **Save** button. ![Updated Logo](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/email-customization/updated-logo.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=0869269266b86849f839e588f376a273) ## Viewing the Logo in the Email You can click on the **Send test email** button to get a test email with the logo. ![Email Sample](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/email-customization/email-sample.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=29953fbbcdc381ef3e6eb58d7a7d3918) ## Use Cases * **White-labeling**: You can use this feature to white-label your emails to your users. * **Branding**: You can use this feature to add your logo to your emails to increase brand recognition. # Activepieces Source: https://formbricks.com/docs/platform/features/integrations/activepieces A step-by-step guide to integrating Formbricks with Activepieces. Activepieces is a versatile tool to automate workflows between Formbricks and numerous applications. Here's how to set it up. > [!NOTE] > > Ensure your survey is finalized before setting up Activepieces. Any changes in the survey will require additional adjustments in the workflow. ## Step 1: Setup your survey incl. `questionId` for every question Set up the `questionId`s of your survey questions before activating it. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=723097d5bcb8ef6005048367d71cb458) *Update the Question ID on every question — it is the first field behind **Show Question settings** at the foot of a question card.* > [!NOTE] > > Already activated? Duplicate survey You can only update the questionId before activating the survey. If already activated, simply duplicate it. > > ![Duplicate Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/duplicate-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=3efcf928c9aabae279322ba7b7900fce) ## Step 2: Setup Activepieces Visit [Activepieces](https://activepieces.com) to start a new Flow. ![Create New Flow](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/create-new-flow.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=1fa7831e36aef555aafca92301cb3262) Search for `Formbricks` and choose the event to trigger the flow, we will choose `Response Finished` here ![Search Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/search-formbricks.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=53c97290a767994cf032f8682c81482e) ## Step 3: Connect Formbricks with Activepieces Click on `Create connection`: ![Create Connection](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/create-connection.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=9a40dbc2f8ad9cd9c6ec9de5b67ec488) Enter the Formbricks API Host and API Key. API Host is by default set to [https://app.formbricks.com](https://app.formbricks.com) but can be modified for self-hosting instances. Learn how to get an API Key from the [API Key tutorial](/docs/api-reference/generate-key). ![Configure Connection](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/configure-connection.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=0cd473462e28b9f6e14b510a7f21a6dc) ## Step 4: Select Survey Choose from your created surveys: ![Select Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/select-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=3fd6ee8f1d97fb0e126b79bc2703f409) ## Step 5: Send a test response You need a test response for Activepieces setup. Click on Test trigger and submit a test response in the connected Formbricks survey to see the data in Activepieces. ![Test Trigger](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/test-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=931848aa56c54370dbda1462acc1838f) If the test response is successful, you will see the data in Activepieces. ![Success Response](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/success-response.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=f7a89145bb04bc2c3ab12be8ea13914e) ## Step 6: Set up Google Sheet Decide on the desired action for the data. Here, we'll send submissions to a Google Sheet. Add Google sheet step to your flow and configure it as follows: Choose "Add a Row" for the action. Authenticate with Google and select the spreadsheet you want to add the data to. ![Select Google sheet](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/select-gs-sheet.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=cb4092a65ab6a90efe4e491c3ac0268b) Specify the fields you want to add to the spreadsheet. ![Match Data](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/match-data.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=c044e2a03cb1c99b562270b744d13524) A new row gets added to the spreadsheet for every response: ![Result](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/activepieces/result.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=c77ca57b90389510155a613e5f4d35cc) # Airtable Source: https://formbricks.com/docs/platform/features/integrations/airtable A step-by-step guide to integrate Airtable with Formbricks Cloud. The Airtable integration allows you to automatically send responses to an Airtable of your choice. > [!NOTE] > > If you are on a self-hosted instance, you will need to configure this integration separately. Please follow > the guides [here](/docs/self-hosting/configuration/integrations) to configure integrations on your self-hosted > instance. ## Formbricks Cloud 1. Click on the `Configuration` tab in the left sidebar and then click on the `Integrations` tab and click on the `connect` button under the `Airtable` card. ![Formbricks Integration Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=290dcf4201ed47bc08b71e9d64eb7bc9) 1. Now click on the "Connect with Airtable" button to authenticate yourself with Airtable. ![Connect Formbricks with Airtable](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/connect-with-airtable.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=d7d956d1b96445fad21dffef2587fb7a) 1. You will now be taken to a page where you need to add and grant access to the base you want to use for the integration. ![Add and grant access to airtable base](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/add-base.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=b7097033522de30ddde686413458bf65) 1. Once you add and grant access to your base, you will be taken back to Formbricks Cloud and see the connected status as below: ![Formbricks is now connected with Airtable](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/airtable-connected.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=28b9414375d510c77349c715a8c08201) > [!NOTE] > > Before the next step, make sure that you have a Formbricks Survey with at least one question and an Airtable > base with at least one table in the Airtable account you integrated. 1. Now click on the "Link New Table" button to link an Airtable with Formbricks and a modal will open up. ![Link Formbricks with an Airtable base](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/link-survey-with-table.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=59dba4b116b0a3507da9e1b4a973dcde) 1. Select the Base and table you want to link with Formbricks and the Survey. On doing so, you will be asked with what questions' responses you want to feed in Airtable. Select the questions and click on the "Save" button. ![Select question to link with Airtable](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/link-with-questions.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=78d4066c7aa19ba8882ff90b7376c4ea) 1. On submitting, the modal will close and you will see the linked table in the list of linked tables. ![List of linked tables](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/list-linked-surveys.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=872b8f72d17e7944a2431c1c6a65c32c) Congratulations! You have successfully linked an Airtable with Formbricks. Now whenever a response is submitted for the linked survey, it will be automatically added to the linked Airtable. Still struggling or something not working as expected? [Join us on Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! ## Remove Integration with Airtable To remove the integration with Airtable, 1. Visit the Integrations tab in your Formbricks Cloud dashboard. 2. Select "Manage" button in the Airtable card. 3. Click on the "Connected with `" just before the "Link new Table" button. 4. It will now ask for a confirmation to remove the integration. Click on the "Delete" button to remove the integration. You can always come back and connect again with the same Airtable Account. ![Delete Airtable Integration with Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/airtable/delete-integration.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=08101ddecb21fcb3d99ed4acd1e64bc7) Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Attio Source: https://formbricks.com/docs/platform/features/integrations/attio Learn how to integrate Formbricks with Attio to automatically create or update records when survey responses are submitted. > [!NOTE] > > There is no native Attio integration yet. Connect Formbricks to Attio with Attio Workflows, Make, n8n, or a custom webhook. ## Prerequisites * A Formbricks survey that collects email addresses * An Attio plan that includes Workflows or API access * An Attio access token (n8n and webhook methods only) ### Attio access token **1. Create an Integration** In Attio, go to **Workspace Settings** → **Developers** and click **Create a new integration**. **2. Set Scopes and Copy the Token** Grant `record_permission:read-write` and `object_configuration:read`, save, and copy the access token. See [Attio's authentication docs](https://docs.attio.com/rest-api/guides/authentication) for details. *** ## Method 1: Attio Workflows Attio [Workflows](https://attio.com/help/reference/automations/workflows/overview-of-workflows) can receive Formbricks webhooks directly, so no third-party tool is needed. **1. Create a Workflow** In Attio, go to **Workflows** → **Create workflow** and choose **Webhook received** as the trigger. Copy the generated URL. **2. Add the Webhook in Formbricks** Go to **Configuration** → **Integrations** → **Manage Webhooks** → **Add Webhook**. Paste the Attio URL, select **Response Finished**, and choose your survey. ![Integrations Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/webhooks/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6701827c1d1c7b24eaec63f2c3450601) **3. Add a Parse JSON Block** Submit a test response, then add a **Parse JSON** block. Set **Input** to **Webhook Payload Body** and generate the schema by pasting the sample Formbricks payload. Answers are under `data.data`, keyed by `questionId`. **4. Add a Create/Update Record Action** Choose **People** or **Companies** and map the parsed fields. To avoid duplicates, match People on email (e.g. `data.data.email`) and Companies on domain. **5. Test and Activate** Submit another response, confirm the record in Attio, and turn the workflow on. *** ## Method 2: Make.com **1. Set Question IDs** Give each question a meaningful `questionId` so mapping is easier. These can only be changed before publishing; for a published survey, duplicate it first. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=34ef2a99e6353651275474585b319bd6) **2. Add the Formbricks Trigger** In a new [Make](https://make.com) scenario, add **Formbricks** → **Watch Response Finished**. Click **Create a webhook**, enter your API host (default `https://app.formbricks.com`) and [API key](/docs/api-reference/rest-api#how-to-generate-an-api-key), and select your survey. ![Search Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/search-formbricks.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ccc17e459b6999a6e5c9a2853548bda) ![Enter API Key](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/enter-api-key-and-host.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=635a6374fc27d2f5935dbf1204937c7a) **3. Add the Attio Module** Add **Attio** → **Create or Update a Person** (or **Company**) and connect your Attio account. **4. Map Fields** | Attio Attribute | Formbricks Field | | - | - | | Email Addresses | `data.email` | | Name | `data.firstName` / `data.lastName` | | Custom Attribute | Any `data.*` or `meta.*` field | **5. Test and Activate** Submit a test response, confirm the record in Attio, and turn on the scenario. *** ## Method 3: n8n > [!NOTE] > > The Formbricks and Attio nodes are community nodes for self-hosted n8n. On n8n Cloud, use a **Webhook** node as the trigger (with a Formbricks webhook pointing at it) and an **HTTP Request** node with the API call from Method 4. The Webhook node nests the request under `body`, so use `$json.body.data.data.*` in place of `$json.data.data.*`. **1. Add the Formbricks Trigger** Install `@formbricks/n8n-nodes-formbricks` via **Settings** → **Community Nodes**. Then add the **Formbricks** trigger node, connect your API key and host, select **Response Finished**, and choose your survey. ![Add Formbricks Trigger](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-formbricks-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6ec754cf7fb282ae800595341304a2ea) **2. Add the Attio Node** Install `n8n-nodes-attio` via **Settings** → **Community Nodes**, add it with the **Assert Record** operation, and authenticate with your access token. **3. Configure the Record** Set **object** to `people` and **matching\_attribute** to `email_addresses`, then set the `data` body (replace the keys with your `questionId`s): ```json theme={null} { "values": { "email_addresses": ["{{ $json.data.data.email }}"], "name": [{ "first_name": "{{ $json.data.data.firstName }}", "last_name": "{{ $json.data.data.lastName }}", "full_name": "{{ $json.data.data.firstName }} {{ $json.data.data.lastName }}" }] } } ``` **4. Test and Activate** Click **Listen for event**, submit a test response, confirm the record in Attio, and activate the workflow. *** ## Method 4: Custom webhook **1. Create a Formbricks Webhook** Go to **Configuration** → **Integrations** → **Manage Webhooks** → **Add Webhook**, enter your endpoint URL, select **Response Finished**, and choose your surveys. **2. Build the Handler** Read the answers from `data.data` (keyed by `questionId`) and call Attio's [Assert Record endpoint](https://docs.attio.com/rest-api/endpoint-reference/records/assert-a-record), which creates or updates in one call: ``` PUT /v2/objects/people/records?matching_attribute=email_addresses ``` ```json theme={null} { "data": { "values": { "email_addresses": ["jane@example.com"], "name": [{ "first_name": "Jane", "last_name": "Doe", "full_name": "Jane Doe" }] } } } ``` For signature verification, see [Webhooks](/docs/platform/features/integrations/webhooks). **3. Deploy and Test** Deploy the handler to a public URL, submit a test response, and confirm the record in Attio. *** ## Troubleshooting **No record created** * Check that you're mapping the correct email `questionId`. * Check the token has `record_permission:read-write` and `object_configuration:read`. **Duplicate records** * Use a create-or-update action (or the Assert endpoint) matching People on email and Companies on domain. **Webhook not firing** * Check the URL is public, **Response Finished** is selected, and the survey is linked. *** Need help? Ask in [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Google Sheets Source: https://formbricks.com/docs/platform/features/integrations/google-sheets The Google Sheets integration allows you to automatically send responses to a Google Sheet of your choice. > [!NOTE] > > If you are on a self-hosted instance, you will need to configure this integration separately. Please follow > the guides [here](/docs/self-hosting/configuration/integrations) to configure integrations on your self-hosted > instance. ## Connect Google Sheets 1. Click on the `Configuration` tab in the left sidebar and then click on the `Integrations` tab and click on the `connect` button under the `Google Sheets` card. ![Formbricks Integrations Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ac15a0daeecc4883e3d187a35606e8f) 1. Now click on the "Connect with Google" button to authenticate yourself with Google. ![Connect Formbricks with your Google](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/connect-with-google.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=79a3adba6ec8eb508cbbc7da0c6387e5) 1. You will now be taken to the Google OAuth page where you can select the Google account you want to use for the integration. 2. Once you have selected the account and completed the authentication process, you will be taken back to Formbricks Cloud and see the connected status as below: ![Formbricks is now connected with Google](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/google-connected.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=0b14eb071721c1f08d03b38a8bf6914f) > [!NOTE] > > Before the next step, make sure that you have a Formbricks Survey with at least one question and a Google > Sheet in the Google account you integrated. 1. Now click on the "Link New Sheet" button to link a Google Sheet with Formbricks and a modal will open up. ![Link Formbricks with a Google Sheet](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/link-survey-with-sheet.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=ca62fb9dea56a6f81333a3781df06004) 1. Enter the spreadsheet URL for the Google Sheet you want to link with Formbricks and the Survey. On doing so, you will be asked with what questions' responses you want to feed in the Google Sheet. Select the questions and click on the "Link Sheet" button. ![Select question to link with Google Sheet](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/link-with-questions.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6d19277fc829fc7fbdc3221fc36b7771) 1. On submitting, the modal will close and you will see the linked Google Sheet in the list of linked Google Sheets. ![List of linked Google Sheets](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/list-linked-surveys.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=c782f4ba4ad1a0fce63bb220a96a96f4) Congratulations! You have successfully linked a Google Sheet with Formbricks. Now whenever a response is submitted for the linked survey, it will be automatically added to the linked Google Sheet. ## Remove Integration with Google Account To remove the integration with Google Account, 1. Visit the Integrations tab in your Formbricks Cloud dashboard. 2. Select **Manage Sheets** button in the Google Sheets card. 3. Click on the **Delete Integration** button. 4. It will now ask for a confirmation to remove the integration. Click on the **Delete** button to remove the integration. You can always come back and connect again with the same Google Account. ![Delete Google Integration with Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/google-sheets/delete-connection.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6080da7155daecc672c0decef8f68659) ## What info do you need? * Your **Email ID** for authentication (We use this to identify you) * Your **Google Sheets Names and IDs** (We fetch this to list and show you the options of choosing a sheet to integrate with) * Write access to **selected Google Sheet** (The google sheet you choose to integrate it with, we write survey responses to it) For the above, we ask for: 1. **User Email**: To identify you (that's it, nothing else, we're opensource, see this in our codebase [here](https://github.com/formbricks/formbricks/blob/main/apps/web/app/api/google-sheet/callback/route.ts#L47C17-L47C25)) 2. **Google Spreadsheet API**: To write to the spreadsheet you select (that's it, nothing else, we're opensource, see this method in our codebase [here](https://github.com/formbricks/formbricks/blob/main/packages/lib/googleSheet/service.ts#L70)) > [!NOTE] > > We store as little personal information as possible. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # HubSpot Source: https://formbricks.com/docs/platform/features/integrations/hubspot Learn how to integrate Formbricks with HubSpot to automatically create or update contacts when survey responses are submitted. > [!NOTE] > > Formbricks doesn't have a native HubSpot integration yet. This guide shows you how to connect Formbricks with HubSpot using automation platforms (Make.com, n8n) or custom webhooks. ## Prerequisites Before setting up the integration, you'll need: 1. **A Formbricks account** with at least one survey that collects email addresses 2. **A HubSpot account** with API access 3. **HubSpot API credentials** (see authentication options below) 4. **Automation service** like Make, n8n, or ActivePieces (for no-code methods) ### HubSpot Authentication Options HubSpot offers two main ways to authenticate API requests: #### Option A: OAuth 2.0 via Public App (Recommended) OAuth is the recommended approach for production integrations. When using Make.com or n8n, they handle OAuth authentication for you through their built-in HubSpot connectors. #### Option B: Legacy Private Apps (Simple Setup) For custom webhook handlers, you can use a Legacy Private App which provides a static access token. While marked as "legacy," these apps remain fully supported by HubSpot. To create a Legacy Private App: **1. Open HubSpot Settings** Go to your HubSpot account **Settings** and navigate to **Integrations** → **Private Apps**. **2. Create the App** Click **Create a private app** and give it a name (e.g., "Formbricks Integration"). **3. Configure Scopes** Under **Scopes**, add `crm.objects.contacts.write` and `crm.objects.contacts.read`. **4. Get Your Access Token** Click **Create app** and copy the access token. > [!NOTE] > > For more information on HubSpot's authentication options, see the [HubSpot Authentication Overview](https://developers.hubspot.com/docs/guides/apps/authentication/intro-to-auth). *** ## Method 1: Using Make.com (Recommended for No-Code) > [!NOTE] > > Before starting, ensure your survey has clear `questionId` values set. You can only update these before activating the survey. If your survey is already activated, duplicate it and update the question IDs in the copy. **1. Set Up Your Survey** Make sure your survey has meaningful `questionId` values for each question. This makes mapping responses to HubSpot fields easier. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=34ef2a99e6353651275474585b319bd6) **2. Create a New Make.com Scenario** Go to [Make.com](https://make.com) and create a new scenario. Search for **Formbricks** and select the **Watch Response Finished** trigger, not **Watch Response Created**, which fires as soon as the first question is answered and may run before the email field is filled in. ![Search Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/search-formbricks.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ccc17e459b6999a6e5c9a2853548bda) **3. Connect Formbricks to Make** Click **Create a webhook**, enter your Formbricks API Host (default: `https://app.formbricks.com`), add your Formbricks API Key (see [API Key Setup](/docs/api-reference/generate-key)), and select the survey you want to connect. ![Enter API Key](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/enter-api-key-and-host.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=635a6374fc27d2f5935dbf1204937c7a) **4. Add the HubSpot Module** Click the **+** button after the Formbricks trigger, search for **HubSpot**, choose **Create or Update a Contact** as the action, and connect your HubSpot account. **5. Map Formbricks Fields to HubSpot** Map the Formbricks response fields to HubSpot contact properties: | HubSpot Field | Formbricks Field | | - | - | | Email | `data.email` (your email question ID) | | First Name | `data.firstName` (if collected) | | Last Name | `data.lastName` (if collected) | | Custom Property | Any other `data.*` field | You can also map metadata: `meta.country`, `meta.userAgent.browser`, `survey.title`. **6. Test and Activate** Submit a test response to your Formbricks survey, verify the contact appears in HubSpot, and turn on your Make scenario. *** ## Method 2: Using n8n (Self-Hosted Option) > [!NOTE] > > The Formbricks n8n node is available as a community node. Install it via **Settings** → **Community Nodes** → install `@formbricks/n8n-nodes-formbricks`. **1. Set Up the Formbricks Trigger** Create a new workflow in n8n, add the **Formbricks** trigger node, connect it with your Formbricks API Key and host, select **Response Finished** as the event, and choose your survey. ![Add Formbricks Trigger](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-formbricks-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6ec754cf7fb282ae800595341304a2ea) **2. Add the HubSpot Node** Add a new node and search for **HubSpot**, select **Create/Update Contact** as the operation, and connect your HubSpot account (n8n supports both OAuth and access token authentication). **3. Configure Field Mapping** In the HubSpot node, map the fields: ``` Email: {{ $json.data.email }} First Name: {{ $json.data.firstName }} Last Name: {{ $json.data.lastName }} ``` For custom HubSpot properties, use the **Additional Fields** section to add mappings like `survey_source`, `response_id`, and `submission_date`. **4. Test Your Workflow** Click **Listen for event** in the Formbricks trigger, submit a test survey response, verify the data flows through to HubSpot, and activate your workflow. *** ## Method 3: Using Webhooks (Custom Integration) For maximum flexibility, you can use Formbricks webhooks with a custom endpoint that calls the HubSpot API directly. This approach is ideal for developers who want full control. > [!NOTE] > > This method requires a HubSpot access token. You can use a Legacy Private App token (simplest) or implement OAuth 2.0 for production applications. **1. Create a Formbricks Webhook** Go to **Settings → Workspace → Integrations** in Formbricks, click **Manage Webhooks** → **Add Webhook**, enter your endpoint URL, select **Response Finished** as the trigger, and choose the surveys to monitor. ![Integrations Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/webhooks/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6701827c1d1c7b24eaec63f2c3450601) **2. Build Your Webhook Handler** Your webhook handler needs to: * **Receive the Formbricks webhook** - Accept POST requests with the survey response payload * **Extract contact data** - Parse the email and other fields from `data.data` (keyed by your `questionId` values) * **Call the HubSpot API** - Use the [HubSpot Contacts API](https://developers.hubspot.com/docs/api/crm/contacts) to create or update contacts * **Handle duplicates** - HubSpot returns a 409 error if a contact with that email exists; search and update instead You can deploy using serverless functions (Vercel, AWS Lambda, Cloudflare Workers), traditional servers, or low-code platforms. For webhook signature verification, see the [Webhooks documentation](/docs/platform/features/integrations/webhooks). **3. Deploy and Test** Deploy your webhook handler to a publicly accessible URL, add the URL to your Formbricks webhook configuration, submit a test survey response, and verify the contact appears in HubSpot. *** ## Troubleshooting ### Contact Not Created in HubSpot 1. **Check the email field**: Ensure your survey has an email question and you're mapping the correct `questionId` 2. **Verify API token**: Make sure your HubSpot access token has the required scopes (`crm.objects.contacts.write` and `crm.objects.contacts.read`) 3. **Check for duplicates**: HubSpot returns a 409 error if a contact with that email already exists ### Webhook Not Triggering 1. Verify the webhook URL is publicly accessible 2. Check that **Response Finished** trigger is selected 3. Ensure the survey is linked to the webhook ### Testing Your Integration 1. Use a unique test email for each test 2. Check HubSpot's **Contacts** page after submitting a response 3. Review your webhook handler logs for errors *** Still struggling or something not working as expected? [Join our GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we're happy to help! # Make Source: https://formbricks.com/docs/platform/features/integrations/make Discover how to seamlessly integrate Formbricks with Make.com. Dive into our comprehensive guide to set up scenarios, connect with a plethora of apps, and send your survey data to more than 1000 platforms. Make is a powerful tool to send information between Formbricks and thousands of apps. Here's how to set it up. > [!NOTE] > > Nailed down your survey?? Any changes in the survey cause additional work in the *Scenario*. It makes sense to first settle on the survey you want to run and then get to setting up Make. ## Step 1: Setup your survey incl. `questionId` for every question Set up the `questionId`s of your survey questions before activating it. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=34ef2a99e6353651275474585b319bd6) *Update the Question ID on every question — it is the first field behind **Show Question settings** at the foot of a question card.* > [!NOTE] > > Already activated? Duplicate survey You can only update the questionId > before activating the survey. If already activated, simply duplicate it. > > ![Duplicate Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/duplicate-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=5216b43ede5a16e451ed29f124120f3c) ## Step 2: Setup Make.com Visit [Make.com](https://make.com) to start a new scenario. ![Create New Scenario](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/create-new-scenario.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=d9ceaed0efac89156df2329f201adf02) Search for `Formbricks`: ![Search Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/search-formbricks.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ccc17e459b6999a6e5c9a2853548bda) Choose the event to trigger the Scenario: ![Select Triggers](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/select-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=24757168c5324066b618f8885235d1ff) ## Step 3: Connect Formbricks with Make Click "Create a webhook": ![Create Webhook](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/create-webhook.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=ca43db58ed03fc435134be0cd514fdf7) Enter the Formbricks API Host and API Key. API Host is by default set to [https://app.formbricks.com](https://app.formbricks.com) but can be modified for self-hosting instances. Learn how to get an API Key from the [API Key tutorial](/docs/api-reference/generate-key). ![Enter API Key](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/enter-api-key-and-host.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=635a6374fc27d2f5935dbf1204937c7a) ## Step 4: Select Survey Choose from your created surveys: ![Select Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/select-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=709e2d509cb93a1de88b803c17a4cdb3) ## Step 5: Send a test response You need a test response for Make setup. ![Submit Test Response](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/submit-test-response.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=ece19702a7adafdf89768d9a2eed7b97) ## Step 6: Set up Google Sheet Decide on the desired action for the data. Here, we'll send submissions to a Google Sheet: ![Add Module](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/add-module.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=a04b8d62aa46938487d9095f4d13b68b) Choose "Add a Row" for the action: ![Select Action](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/select-action.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=ca26035145d335d74ef5707ea4058be6) Specify the spreadsheet details and match the Formbricks data: ![Select Fields](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/select-fields.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=b8a0451ff3e8a95961f2c7ca2cf383ca) A new row gets added to the spreadsheet for every response: ![Result](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/result.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=59392cf5771573bd585ebda559a72c20) # n8n Source: https://formbricks.com/docs/platform/features/integrations/n8n Integrate Formbricks with n8n for a streamlined workflow experience. > [!NOTE] > > The Formbricks n8n node is currently only available in the n8n self-hosted > version as a community node. To install it go to "Settings" -> "Community > Nodes" and install @formbricks/n8n-nodes-formbricks. n8n allows you to build flexible workflows focused on deep data integration. And with sharable templates and a user-friendly UI, the less technical people on your team can collaborate on them too. Unlike other tools, complexity is not a limitation. So you can build whatever you want — without stressing over budget. Hook up Formbricks with n8n and you can send your data to 350+ other apps. Here is how to do it. ## Step 1: Setup your survey incl. `questionId` for every question > [!NOTE] > > Nailed down your survey? Any changes in the survey cause additional work in > the n8n node. It makes sense to first settle on the survey you want to run and > then get to setting up n8n. When setting up the node your life will be easier when you change the `questionId`s of your survey questions. You can only do so **before** you activate your survey. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=83d7b8bcef7f685a1cec3570c42a7960) *The Question ID is the first field behind **Show Question settings** at the foot of a question card. Update it so you will recognise the response tied to this question.* > [!NOTE] > > Already activated? Duplicate survey You can only update the questionId > when the survey was not yet activated. Already activated it? Just **duplicate > it** to update the questionIds. > > ![Duplicate Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/duplicate-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=3ee00952d6bc1a50d9a944d765851730) ## Step 2: Setup your n8n workflow Go to [n8n.io](https://n8n.io) and create a new workflow. Search for “Formbricks” to get started: ![Add Formbricks Trigger](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-formbricks-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6ec754cf7fb282ae800595341304a2ea) ## Step 3: Connect Formbricks with n8n Now, you have to connect n8n with Formbricks via an API Key: ![Create new credential button](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/create-new-credential-btn.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=62ef7868d016e0bc34713d709e0c4bb1) Click on Create New Credential button to add your host and API Key ![Add host and api key](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-api-key.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=8d70a5cd7bb1a26e5d5bbfbcdd334677) Now you need an API key. Please refer to the [API Key Setup](/docs/api-reference/generate-key) page to learn how to create one. Once you copied it in the API Key field, hit Save button to test the connection and save the credentials. ![Successful Connection](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/success-connection.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=ae40b4a7811b28647bf769508c3b9a6b) ## Step 4: Select Event Next, you can choose the event you want to trigger the node on. You can select multiple events: ![Select Event](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/select-event.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=8ed93f51f5affc12a4fe481f2b26cff9) Here, we are adding `Response Finished` as an event, which will trigger when the survey has been filled out. ## Step 5: Select Survey Next, you can choose from all the surveys you have created in this workspace. You can select multiple surveys: ![Select Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/select-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=f8493b8d9fc1984a4f8de3bd9504c9b8) Here, we are selecting two surveys. ![Selected Surveys](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/selected-surveys.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4dd3b1869902a51da42d498fc96e46d6) ## Step 6: Test your trigger In order to set up n8n you'll need a test response in the selected survey. This allows you to select the individual values of each response in your workflow. ![Submit Test Response](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/submit-test-response.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=0477176b9d40aa90e60c6bee6e77dfd8) Next, click on Listen for event button. ![Listen for event](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/listen-for-event.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=45543238ec8328d126e8f8d74548b806) Then, go to the survey which you selected. Fill it out, and wait for the particular event to trigger (in this case it's `Response Finished`). Once the event is triggered you will see the response that you filled out in the survey. ![Test Response Success](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/test-response-success.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=eea118063a384c0c08e3fa79a255c6b9) Now you have all the data you need at hand. The next steps depend on what you want to do with it. In this tutorial, we will send submissions to a discord channel: ## Step 7: Add discord to your workflow Click on the plus and search `Discord`. ![Add Discord](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-discord.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=a30314c4fcf031ec9274fcd4a9bf0e66) Fill in the `Webhook URL` and the `Content` that you want to receive in the respective discord channel. Next, click on `Execute Node` button to test the node. ![Fill Discord Details](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/fill-discord-details.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=1a52e6c0c26b35ad8702393ac82a81b1) Once the execution is successful, you'll receive the content in the discord channel. ![Discord Response](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/discord-response.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=3416cbebf74fd38ce22548ae0abb8813) # Notion Source: https://formbricks.com/docs/platform/features/integrations/notion The notion integration allows you to automatically send responses to a Notion database of your choice. > [!NOTE] > > If you are on a self-hosted instance, you will need to configure this integration separately. Please follow > the guides [here](/docs/self-hosting/configuration/integrations) to configure integrations on your self-hosted > instance. ## Formbricks Cloud 1. Click on the `Configuration` tab in the left sidebar and then click on the `Integrations` tab and click on the `connect` button under the `Notion` card. ![Formbricks Integrations Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=45e8841243520e5141e7eac601abe381) 1. Now click on the "Connect with Notion" button to authenticate yourself with Notion. ![Connect Formbricks with your Notion account](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/connect-with-notion.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=7745daa8b55e5de7d51c2fce0b285db7) 1. You will now be taken to the Notion OAuth page where you can select the Notion account you want to use for the integration 2. Once you have selected the account and databases and completed the authentication and authorization process, you will be taken back to Formbricks Cloud and see the connected status as below: ![Formbricks is now connected with Notion](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/notion-connected.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=bf9db3fa51fde8dabf9cab7ac5c1ceb9) > [!NOTE] > > Before the next step, make sure that you have a Formbricks Survey with at least one question and a Notion > database in the Notion account you integrated. 1. Now click on the "Link New Database" button to link a Notion database with Formbricks and a modal will open up. ![Link Formbricks with a Notion database](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/link-survey-with-database.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4086c400e2f9dd49980b54e8842b226b) 1. Select the Notion database you want to link with Formbricks and the Survey. On doing so, you will be asked to map formbricks' survey questions with selected databases' column. Complete the mapping and click on the "Link Database" button. ![Question to notion database column mapping](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/link-with-databases.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=521e36a65afdc2c59910bcca4bfbcf57) 1. On submitting, the modal will close and you will see the linked Notion database in the list of linked Notion databases. ![List of linked notion databases](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/list-linked-databases.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=dbb9241fad17c49de9fb0ffb64db762c) Congratulations! You have successfully linked a Notion database with Formbricks. Now whenever a response is submitted for the linked survey, it will be automatically added to the linked Notion database. ## Setup in self-hosted Formbricks Enabling the Notion Integration in a self-hosted environment requires a setup using Notion account and changing the environment variables of your Formbricks instance. 1. Sign up for a [Notion](https://www.notion.so/) account, if you don't have one already. 2. Go to the [my integrations](https://www.notion.so/my-integrations) page and click on **New integration**. 3. Fill up the basic information like **Name**, **Logo** and click on **Submit**. 4. Now, click on **Distribution** tab on the sidebar. A text will appear which will ask you to make the integration public. Click on that toggle button. A form will appear below the text. 5. Now provide it the details such as requested. Under **Redirect URIs** field: * If you are running formbricks locally, you can enter `http://localhost:3000/api/v1/integrations/notion/callback`. * Or, you can enter `https:///api/v1/integrations/notion/callback` 6. Once you've filled all the necessary details, click on **Submit**. 7. A screen will appear which will have **Client ID** and **Client secret**. Copy them and set them as the environment variables in your Formbricks instance as: * `NOTION_OAUTH_CLIENT_ID` - OAuth Client ID * `NOTION_OAUTH_CLIENT_SECRET` - OAuth Client Secret Voila! You have successfully enabled the Notion integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Formbricks Cloud](#formbricks-cloud) section to link a Notion database with Formbricks. ## Remove Integration with Notion Account To remove the integration with Slack Workspace, 1. Visit the Integrations tab in your Formbricks Cloud dashboard. 2. Select "Manage" button in the Slack card. 3. Click on the "Delete Integration" button. 4. It will now ask for a confirmation to remove the integration. Click on the "Delete" button to remove the integration. You can always come back and connect again with the same Notion Account. ![Delete Notion Integration with Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/notion/delete-connection.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=a451928e88fb522433f6eeeae6320886) Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Third-party Integrations Source: https://formbricks.com/docs/platform/features/integrations/overview Configure third-party integrations with Formbricks Cloud. At Formbricks, we understand the importance of integrating with third-party applications. We have step-by-step guides to configure our third-party integrations with Formbricks Cloud. > [!NOTE] > > For automations that stay inside Formbricks — without a third-party tool — use [Workflows](/docs/workflows/overview) to trigger actions like sending an email when a response is completed. > [!NOTE] > > If you are on a self-hosted instance, you will need to configure these integrations manually. Please follow the guides [here](/docs/self-hosting/configuration/integrations) to configure integrations on your self-hosted instance. * [ActivePieces](/docs/platform/features/integrations/activepieces) (Open Source): Automate workflows with ActivePieces no-code automation tool * [Airtable](/docs/platform/features/integrations/airtable): Automatically send responses to an Airtable of your choice. * [Attio](/docs/platform/features/integrations/attio): Create or update Attio records automatically when survey responses are submitted. * [Google Sheets](/docs/platform/features/integrations/google-sheets): Automatically send responses to a Google Sheet of your choice. * [HubSpot](/docs/platform/features/integrations/hubspot): Create or update HubSpot contacts automatically when survey responses are submitted. * [Make](/docs/platform/features/integrations/make): Leverage Make's powerful automation capabilities to automate your workflows. * [n8n](/docs/platform/features/integrations/n8n)(Open Source): Automate workflows with n8n's no-code automation tool * [Notion](/docs/platform/features/integrations/notion): Automatically send responses to a Notion database of your choice. * [Salesforce](/docs/platform/features/integrations/salesforce): Create Salesforce leads or contacts automatically when survey responses are submitted. * [Slack](/docs/platform/features/integrations/slack): Automatically send responses to a Slack channel of your choice on response events. * [Webhooks](/docs/platform/features/integrations/webhooks): Send real-time HTTP notifications to any endpoint of your choice when responses come in. * [Wordpress](/docs/platform/features/integrations/wordpress)(Open Source): Automatically integrate your Formbricks surveys with your Wordpress website. * [Zapier](/docs/platform/features/integrations/zapier): Connect Formbricks with 2000+ apps on Zapier. *** If you have any questions or need help with any of the integrations or even want a new integration, please reach out to us on [Github Discussions](https://github.com/formbricks/formbricks/discussions). # Salesforce Source: https://formbricks.com/docs/platform/features/integrations/salesforce Learn how to integrate Formbricks with Salesforce to automatically create or update contacts when survey responses are submitted. > [!NOTE] > > There is no native Salesforce integration yet. Connect Formbricks to Salesforce with Make (recommended), n8n, or a custom webhook. ## Prerequisites * A Formbricks survey that collects email addresses * A Salesforce edition with API access (Enterprise, Unlimited, Developer, or Professional with the API add-on) * A Make or n8n account, unless you build a custom webhook *** ## Method 1: Make.com (recommended) Make is a registered Salesforce app, so you only need to log in and click **Allow**. No Salesforce app setup is required. **1. Set Question IDs** Give each question a meaningful `questionId` so mapping is easier. These can only be changed before publishing; for a published survey, duplicate it first. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=34ef2a99e6353651275474585b319bd6) **2. Add the Formbricks Trigger** In a new [Make](https://make.com) scenario, add **Formbricks** → **Watch Response Finished**. Click **Create a webhook**, enter your API host (default `https://app.formbricks.com`) and [API key](/docs/api-reference/rest-api#how-to-generate-an-api-key), and select your survey. ![Search Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/search-formbricks.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ccc17e459b6999a6e5c9a2853548bda) ![Enter API Key](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/make/enter-api-key-and-host.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=635a6374fc27d2f5935dbf1204937c7a) **3. Add the Salesforce Module** Add **Salesforce** → **Create a Record**. Next to **Connection**, click **Add**, log in, and click **Allow**. Set **Type** to **Contact** for existing customers, or **Lead** for new prospects. **4. Map Fields** | Salesforce Field | Formbricks Field | | - | - | | Email | `data.email` | | First Name | `data.firstName` | | Last Name (required) | `data.lastName` | | Account (Contact only) | Optional, but Contacts without one are private to their owner | | Company (Lead only) | Required unless your org uses Person Accounts | | Custom Field | Any `data.*` or `meta.*` field | **5. Avoid Duplicates** Salesforce doesn't match on email by default. Add a **Search Records** module before the create step and route existing matches to **Update a Record**. **6. Test and Activate** Submit a test response, confirm the record in Salesforce, and turn on the scenario. ![Formbricks to Salesforce Scenario](https://mintcdn.com/formbricks/AHOlYlDNSsZMoYm0/images/platform/features/integrations/make/salesforce-scenario.webp?fit=max\&auto=format\&n=AHOlYlDNSsZMoYm0\&q=85\&s=e88a1725854a08765a0c3bdec85ea7ff) *** ## Method 2: n8n The built-in Salesforce node works on n8n Cloud and self-hosted, but needs a Salesforce app for OAuth login. The Formbricks trigger is a community node for self-hosted n8n; on n8n Cloud, use a **Webhook** node as the trigger with a Formbricks webhook pointing at it. The Webhook node nests the request under `body`, so use `$json.body.data.data.*` in place of `$json.data.data.*` in the expressions below. **1. Add the Formbricks Trigger** Install `@formbricks/n8n-nodes-formbricks` via **Settings** → **Community Nodes**. Then add the **Formbricks** trigger node, connect your API key and host, select **Response Finished**, and choose your survey. ![Add Formbricks Trigger](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/n8n/add-formbricks-trigger.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6ec754cf7fb282ae800595341304a2ea) **2. Create a Salesforce App** In Salesforce, go to **Setup** → **App Manager** → **New External Client App** (or **New Connected App**). Enable OAuth, set the callback URL n8n shows you (`https:///rest/oauth2-credential/callback`), and add the `api` and `refresh_token, offline_access` scopes. Copy the Consumer Key and Secret. **3. Add the Salesforce Node** Choose **Contact** → **Create or Update**, create a Salesforce OAuth2 credential with the key and secret, and click **Connect my account**. **4. Map Fields** Create or Update needs an external ID field to match on, such as a custom `Email__c` field on Contact marked as External ID and Unique. Set **Match Against** to `Email__c` and **Value to Match** to `{{ $json.data.data.email }}`, then map: ``` Email: {{ $json.data.data.email }} First Name: {{ $json.data.data.firstName }} Last Name: {{ $json.data.data.lastName }} ``` **5. Test and Activate** Click **Listen for event**, submit a test response, confirm the record in Salesforce, and activate the workflow. *** ## Method 3: Custom webhook (advanced) Use this only if you want to avoid Make or n8n. Your handler authenticates with the OAuth 2.0 Client Credentials Flow. ### Set up an External Client App **1. Create the App** Go to **Setup** → **App Manager** → **New External Client App**, and set Distribution State to **Local**. **2. Configure OAuth** Enable OAuth, use any callback URL (e.g. `https://login.salesforce.com/services/oauth2/callback`), and select **only** the `api` scope. Enable **Client Credentials Flow** and save. **3. Set the Run As User** In **External Client Apps Manager** → your app → **Policies**, set **Run As** to an active, full-license user with **API Enabled** and create/edit access on Contact. **4. Copy the Credentials** On the **Settings** tab, click **Consumer Key and Secret** and copy them. Changes can take a few minutes to apply. See [Salesforce's Client Credentials Flow guide](https://help.salesforce.com/s/articleView?id=xcloud.configure_client_credentials_flow_for_external_client_apps.htm) for details. ### Build the handler **1. Create a Formbricks Webhook** Go to **Configuration** → **Integrations** → **Manage Webhooks** → **Add Webhook**, enter your endpoint URL, select **Response Finished**, and choose your surveys. **2. Write the Handler** 1. Read the answers from `data.data` (keyed by `questionId`). 2. Get a token: `POST https://YOUR_DOMAIN.my.salesforce.com/services/oauth2/token` with `grant_type=client_credentials`. 3. Create the Contact: `POST /services/data/vXX.0/sobjects/Contact`. 4. To avoid duplicates, query by email first and `PATCH` any match, or upsert via an external ID: `PATCH /sobjects/Contact/Email__c/jane@example.com`. For signature verification, see [Webhooks](/docs/platform/features/integrations/webhooks). **3. Deploy and Test** Deploy the handler to a public URL, submit a test response, and confirm the record in Salesforce. *** ## Troubleshooting **No record created** * Check that you're mapping the correct email `questionId`. * Contacts require `LastName`; Leads also require `Company` unless your org uses Person Accounts. **Duplicate records** * Add a search-then-update step, or upsert on an external ID. **Authentication errors (Method 3)** * `no client credentials user enabled`: set a valid **Run As** user under **Policies**. * `no valid scopes defined`: make sure the `api` scope is selected; Client Credentials ignores `full` and `refresh_token`. * Expired token or blocked IP: request a new token on 401, and check Trusted IP Ranges. **Webhook not firing** * Check the URL is public, **Response Finished** is selected, and the survey is linked. *** Need help? Ask in [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Slack Source: https://formbricks.com/docs/platform/features/integrations/slack The slack integration allows you to automatically send responses to a Slack channel of your choice. > [!NOTE] > > If you are on a self-hosted instance, you will need to configure this integration separately. Please follow the guides [here](/docs/self-hosting/configuration/integrations) to configure integrations on your self-hosted instance. ## Formbricks Cloud 1. Click on the `Configuration` tab in the left sidebar and then click on the `Integrations` tab and click on the `connect` button under the `Slack` card. ![Formbricks Integrations Tab](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=728e2554111b6f69ee7dd32f1d2fb457) 1. Now click on the "Connect with Slack" button to authenticate yourself with Slack. ![Connect Formbricks with your Slack Workspace](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/connect-with-slack.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=767f1d3adeb7e805853e07117d20a860) 1. You will now be taken to the Slack OAuth page where you can select the Slack channel you want to link with Formbricks and click on the "Allow" button. ![Slack OAuth Page](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/slack-auth.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=59850040792bdf674efa9bb3c4507a35) 1. Once you have selected the account and completed the authentication process, you will be taken back to Formbricks Cloud and see the connected status as below: ![Formbricks is now connected with Slack](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/slack-connected.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4ee295c2b24719c941fff4997a7a3b3d) > [!NOTE] > > Before the next step, make sure that you have a Formbricks Survey with at > least one question and a Slack channel in the Slack workspace you integrated. 1. In order to make your channel available in channel dropdown, you need to add formbricks integration bot to the channel you want to link. You can do this by going to channel settings -> Integrations -> Add apps -> Search for "Formbricks" -> Select the bot -> Add. ![Click on three dot at top right of the channel](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/add-slack-bot-1.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=c09191adda1457b47c247aac339a7445) ![Select Edit Settings](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/add-slack-bot-2.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=8c0be9bb27b8e1a8bcee6e815cd8b15a) ![Navigate to Integrations](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/add-slack-bot-3.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=21655bf8a1c359a8867bdcbb0fea47de) ![Add Formbricks Bot](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/add-slack-bot-4.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=76392dcd174203c676000938713e61a9) 1. Now click on the "Link channel" button to link a Slack channel with Formbricks and a modal will open up. ![Link Formbricks with a Slack Channel](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/link-survey-with-channel.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=4a7466af414dddd7a6e8602ee920c593) 1. Select the channel you want to link with Formbricks and the Survey. On doing so, you will be asked to select the questions' responses you want to feed in the Slack channel. Select the questions and click on the "Link Channel" button. ![Select question to link with Slack Channel](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/link-with-questions.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=66f99ac3669a1d9445c15294f2fbc130) 1. On submitting, the modal will close and you will see the linked Slack channel in the list of linked Slack channels. ![List of linked Slack Channels](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/list-linked-surveys.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=fc20d748d24cac2d4dd536c02cb8eb23) Congratulations! You have successfully linked a Slack channel with Formbricks. Now whenever a response is submitted for the linked survey, it will be automatically sent to the linked Slack channel. ## Setup in self-hosted Formbricks Enabling the Slack Integration in a self-hosted environment requires a setup using slack workspace account and changing the environment variables of your Formbricks instance. > [!NOTE] > > If you are running Formbricks locally: > > You need to use `https` instead of `http` for the redirect URI. > > * You can update the `go` script in your `apps/web/package.json` to include the `--experimental-https` flag. The > command will look like: \\ > > ```bash theme={null} > "go": next dev --experimental-https -p 3000 > ``` > > * You also need to update the .env file in the `apps/web` directory to include the `WEBAPP_URL` as `https://localhost:3000` instead of `http://localhost:3000`. > > * You also need to run the terminal in admin mode to run the `go` script(to acquire the SSL certificate). You can do this by running the terminal as an administrator or using the `sudo` command in Unix-based systems. 1. Create a Slack workspace if you don't have one already. 2. Go to the [Your apps](https://api.slack.com/apps) page and **Create New App**. 3. Click on **From Scratch** and provide the **App Name** and select your workspace in **Pick a workspace to develop your app in:** dropdown. Click on **Create App**. 4. Go to the **OAuth & Permissions** tab on the sidebar and add the following **Bot Token Scopes**: * `channels:read` * `groups:read` * `chat:write` * `chat:write.public` * `chat:write.customize` 5. Add the **Redirect URLs** under **OAuth & Permissions** tab. You can add the following URLs: * If you are running formbricks locally, you can enter `https://localhost:3000/api/v1/integrations/slack/callback`. * Or, you can enter `https:///api/v1/integrations/slack/callback` 6. Now, click on **Install to Workspace** and **Allow** the permissions. 7. Go to the **Basic Information** tab on the sidebar and copy the **Client ID** and **Client Secret**. Copy them and set them as the environment variables in your Formbricks instance as: * `SLACK_CLIENT_ID` - OAuth Client ID * `SLACK_CLIENT_SECRET` - OAuth Client Secret 1. Now, you need to enable the public distribution of your app. Go to the **Basic Information** tab and click on the **Manage distribution** button and click on the "Distribute App". 2. Scroll down to the **Share your app with other workspaces** section, complete the checklist and click on the **Activate public distribution** button. ### By now, your environment variables should include the below ones: * `SLACK_CLIENT_ID` * `SLACK_CLIENT_SECRET` Voila! You have successfully enabled the Slack integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Formbricks Cloud](#formbricks-cloud) section to link a Slack workspace with Formbricks. ## Remove Integration with Slack Workspace To remove the integration with Slack Workspace, 1. Visit the Integrations tab in your Formbricks Cloud dashboard. 2. Select "Manage" button in the Slack card. 3. Click on the "Delete Integration" button. 4. It will now ask for a confirmation to remove the integration. Click on the "Delete" button to remove the integration. You can always come back and connect again with the same Slack Workspace. ![Delete Slack Integration with Formbricks](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/slack/delete-connection.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=25119d65a8654d53f7813ee636d22c78) Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Webhooks Source: https://formbricks.com/docs/platform/features/integrations/webhooks With webhooks, you can receive real-time HTTP notifications when specific objects change in your Formbricks environment. This allows you to stay updated and trigger automated actions based on these events. ### **Webhook Triggers** Webhooks are configured to send notifications based on trigger events. The available triggers include: * **`responseCreated`** * **`responseUpdated`** * **`responseFinished`** *** ## **Creating Webhooks** You can create webhooks either through the **Formbricks App UI** or programmatically via the **Webhook API**. ## **Creating Webhooks via UI** * **Log in to Formbricks** and click on the `Configuration` tab in the left sidebar and then click on the `Integrations` tab. ![Step one](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/webhooks/integrations-tab.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=6701827c1d1c7b24eaec63f2c3450601) * Click on **Manage Webhooks** & then **Add Webhook** button: ![Step two](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738094259/j4a92z2q43twgamogpny.webp) * Add your webhook listener endpoint and test it to make sure the endpoint is reachable and accepts `POST` requests. ![Step three](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738094617/image_kubsnz.jpg) * Now add the triggers you want to listen to and the surveys! * That’s it! Your webhooks will now start receiving data as soon as it arrives! ![Step five](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738094816/image_xvrel1.jpg) ## **Creating Webhooks via API** Use our documented methods on the **Creation**, **List**, and **Deletion** endpoints of the Webhook API mentioned in our [API v2 playground](https://formbricks.com/docs/api-v2-reference/management-api-%3E-webhooks/get-webhooks). ## Testing Webhooks Locally If you want to test a webhook consumer running on your machine before deploying it, you can expose your local endpoint with [ngrok](https://ngrok.com/docs/universal-gateway/http). **1. Start your local webhook listener** Run your local endpoint on a port like `3000`. **2. Expose it with ngrok** Create a public HTTPS URL for your local service, for example with `ngrok http http://localhost:3000`. **3. Use the public URL in Formbricks** Paste the ngrok URL into your webhook endpoint, click **Test Endpoint**, and then save the webhook once the endpoint is reachable. > [!NOTE] > > To avoid sending unwanted test responses to production workflows, create a separate test survey in your > Workspace and use that survey copy in your development workflow while validating the webhook setup. ### Allowing Internal URLs (Self-Hosted Only) By default, Formbricks blocks webhook URLs that point to private or internal IP addresses (e.g. `localhost`, `192.168.x.x`, `10.x.x.x`) to prevent [SSRF attacks](https://owasp.org/www-community/attacks/Server-Side_Request_Forgery). If you are self-hosting Formbricks and need to send webhooks to internal services, you can set the following environment variable: ```sh theme={null} DANGEROUSLY_ALLOW_WEBHOOK_INTERNAL_URLS=1 ``` > [!WARNING] > > Only enable this on trusted, self-hosted environments. Enabling this on a publicly accessible instance exposes your server to SSRF risks. If you encounter any issues or need help setting up webhooks, feel free to reach out to us on [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). 😃 *** ## Delivery and Retries Formbricks delivers webhooks asynchronously from a background job runner, one delivery per webhook and event, so a slow or unavailable receiver never delays other webhooks or the rest of response processing. * A delivery counts as successful when your endpoint answers with any `2xx` status within the delivery timeout (5 seconds by default; self-hosters can change it with `WEBHOOK_DELIVERY_TIMEOUT_MS`). * Network errors, timeouts, redirects, and `408`, `429` or `5xx` responses are **attempted up to 5 times** with an exponential backoff starting at 30 seconds — roughly 30 seconds, then 1, 2 and 4 minutes after the first attempt. After the last attempt the event is dropped; Formbricks does not replay exhausted deliveries. * Any other `4xx` response is treated as a rejection of the request and is **not** retried. Respond with `2xx` as soon as you have durably accepted the event, and do your own processing afterwards. * Every attempt of the same event carries the same `webhook-id` header, so you can safely deduplicate retries on your side. * Deleting a webhook, or removing a trigger or survey from it, also cancels deliveries that are still queued or retrying for it. ## Webhook Security with Standard Webhooks Formbricks implements the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks) specification to ensure webhook requests can be verified as genuinely originating from Formbricks. ### Webhook Headers Every webhook request includes the following headers: | Header | Description | Example | | - | - | - | | `webhook-id` | Unique message identifier | `019ba292-c1f6-7618-aaf2-ecf8e39d1cc7` | | `webhook-timestamp` | Unix timestamp (seconds) when the webhook was sent | `1704547200` | | `webhook-signature` | HMAC-SHA256 signature (only if secret is configured) | `v1,K3Q2bXlzZWNyZXQ=` | ### Signing Secret When you create a webhook (via the UI or API), Formbricks automatically generates a unique signing secret for that webhook. The secret follows the Standard Webhooks format: `whsec_` followed by a base64-encoded random value. **Via UI:** After creating a webhook, the signing secret is displayed immediately. Copy and store it securely—you can also view it later in the webhook settings. **Via API:** The signing secret is returned in the webhook creation response. This secret is used to generate the HMAC signature included in each webhook request, allowing you to verify the authenticity of incoming webhooks. ### Signature Verification The signature is computed as follows: ``` signed_content = "{webhook-id}.{webhook-timestamp}.{body}" signature = base64(HMAC-SHA256(secret, signed_content)) header_value = "v1,{signature}" ``` ### Validating Webhooks To validate incoming webhook requests: 1. Extract the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers 2. Verify the timestamp is within an acceptable tolerance (e.g., 5 minutes) to prevent replay attacks 3. Decode the secret by stripping the `whsec_` prefix and base64 decoding the rest 4. Compute the expected signature using HMAC-SHA256 with the decoded secret 5. Compare your computed signature with the received signature (after stripping the `v1,` prefix) ### Node.js Verification Functions ```javascript theme={null} const crypto = require("crypto"); const WEBHOOK_TOLERANCE_IN_SECONDS = 300; // 5 minutes /** * Decodes a Formbricks webhook secret (whsec_...) to raw bytes */ function decodeSecret(secret) { const base64 = secret.startsWith("whsec_") ? secret.slice(6) : secret; return Buffer.from(base64, "base64"); } /** * Verifies the webhook timestamp is within tolerance * @throws {Error} if timestamp is too old or too new */ function verifyTimestamp(timestampHeader) { const now = Math.floor(Date.now() / 1000); const timestamp = parseInt(timestampHeader, 10); if (isNaN(timestamp)) { throw new Error("Invalid timestamp"); } if (Math.abs(now - timestamp) > WEBHOOK_TOLERANCE_IN_SECONDS) { throw new Error("Timestamp outside tolerance window"); } return timestamp; } /** * Computes the expected signature for a webhook payload */ function computeSignature(webhookId, timestamp, body, secret) { const signedContent = `${webhookId}.${timestamp}.${body}`; const secretBytes = decodeSecret(secret); return crypto.createHmac("sha256", secretBytes).update(signedContent).digest("base64"); } /** * Verifies a Formbricks webhook request * @param {string} body - Raw request body as string * @param {object} headers - Object containing webhook-id, webhook-timestamp, webhook-signature * @param {string} secret - Your webhook secret (whsec_...) * @returns {boolean} true if valid * @throws {Error} if verification fails */ function verifyWebhook(body, headers, secret) { const webhookId = headers["webhook-id"]; const webhookTimestamp = headers["webhook-timestamp"]; const webhookSignature = headers["webhook-signature"]; if (!webhookId || !webhookTimestamp || !webhookSignature) { throw new Error("Missing required webhook headers"); } // Verify timestamp const timestamp = verifyTimestamp(webhookTimestamp); // Compute expected signature const expectedSignature = computeSignature(webhookId, timestamp, body, secret); // Extract signature from header (format: "v1,{signature}") const receivedSignature = webhookSignature.split(",")[1]; if (!receivedSignature) { throw new Error("Invalid signature format"); } // Use constant-time comparison to prevent timing attacks const expectedBuffer = Buffer.from(expectedSignature, "utf8"); const receivedBuffer = Buffer.from(receivedSignature, "utf8"); if ( expectedBuffer.length !== receivedBuffer.length || !crypto.timingSafeEqual(expectedBuffer, receivedBuffer) ) { throw new Error("Invalid signature"); } return true; } module.exports = { verifyWebhook, decodeSecret, computeSignature, verifyTimestamp }; ``` **Usage:** ```javascript theme={null} // In your webhook handler, use the raw body (not parsed JSON) try { verifyWebhook(rawBody, req.headers, process.env.FORMBRICKS_WEBHOOK_SECRET); const payload = JSON.parse(rawBody); // Process verified webhook... } catch (error) { // Verification failed - reject the request console.error("Webhook verification failed:", error.message); } ``` > [!NOTE] > > Always use the **raw request body** (as a string) for signature verification, not the parsed JSON object. > Parsing and re-stringifying can change the formatting and break signature validation. ### Using Standard Webhooks Libraries You can also use the official [Standard Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks#libraries) available for various languages: * **Node.js**: `npm install standardwebhooks` * **Python**: `pip install standardwebhooks` * **Go, Ruby, Java, Kotlin, PHP, Rust**: See the [Standard Webhooks GitHub](https://github.com/standard-webhooks/standard-webhooks) *** ## Example Webhook Payloads We provide the following webhook payloads, `responseCreated`, `responseUpdated`, and `responseFinished`. ### Response Created Example of Response Created webhook payload: ```json theme={null} { "data": { "contact": null, "contactAttributes": null, "createdAt": "2025-07-24T07:47:29.507Z", "data": { "welcome_card_cta": "clicked" }, "displayId": "displayId", "endingId": null, "finished": false, "id": "responseId", "language": "en", "meta": { "country": "DE", "url": "https://app.formbricks.com/s/surveyId", "userAgent": { "browser": "Chrome", "device": "desktop", "os": "macOS" } }, "singleUseId": null, "survey": { "createdAt": "2025-07-20T10:30:00.000Z", "status": "inProgress", "title": "Customer Satisfaction Survey", "type": "link", "updatedAt": "2025-07-24T07:45:00.000Z" }, "surveyId": "surveyId", "tags": [], "ttc": { "welcome_card_cta": 2154.700000047684 }, "updatedAt": "2025-07-24T07:47:29.507Z", "variables": {} }, "event": "responseCreated", "webhookId": "webhookId" } ``` ### Response Updated Example of Response Updated webhook payload: ```json theme={null} { "data": { "contact": null, "contactAttributes": null, "createdAt": "2025-07-24T07:47:29.507Z", "data": { "visit_reason": "Just browsing", "welcome_card_cta": "clicked" }, "displayId": "displayId", "endingId": null, "finished": false, "id": "responseId", "language": "en", "meta": { "country": "DE", "url": "https://app.formbricks.com/s/surveyId", "userAgent": { "browser": "Chrome", "device": "desktop", "os": "macOS" } }, "singleUseId": null, "survey": { "createdAt": "2025-07-20T10:30:00.000Z", "status": "inProgress", "title": "Customer Satisfaction Survey", "type": "link", "updatedAt": "2025-07-24T07:45:00.000Z" }, "surveyId": "surveyId", "tags": [], "ttc": { "visit_reason": 3855.799999952316, "welcome_card_cta": 2154.700000047684 }, "updatedAt": "2025-07-24T07:47:33.696Z", "variables": {} }, "event": "responseUpdated", "webhookId": "webhookId" } ``` ### Response Finished Example of Response Finished webhook payload: ```json theme={null} { "data": { "contact": null, "contactAttributes": null, "createdAt": "2025-07-24T07:47:29.507Z", "data": { "newsletter_consent": "accepted", "welcome_card_cta": "clicked" }, "displayId": "displayId", "endingId": "endingId", "finished": true, "id": "responseId", "language": "en", "meta": { "country": "DE", "url": "https://app.formbricks.com/s/surveyId", "userAgent": { "browser": "Chrome", "device": "desktop", "os": "macOS" } }, "singleUseId": null, "survey": { "createdAt": "2025-07-20T10:30:00.000Z", "status": "inProgress", "title": "Customer Satisfaction Survey", "type": "link", "updatedAt": "2025-07-24T07:45:00.000Z" }, "surveyId": "surveyId", "tags": [], "ttc": { "_total": 4947.899999035763, "newsletter_consent": 2793.199999988079, "welcome_card_cta": 2154.700000047684 }, "updatedAt": "2025-07-24T07:47:56.116Z", "variables": {} }, "event": "responseFinished", "webhookId": "webhookId" } ``` # Wordpress Source: https://formbricks.com/docs/platform/features/integrations/wordpress Target specific visitors with a survey on your WordPress page using Formbricks for free. Show survey on specific page or on button click. To run a targeted survey on your WordPress website, Formbricks is the way to go! With our generous free plan and open source tech, you get everything you need to get started and keep full control over your data. ## TLDR 1. Install the Formbricks WordPress plugin 2. Create a [free Formbricks account](https://app.formbricks.com/auth/signup) 3. Find and copy the `workspaceId` 4. Copy the `workspaceId` into the right field in the plugin settings 5. Create survey on trigger “New Session” to test it ## Step 1: Install the Formbricks WordPress plugin As long as the Formbricks plugin is in review, please download it from our [GitHub repository directly.](https://github.com/formbricks/wordpress) ![Run targeted website survye on any WordPress site](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/wordpress/1-wordpress-targeted-survey-on-website-free.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=a76bfff14611e37fb3023d650d0ae2b3) ## Step 2: Create a Formbricks Account This is super straight forward: Go to [app.formbricks.com/auth/signup](https://app.formbricks.com/auth/signup), create the account, verify your email and you’re in! When you see this screen, you’re there: ![Free HotJar survey alternative open source](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/wordpress/2-run-website-survey-wordpress-targeted-for-free.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=cddb18fcbe224e74543aac7dddd71456) ## Step 3: Find and copy the workspaceId Go to **Settings → Workspace → Web & Mobile SDK** where the **Workspace details** card holds your workspaceId: ![The Workspace details card on the Web & Mobile SDK settings page, showing Your Workspace ID and SDK Connection URL](https://mintcdn.com/formbricks/AHOlYlDNSsZMoYm0/images/platform/features/integrations/wordpress/3-wordpress-setup-survey-on-website-targeted-free-open-source.webp?fit=max\&auto=format\&n=AHOlYlDNSsZMoYm0\&q=85\&s=a70da295a6ee59caf6d6bd3e98028fb9) ## Step 4: Copy the workspaceId to the WordPress Plugin Settings In your WordPress instance, go to the Formbricks Plugin settings and copy the workspaceId in the correct field: ![Free and open source HotJar survey on WordPress page](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/wordpress/step-4-copy-to-wordpress-for-free-targeted-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=8c8fa8dcc10669cd6a90528a7fb18d68) Then click the button at the bottom to see if the connection worked. > [!NOTE] > > If you don’t use our Cloud, you also have to update the API Host Great! ## Step 5: Create survey on trigger “New Session” Now that all is setup, we create a survey to display an example survey. Create a survey and open survey editor. Keep the content for now, click on the Settings tab: ![Free and open source HotJar survey on WordPress page](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/wordpress/4-wordpress-website-survey-target-visitor-free.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=80afd3b6226a90a41d3f03cdbba06ae3) Here we do three things: 1. Change survey type to **App Survey** or **Website Survey**(for public facing) 2. Select trigger “New Session” 3. Publish ![Open Source survey on targeted website wordpress](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/wordpress/6-targeted-survey-on-wordpress-website-for-free.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=8fe522da324ec001cafd5ef27f88125c) When you see this page, you did it! ![Run free an open source targeted survey on any page](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/wordpress/7-wordpress-free-hotjar-survey-open-source-website-survey-hotjar.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=e81b1d8f9fa9b3b3e77fdaf9188c7cbc) ## Step 6: Reload your page to check out your survey 🤓 You did it! Reload the WordPress page and your survey should appear! ## Doesn't work? If you have any questions or need help, feel free to reach out to us on [Github Discussions](https://github.com/formbricks/formbricks/discussions) # Zapier Source: https://formbricks.com/docs/platform/features/integrations/zapier Master the integration of Formbricks with Zapier using our detailed guide. Seamlessly connect your surveys to 5000+ apps, automate data transfers, and enhance feedback management. Start optimizing your workflow today. > [!NOTE] > > Nail down your survey first? Any changes in the survey cause additional work in the Zap. It makes sense to first settle on the survey you want to run and then get to setting up Zapier. ## Step 1: Setup your survey incl. `questionId` for every question When setting up the Zap your life will be easier when you change the `questionId`s of your survey questions. You can only do so **before** you activate your survey. ![Update Question ID](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/update-question-id.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=06481917e5cd8b25bd0bb21b7f09dada) *The Question ID is the first field behind **Show Question settings** at the foot of a question card. Update it so you will recognise the response tied to this question.* > [!NOTE] > > Already activated? Duplicate survey You can only update the questionId > when the survey was not yet activated. Already activated it? Just **duplicate > it** to update the questionIds. > > ![Duplicate Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/duplicate-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=832f19037161f9f49823545d3ca01c66) ## Step 2: Send a test response In order to set up Zapier you’ll need a test response. This allows you to select the individual values of each response in your Zap. ![Submit Test Response](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/submit-test-response.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=91b0472a96c682079bd160314ed4bf6a) ## Step 3: Setup your Zap Go to [zapier.com](https://zapier.com) and create a new Zap. Search for “Formbricks” to get started: ![Add New Zap](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/add-new-zap.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=2d1e85269365c1dba422cb2995c5e125) Then, choose the event you want to trigger the Zap on: ![Choose Event](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/choose-event.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=f371db58d6ed4e586f6079417d6992a1) ## Step 4: Connect Formbricks with Zapier Now, you have to connect Zapier with Formbricks via an API Key: ![Connect with Formbricks - 1](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/connect-with-formbricks-1.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=5c95cfcc4fb806c12a0e48ae918316b6) ![Connect with Formbricks - 2](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/connect-with-formbricks-2.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=cab6703bea1c3e5bf8f0f78c0652a863) Now you need an API key. Please refer to the [API Key Setup](/docs/api-reference/generate-key) page to learn how to create one. Once you copied it in the newly opened Zapier window, you will be connected: ![Successful Connection](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/success-connected.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=f9690bd8fdff55244479c886d5bfa6f3) ## Step 5: Select Survey Next, you can choose from all the surveys you have created in this workspace: ![Select Survey](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/select-survey.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=3407e684e7e69d9a6c9a32d0400ba39b) ## Step 6: Test your trigger Once you hit “Test” you will see the three most recent submissions for this survey. If you don’t have any submissions in the survey, submit one to continue setting up your Zap: ![Test Submission](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/test-submission.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=38a52c144d81e3de443e3205a5ae32f6) *Now you're happy that you updated the questionId's* ## Step 7: Set up your Zap Now you have all the data you need at hand. The next steps depend on what you want to do with it. In this tutorial, we will send submissions to a Slack channel: ![Slack Channel Message](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/slack-channel-msg.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=f427df07f7023eb897d5941b34f0485a) In the action itself we can determine the data and layout of the message. Here, we only choose the submission data. You can also refer to the meta data of the submission and the [attributes](/docs/surveys/website-app-surveys/user-identification) of the person who submitted the survey. ![Slack Message](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/slack-message.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=afb5bdde9969edbf0090bf9bf8ec2122) We now receive a notifcation in our Slack channel whenever a Churn survey is completed: ![Zapier Message](https://mintcdn.com/formbricks/ciPr-k8rsK4LGtZI/images/platform/features/integrations/zapier/zapier-message.webp?fit=max\&auto=format\&n=ciPr-k8rsK4LGtZI\&q=85\&s=788e79f55efaa6fb92a6496044802b66) # Styling Theme Source: https://formbricks.com/docs/platform/features/styling-theme Keep the survey styling consistent over all surveys with a Styling Theme. Customize colors, fonts, buttons, inputs, and more to match your brand. > [!NOTE] > > **Self-Hosting Requirements**: Uploading custom background images and brand logos requires file upload > storage to be configured. If you're self-hosting Formbricks, make sure to [configure file > uploads](/docs/self-hosting/configuration/file-uploads) before using these features. Keep the survey styling consistent over all surveys with a Styling Theme. Customize colors, fonts, buttons, inputs, and other styling options to match your brand's aesthetic. ## Configuration In the left sidebar, open **Settings → Workspace → Appearance**: ![The Appearance settings, with the theme editor and a live preview](https://mintcdn.com/formbricks/DFKZFN1IVGbtTOkC/images/platform/features/styling-theme/appearance.webp?fit=max\&auto=format\&n=DFKZFN1IVGbtTOkC\&q=85\&s=a8dfa99df2b84d6ce96235ed8205265e) ### Light And Dark Select **Dark** at the top of the styling settings to set the dark palette used when your app asks for dark mode. Empty fields show the derived color as a placeholder; the brand color is the same in light and dark. Sizes, fonts and layout are shared by both. Link surveys always render light, so **Background styling** (which only applies to link surveys) is unavailable while **Dark** is selected, and the preview's **Link Survey** option is disabled. For a dark link survey, choose a dark background and light text colors in **Light**; the **Cardless** card arrangement lets the background fill the page. You can also switch the preview between light and dark with the sun and moon toggle under it. See [Dark Mode](/docs/surveys/website-app-surveys/framework-guides#dark-mode). ## Survey styling The Survey styling section gives you granular control over every text and input element in your survey. Expand the **Survey styling** panel to find collapsible sub-sections for Headlines & Descriptions, Inputs, Buttons, and Options. ### Headlines & Descriptions Fine-tune how question headlines, descriptions, and upper labels appear: | Property | Description | | - | - | | **Headline Color** | Color of the question headline text | | **Description Color** | Color of the question description text | | **Headline Font Size** | Font size for headlines (in `px` or any CSS unit) | | **Description Font Size** | Font size for descriptions | | **Headline Font Weight** | Numeric font weight for headlines (e.g. `400`, `600`, `700`) | | **Description Font Weight** | Numeric font weight for descriptions | | **Upper Label Color** | Color of the small labels above input fields | | **Upper Label Font Size** | Font size for upper labels | | **Upper Label Font Weight** | Numeric font weight for upper labels | ### Inputs Control the appearance of text inputs, textareas, and other form fields: | Property | Description | | - | - | | **Input Color** | Background color of input fields | | **Input Border Color** | Border color of input fields | | **Input Text Color** | Color of text typed into inputs | | **Border Radius** | Corner roundness of input fields (in `px` or any CSS unit) | | **Height** | Height of input fields | | **Font Size** | Font size of text inside inputs | | **Padding X** | Horizontal padding inside inputs | | **Padding Y** | Vertical padding inside inputs | | **Placeholder Opacity** | Opacity of placeholder text (`0` to `1`) | | **Shadow** | CSS box-shadow value for inputs (e.g. `0 1px 2px rgba(0,0,0,0.1)`) | ### Buttons Customize the submit and navigation buttons: | Property | Description | | - | - | | **Button Background** | Background color of buttons | | **Button Text** | Text color of buttons | | **Border Radius** | Corner roundness of buttons | | **Height** | Height of buttons | | **Font Size** | Font size of button text | | **Font Weight** | Numeric font weight for button text | | **Padding X** | Horizontal padding inside buttons | | **Padding Y** | Vertical padding inside buttons | ### Options Style the select options in single-select, multi-select, and similar question types: | Property | Description | | - | - | | **Option Background** | Background color of option items | | **Option Label Color** | Text color of option labels | | **Border Radius** | Corner roundness of option items | | **Padding X** | Horizontal padding inside options | | **Padding Y** | Vertical padding inside options | | **Font Size** | Font size of option text | ## Card Styling Adjust the look of the survey card container: | Property | Description | | - | - | | **Roundness** | Corner roundness of the survey card (in `px` or any CSS unit) | | **Card Background Color** | Background color of the survey card | | **Card Border Color** | Border color of the survey card | | **Add Highlight Border** | Adds a distinct colored border for emphasis (app surveys only) | | **Card Arrangement** | Layout mode for stacking cards: **Simple**, **Straight**, or **Casual** | ### Progress Bar When the progress bar is visible (toggle **Hide progress bar** to control it), you can customize: | Property | Description | | - | - | | **Track Background** | Background color of the progress track | | **Indicator Background** | Fill color of the progress indicator | | **Track Height** | Height of the progress bar track | ## Background Styling Customize the survey background with static colors, animations, or images (upload your own or pick from Unsplash). > [!NOTE] > > Background styling is only available for Link Surveys. | Property | Description | | - | - | | **Color** | Pick any color for the background | | **Animation** | Add dynamic animations to enhance user experience | | **Upload** | Use a custom uploaded image (5 MB max) | | **Image** | Choose from Unsplash's gallery (attribution shown automatically) | | **Background Overlay** | Adjust the background's opacity / brightness | ## Add Brand Logo Customize your survey with your brand's logo. > [!NOTE] > > Brand logos are only visible on Link Survey pages. 1. In **Settings → Workspace → Appearance**, scroll down to **Logo**. 2. Upload your logo. Logos must be 5 MB or less. 3. Optionally turn on **Add background color** — useful for a transparent logo that needs a solid backdrop. 4. Choose **Save**. The logo only takes effect once saved. ![The Logo section with a logo uploaded](https://mintcdn.com/formbricks/DFKZFN1IVGbtTOkC/images/platform/features/styling-theme/logo.webp?fit=max\&auto=format\&n=DFKZFN1IVGbtTOkC\&q=85\&s=5d4055aaced303cc1afc0fde0bbc3253) > [!NOTE] > > The logo settings apply across all Link Survey pages. ## Overwrite Styling Theme You can allow overwriting the styling theme for individual surveys to create unique styles per survey: ![The Enable custom styling toggle](https://mintcdn.com/formbricks/DFKZFN1IVGbtTOkC/images/platform/features/styling-theme/enable-custom-styling.webp?fit=max\&auto=format\&n=DFKZFN1IVGbtTOkC\&q=85\&s=f7e94fc6498e7f1b60b7cd16af6bfe1c) In the survey editor, a **Styling** tab will appear where you can overwrite the default styling theme. See the [Custom Styling](/docs/surveys/general-features/overwrite-styling) guide for details. ## CSS Variables Reference Under the hood, every styling property maps to a CSS variable prefixed with `--fb-`. For App & Website Surveys, you can override these directly in your global CSS file (e.g., `globals.css`) by targeting the `#fbjs` selector. See the full [CSS Variables Reference](/docs/surveys/general-features/overwrite-styling#overwrite-css-styles-for-app-&-website-surveys) in the Custom Styling guide. To go beyond the theme editor, add [Custom CSS](/docs/surveys/general-features/custom-css) for the whole workspace in **Appearance**, or for a single survey in its **Styling** tab. # User Management Overview Source: https://formbricks.com/docs/platform/features/user-management Manage organization members, roles, teams, and security settings to control access and collaboration in your Formbricks organization. Formbricks provides comprehensive user management capabilities to help you control access, organize teams, and secure your organization. This section covers everything you need to know about managing users, roles, and permissions. ## Key concepts Formbricks uses a flexible permission system with multiple layers: * **Organization roles** - Control access across the entire organization * **Team roles** - Provide granular permissions within specific teams * **Workspace permissions** - Fine-tune access to individual Workspaces * **Security features** - Protect accounts with two-factor authentication > [!NOTE] > > Advanced user management features are part of the [Enterprise Edition](/docs/self-hosting/advanced/license). The Community Edition and Free/Startup Cloud plans support unlimited organization members with Owner permissions. ## Get started > [card] [Organizations and roles](/docs/platform/features/user-management/organizations-and-roles) > > Learn about organization-level roles and how they control access to teams, Workspaces, and data across your Formbricks organization. > [card] [Teams and roles](/docs/platform/features/user-management/teams-and-roles) > > Understand team-level roles and Workspace permissions that enable granular access control within teams and Workspaces. > [card] [Invite members](/docs/platform/features/user-management/invite-members) > > Learn how to invite new members to your organization individually or in bulk, and manage invitation workflows. > [card] [Two-factor authentication](/docs/platform/features/user-management/two-factor-auth) > > Secure your account with an additional layer of protection using time-based codes from authenticator apps and backup codes. # Invite members Source: https://formbricks.com/docs/platform/features/user-management/invite-members Learn how to invite new members to your organization individually or in bulk, and manage invitation workflows. Add new members to your Formbricks organization to collaborate on surveys and manage Workspaces together. You can invite members individually or in bulk using CSV uploads. ## Prerequisites To invite members, you need: * **Owner** or **Manager** role in the organization * Valid email addresses for the people you want to invite ## Individual invitations Use this method when inviting a few people or when you need to carefully control each invitation. ### Steps to invite individual members **1. Navigate to Settings → Organization → Teams** Go to **Settings → Organization → Teams**, where members are managed. ![Access Control Tab](https://mintcdn.com/formbricks/ZCg8IT8zvYLvsj9U/images/xm-and-surveys/core-features/access-roles/access-control.webp?fit=max\&auto=format\&n=ZCg8IT8zvYLvsj9U\&q=85\&s=8172505ebc82fda24fb6b67c31ae521f) **2. Start the invitation process** Click on the `Add member` button: ![Add member Button Position](https://mintcdn.com/formbricks/FxVXbfRFRc8kmKdj/images/xm-and-surveys/core-features/access-roles/add-member.webp?fit=max\&auto=format\&n=FxVXbfRFRc8kmKdj\&q=85\&s=0cf4e351491d083131a80420e699152c) **3. Fill in member details** In the modal, add the Name, Email and Role of the organization member you want to invite: ![Individual Invite Modal Tab](https://mintcdn.com/formbricks/FxVXbfRFRc8kmKdj/images/xm-and-surveys/core-features/access-roles/individual-invite.webp?fit=max\&auto=format\&n=FxVXbfRFRc8kmKdj\&q=85\&s=463b6a8c306e0dbd5a363769cf50b1e9) **4. Send the invitation** Click the invite button to send the invitation email. ### What happens next 1. Formbricks sends an email to the organization member with an invitation link 2. The organization member can accept the invitation or create a new account by clicking on the link 3. Once accepted, they'll have access based on the role you assigned ## Bulk invitations Use bulk invitations when you need to invite many people at once, such as when onboarding an entire team or department. ### Steps to invite members in bulk **1. Navigate to Settings → Organization → Teams** Go to **Settings → Organization → Teams**, where members are managed. **2. Start the bulk invitation process** Click on the `Add member` button: ![Add member Button Position](https://mintcdn.com/formbricks/FxVXbfRFRc8kmKdj/images/xm-and-surveys/core-features/access-roles/add-member.webp?fit=max\&auto=format\&n=FxVXbfRFRc8kmKdj\&q=85\&s=0cf4e351491d083131a80420e699152c) **3. Switch to bulk invite** In the modal, switch to `Bulk Invite`. You can download an example .CSV file to fill in the Name, Email and Role of the organization members you want to invite: ![Individual Invite Modal Tab](https://mintcdn.com/formbricks/FxVXbfRFRc8kmKdj/images/xm-and-surveys/core-features/access-roles/bulk-invite.webp?fit=max\&auto=format\&n=FxVXbfRFRc8kmKdj\&q=85\&s=a818c907297ca32d3d7115ba4cf9b22c) **4. Prepare your CSV file** The CSV file should include three columns: * **Name**: Full name of the person * **Email**: Valid email address * **Role**: One of the available organization roles (Owner, Manager, Billing, Member) **5. Upload and send invitations** Upload the filled .CSV file and invite the organization members in bulk ✅ ### What happens next * Formbricks sends an email to each organization member in the CSV * Each member can accept the invitation or create a new account by clicking on the link * All invitations are processed simultaneously ## Managing invitations ### Pending invitations * View pending invitations under **Settings → Organization → Teams** * Resend invitations if needed * Cancel pending invitations before they're accepted ### Invitation status Monitor the status of your invitations: * **Pending**: Invitation sent but not yet accepted * **Accepted**: User has joined the organization * **Expired**: Invitation has expired and needs to be resent # Organizations and roles Source: https://formbricks.com/docs/platform/features/user-management/organizations-and-roles Understand organization-level roles and how they control access to teams, Workspaces, and data across your Formbricks organization. Organization-level roles apply to all teams and Workspaces within your Formbricks organization. These roles provide broad permissions that determine what users can do across the entire organization. > [!NOTE] > > Access Roles is a feature of the [Enterprise Edition](/docs/self-hosting/advanced/license). In the **Community Edition** and on the **Free** > and **Startup** plan in the Cloud you can invite unlimited organization members as `Owner`. ## Role hierarchy Here are the different access permissions, ranked from highest to lowest access: 1. **Owner** - Full organizational control 2. **Manager** - Management access with some restrictions 3. **Billing** - Billing and payment management only 4. **Member** - Basic access to assigned Workspaces ### Role Permissions and Privilege Escalation Prevention To prevent privilege escalation, the following rules apply: * **Owners** can: * Invite users as owners, managers, or members * Assign roles up to owner level * **Managers** can: * Invite users only as members * Assign roles up to member only, not manager or owner * **Members** cannot: * Invite users * Assign roles ## Organization-level roles All users and their organization-level roles are listed under **Settings → Organization → Teams**. The role dropdown beside each person is where you change one. ![The organization's member list, with a role beside each person](https://mintcdn.com/formbricks/VfxKz9eund_LUynq/images/platform/features/user-management/organizations-and-roles/members.webp?fit=max\&auto=format\&n=VfxKz9eund_LUynq\&q=85\&s=b59a4918a352c9fbf4478536632309f7) Users can hold any of the following org-level roles: ### Owner * Have full access to the organization, its data, and settings * Can perform Team Admin actions without needing to join the team * Can manage all aspects of the organization including billing, integrations, and member management ### Manager * Have full management access to all teams and Workspaces * Can manage the organization's membership (but can only invite or assign users as members) * Can perform Team Admin actions without needing to join the team * Cannot change other organization settings like billing or delete the organization ### Billing * Can manage payment and compliance details in the organization * Have access to billing settings and subscription management * Cannot access other organizational data or settings ### Member * Can view most data in the organization and act in the Workspaces they are members of * Cannot create or join Workspaces on their own and need to be assigned by owners or managers * Have limited permissions that depend on their Workspace-level access ## Detailed permissions matrix | | Owner | Manager | Billing | Member | | - | - | - | - | - | | **Organization** | | | | | | Update organization | ✅ | ❌ | ❌ | ❌ | | Delete organization | ✅ | ❌ | ❌ | ❌ | | Add new member | ✅ | ✅ | ❌ | ❌ | | Delete member | ✅ | ✅ | ❌ | ❌ | | Update member access | ✅ | ✅ | ❌ | ❌ | | Update billing | ✅ | ✅ | ✅ | ❌ | | **Workspace** | | | | | | Create Workspace | ✅ | ✅ | ❌ | ❌ | | Update Workspace name | ✅ | ✅ | ❌ | ✅\*\* | | Update Workspace recontact options | ✅ | ✅ | ❌ | ✅\*\* | | Update look & feel | ✅ | ✅ | ❌ | ✅\*\* | | Update survey languages | ✅ | ✅ | ❌ | ✅\*\* | | Delete Workspace | ✅ | ✅ | ❌ | ❌ | | **Surveys** | | | | | | Create new survey | ✅ | ✅ | ❌ | ✅\* | | Edit survey | ✅ | ✅ | ❌ | ✅\* | | Delete survey | ✅ | ✅ | ❌ | ✅\* | | View survey results | ✅ | ✅ | ❌ | ✅ | | **Response** | | | | | | Delete response | ✅ | ✅ | ❌ | ✅\* | | Add tags on response | ✅ | ✅ | ❌ | ✅\* | | Edit tags on response | ✅ | ✅ | ❌ | ✅\* | | Download survey responses (CSV) | ✅ | ✅ | ❌ | ✅\* | | **Actions** | | | | | | Create action | ✅ | ✅ | ❌ | ✅\* | | Update action | ✅ | ✅ | ❌ | ✅\* | | Delete action | ✅ | ✅ | ❌ | ✅\* | | **API keys** | | | | | | Create API key | ✅ | ✅ | ❌ | ✅\*\* | | Update API key | ✅ | ✅ | ❌ | ✅\*\* | | Delete API key | ✅ | ✅ | ❌ | ✅\*\* | | **Tags** | | | | | | Create tags | ✅ | ✅ | ❌ | ✅\* | | Update tags | ✅ | ✅ | ❌ | ✅\* | | Delete tags | ✅ | ✅ | ❌ | ✅\*\* | | **Contacts** | | | | | | Delete contact | ✅ | ✅ | ❌ | ✅\* | | **Integrations** | | | | | | Manage integrations | ✅ | ✅ | ❌ | ✅\* | \* - for the read & write permissions team members \*\* - for the manage permissions team members ## Best practices * **Principle of least privilege**: Assign users the minimum role necessary for their responsibilities * **Regular audits**: Periodically review organization members and their roles * **Owner role**: Limit the number of owners to reduce security risk * **Manager role**: Use for team leads who need to manage Workspaces but not organizational settings # Teams and roles Source: https://formbricks.com/docs/platform/features/user-management/teams-and-roles Learn about team-level roles and workspace permissions that enable granular access control within teams and workspaces. Team-level roles provide more granular permissions within specific teams and workspaces. These roles work alongside organization-level roles to create a flexible permission system. > [!NOTE] > > Team-level roles are a feature of the [Enterprise Edition](/docs/self-hosting/advanced/license). In the Community Edition, all members are Organisation-level "Owners". ## Understanding the role hierarchy Formbricks uses a two-tier permission system: 1. **Organization-level roles** - Apply across all teams and workspaces 2. **Team-level roles** - Apply within specific teams and workspaces ### How roles interact * Organization-level roles (Owner, Manager) can override team-level restrictions * Team-level roles provide granular control for specific teams * Workspace permissions further refine what users can do within individual workspaces Teams live under **Settings → Organization → Teams**, below the member list. ![The Teams card, listing each team and its size](https://mintcdn.com/formbricks/VfxKz9eund_LUynq/images/platform/features/user-management/teams-and-roles/teams.webp?fit=max\&auto=format\&n=VfxKz9eund_LUynq\&q=85\&s=fecd2b70d8fc5e8a4fab5fa492da986d) ## Team-level roles ### Team Admins * Have additional permissions to manage their team's membership and workspaces * Can add or remove team members * Can create and manage workspaces within their team * Can assign workspace-level permissions to team members * These permissions are granted at the team-level and don't apply to teams where they're not a Team Admin ### Team Contributors * Can view and act on surveys and responses within their assigned workspaces * Cannot manage team membership or create new workspaces * Permissions depend on their workspace-level access (Read, Read & Write, or Manage) ## Workspace-level permissions A team is granted access to a workspace one workspace at a time, under **Settings → Workspace → Team Access**. The permission there decides what the team's members can do in that workspace. ![Team Access, showing each team's permission on this workspace](https://mintcdn.com/formbricks/VfxKz9eund_LUynq/images/platform/features/user-management/teams-and-roles/workspace-access.webp?fit=max\&auto=format\&n=VfxKz9eund_LUynq\&q=85\&s=cb61bc0ad8224a6d9ed643a642d43339) Within each workspace, team members can have one of three permission levels: ### Read * Read access to all resources (except settings) in the workspace * Can view surveys, responses, and analytics * Cannot create, edit, or delete surveys * Cannot modify workspace settings ### Read & Write * Read & write access to all resources (except settings) in the workspace * Can create, edit, and delete surveys * Can manage responses and tags * Can download survey data * Cannot modify workspace settings or manage integrations ### Manage * Read & write access to all resources including settings in the workspace * Full workspace control including settings * Can manage API keys and integrations * Can configure workspace-level settings like recontact options and styling * Can manage workspace tags and actions ## Permission examples ### Scenario 1: Marketing Team Member * **Organization role**: Member * **Team role**: Team Contributor * **Workspace permission**: Read & Write * **Can do**: Create and edit surveys, view responses, download data * **Cannot do**: Change workspace settings, manage team membership ### Scenario 2: Team Lead * **Organization role**: Member * **Team role**: Team Admin * **Workspace permission**: Manage * **Can do**: Everything within their team including managing members and workspace settings * **Cannot do**: Access other teams, change organization settings ### Scenario 3: Department Manager * **Organization role**: Manager * **Team role**: N/A (org role overrides) * **Workspace permission**: N/A (org role provides access) * **Can do**: Access all teams and workspaces, manage organization membership * **Cannot do**: Change organization-level settings like billing # Two-factor authentication Source: https://formbricks.com/docs/platform/features/user-management/two-factor-auth Secure your account with an additional layer of protection using time-based codes from authenticator apps and backup codes. Two-factor authentication (2FA) adds an extra layer of security to user accounts by requiring a second form of verification in addition to the password. This significantly reduces the risk of unauthorized access even if passwords are compromised. > [!NOTE] > > Two-factor authentication is part of the [Enterprise Edition](/docs/self-hosting/advanced/license). ## Prerequisites To use two-factor authentication, users must: * Have an account with email-based authentication (third-party login providers like Google SSO are not compatible with 2FA) * Have a TOTP-compatible authenticator app installed on their device (such as Google Authenticator, Authy, or 1Password) ## Setting up Two-factor authentication Users can enable 2FA from their profile: 1. Navigate to **Settings → Account → Your Profile** via the menu in the lower right corner 2. In the **Security** section, toggle the **Two-factor authentication** switch ![The Security section of your profile settings](https://mintcdn.com/formbricks/4X_K7DGwdLX4n8Ma/images/platform/features/user-management/two-factor-auth/setup.webp?fit=max\&auto=format\&n=4X_K7DGwdLX4n8Ma\&q=85\&s=29aff2ad674738b824a682e0ce69ca0e) 3. Follow the setup wizard: **Step 1: Confirm Password** * Enter your current password to verify your identity **Step 2: Scan QR Code** * Use your authenticator app to scan the displayed QR code * Alternatively, manually enter the provided secret key into your authenticator app **Step 3: Verify Setup** * Enter the 6-digit code from your authenticator app to confirm the setup **Step 4: Save Backup Codes** * **Important**: Save the 10 backup codes in a secure location * These codes can be used to access your account if you lose access to your authenticator device * Each backup code can only be used once > [!WARNING] > > Store your backup codes in a secure location. If you lose access to both your authenticator device and backup codes, you will need administrator assistance to regain access to your account. ## Logging in with Two-factor authentication Once 2FA is enabled, the login process requires an additional step: 1. Enter your email and password as usual 2. When prompted, enter either: * A 6-digit code from your authenticator app, or * One of your backup codes (use format: xxxxx-xxxxx or just the 10-character code) ## Managing Two-factor authentication ### Disabling 2FA To disable two-factor authentication: 1. Go to **Settings → Account → Your Profile** and scroll to the **Security** section 2. Toggle off the **Two-factor authentication** switch 3. Confirm by entering either: * Your password and a TOTP code from your authenticator app, or * Your password and a backup code > [!NOTE] > > When 2FA is disabled, all associated backup codes are permanently deleted for security reasons. ### Re-enabling 2FA If you need to set up 2FA again (for example, after getting a new device): 1. Follow the same setup process described above 2. New backup codes will be generated 3. Old backup codes (if any existed) will be invalidated # Introduction Source: https://formbricks.com/docs/platform/introduction Welcome to the Formbricks Documentation! ## Welcome to the Formbricks Documentation! Formbricks is a versatile open-source platform for collecting and analyzing feedback from customers, users, and employees through targeted surveys. Whether you need simple forms or complex experience management solutions, Formbricks scales with your needs. Formbricks is an end-to-end experience management (XM) suite: **Ask** with surveys, **Analyze** with Unify Feedback and dashboards, and **Act** with Workflows. This guide covers everything you need to set up, use, and develop with Formbricks. You'll find step-by-step instructions, feature explanations, and best practices. It also includes advanced docs on extending Formbricks using its self-hosted option, APIs, and SDKs. > [card] [Surveys (Ask)](/docs/surveys/overview) > > Collect feedback from customers, users, and employees with link, website, and in-app surveys. > [card] [Unify Feedback (Analyze)](/docs/unify-feedback/overview) > > Bring feedback from every source into one store and turn it into insights. > [card] [Workflows (Act)](/docs/workflows/overview) > > Automate what happens next with triggers, filters, actions, and observable runs. > [card] [Self Hosting](/docs/self-hosting/overview) > > Learn how to self-host Formbricks on your infrastructure. > [card] [API Reference](/docs/api-reference/rest-api) > > Learn how to use Formbricks' API to CRUD various resources programmatically. > [card] [Development](/docs/development/overview) > > Warm up with the Formbricks code base to make changes to the platform. # Connect AI Agents (MCP) Source: https://formbricks.com/docs/platform/mcp/overview Let AI assistants like Claude and Codex read and manage your Formbricks surveys and feedback records through the Model Context Protocol (MCP), authorized securely with your own login. Formbricks ships a **Model Context Protocol (MCP) server** that lets AI assistants — Claude Code, the Claude apps, Codex, and other MCP-capable clients — work with your workspace: list and read surveys, create link surveys, update or delete them, and read or add Unify Feedback records. The agent goes through the same APIs and permission checks you use in the app, so it always respects your permissions. You connect a client **with your own Formbricks login over OAuth 2.1** — there are no API keys to generate, copy, or paste. You approve the connection once on a consent screen, and you can revoke it at any time. > [!NOTE] > > Prefer to use a long-lived token instead (for scripts, CI, or a client that doesn't support OAuth yet)? > Formbricks API keys still work as a fallback — see the [MCP server technical > handbook](/docs/development/technical-handbook/mcp-server). ## The MCP server URL Point your client at your Formbricks app's `/api/mcp` endpoint: | Instance | MCP server URL | | - | - | | Formbricks Cloud | `https://app.formbricks.com/api/mcp` | | Self-hosted | `https:///api/mcp` | ## How the connection works You don't need to understand the details to connect, but here's what happens under the hood when you add the server to a client: 1. **Discovery** — the client reads the server's OAuth metadata to find where to sign in. 2. **Registration** — the client registers itself automatically using Dynamic Client Registration (DCR). There's no client ID or secret for you to manage. 3. **Sign in & consent** — your browser opens to Formbricks. You log in (if you aren't already) and **approve** the requested access on a consent screen. 4. **Token** — the client receives a short-lived access token it sends on every request, plus a refresh token so it can stay connected without asking you to sign in again. The whole flow uses Authorization Code + PKCE, the standard the [MCP authorization spec](https://modelcontextprotocol.io/specification/draft/basic/authorization) requires. ## What the agent can do The MCP server exposes survey, workflow, response and feedback-record tools, grouped into authorization scopes. Read tools require the matching `:read` scope; tools that create, update, or delete require the `:write` scope. Everything below is offered on the consent screen: | Scope | Tools | What it allows | | - | - | - | | `surveys:read` | `list_surveys`, `get_survey`, `validate_survey`, `get_workspace_custom_css` | Read surveys and their custom CSS, and validate survey documents and CSS | | `surveys:write` | `create_survey`, `patch_survey`, `edit_survey_blocks`, `set_survey_block_order`, `delete_survey`, `patch_workspace_custom_css` | Create, update, and delete surveys, and save a workspace's shared survey CSS — which additionally needs an organization owner or manager | | `workflows:read` | `list_workflows`, `get_workflow`, `list_workflow_runs`, `get_workflow_run`, `test_workflow`¹ | Read workflows and their runs | | `workflows:write` | `create_workflow`, `patch_workflow`, `duplicate_workflow`, `delete_workflow`, `enable_workflow`, `disable_workflow`, `archive_workflow`, `unarchive_workflow` | Create, update, and delete workflows | | `feedbackRecords:read` | `list_feedback_datasets`, `list_feedback_records`, `count_feedback_records`, `get_feedback_record`, `search_feedback_records`, `find_similar_feedback_records` | Read, count and search feedback records in a workspace's feedback dataset | | `feedbackRecords:write` | `create_feedback_record`, `create_feedback_records`, `update_feedback_record`², `delete_feedback_record`² | Create, correct and delete feedback records | | `responses:read` | `list_responses`, `count_responses`, `get_response` | Read and count survey responses | | `responses:write` | `validate_response`, `create_response`, `update_response`, `delete_response`, `batch_delete_responses` | Record, correct and delete survey responses | ¹ `test_workflow` is a dry-run (no changes are saved), so it only needs the `workflows:read` scope — but because it evaluates the live workflow definition, it requires **write or manage** permission on the workspace. A read-only member will get a 403 even though the scope matches. ² Changing a record that already exists is held to a higher bar than creating one, because a feedback dataset shared across workspaces has no way to tell whose records are whose. Connected over **OAuth** (the flow on this page), both tools require you to be an **organization owner or manager**. Authenticated with an **API key** instead, they require the dataset to be assigned to a **single workspace** — a workspace-scoped key cannot be shown to own a record in a shared one — and `delete_feedback_record` additionally requires **manage** permission, matching `DELETE` elsewhere in the API. Creating, reading and searching are unaffected either way. A response is someone's submitted answers, so grant `responses:read` deliberately — it is respondent data, which `surveys:read` never exposes. An integration you connected before these scopes existed keeps working with the access it already has. If it requests the scopes the server advertises, as MCP clients like Claude Code do, it asks you to approve the response scopes the next time it signs in. Scope groups are independent — a client can be granted feedback-record access without survey access, or the other way around. `list_workspaces` is available to any read scope, since every other tool needs a workspace id. > [!NOTE] > > The feedback-record tools work with **Unify Feedback** data and need the Enterprise Edition > (`feedbackDirectories`), plus a feedback dataset assigned to the workspace. Without the entitlement or a > directory, those tools return an authorization or validation error while the survey tools keep working. > [!WARNING] > > `delete_feedback_record` permanently deletes a record — there is no undo and no trash. Grant > `feedbackRecords:write` only to clients you want to be able to change or delete feedback, and keep read-only > agents on `feedbackRecords:read`. Corrections via `update_feedback_record` are also irreversible — the > previous value is kept only in the audit log. Feedback records can be filtered by source, question, submission, end user, chosen option, language, date range, and by enrichment output — sentiment, emotions and whether a record has been enriched or translated at all. Any filter accepts several values, which are OR-ed, while different filters are AND-ed, and the listing can be ordered by when feedback was collected or when it was stored. `count_feedback_records` answers "how many" without fetching the records themselves — so an agent can report totals without pulling anyone's feedback text into the conversation. The two search tools match by meaning rather than keywords ("checkout is confusing" finds "I couldn't figure out how to pay"), and `find_similar_feedback_records` shows how widely one piece of feedback is echoed by others. They rely on the feedback service having an embedding model configured; on self-hosted installs without one they report that they are unavailable. Newly created records become searchable a short while after they arrive, and records without text are never searchable. > [!WARNING] > > Scopes are only a coarse gate. **Access is always bounded by your Formbricks workspace role**: even > if a client holds a `:write` scope, a call only succeeds if you have write/manage permission on the > target workspace — and deleting a feedback record needs manage. An agent can never do more than > you can. ## Prerequisites * A **Formbricks account** with access to the workspace whose surveys you want to work with. Read-only tasks need `read`; creating or editing surveys needs `write` or `manage`. * The **MCP server URL** for your instance (see the table above). * An **MCP client** that supports remote HTTP servers with OAuth — see the [setup guides](/docs/platform/mcp/setup) for Claude Code, the Claude apps, and Codex. > [!NOTE] > > **Self-hosting?** The OAuth provider is built in and enabled automatically — there's nothing extra to turn > on. It just needs your instance to be served from a correct, public **HTTPS** base URL (set via `WEBAPP_URL` > / `BETTER_AUTH_URL`). The discovery metadata and browser redirects are built from that URL, so an > `http://localhost` or misconfigured origin will break the OAuth flow for remote clients. See the > [self-hosting configuration](/docs/self-hosting/configuration/environment-variables). > > Kubernetes deployments that cannot reach their own public origin can set `MCP_OAUTH_JWKS_URL` to > the internal Formbricks `/api/auth/jwks` endpoint. This changes only the server-side key fetch; > OAuth discovery, issuers, redirects, cookies, and audiences remain on the public URL. The standard > path applies only when Formbricks is not mounted below a custom subpath. For an installation mounted > at `/formbricks`, configure the complete internal URL, for example > `http://formbricks:3000/formbricks/api/auth/jwks`. ## Next steps > [card] [Set up your MCP client](/docs/platform/mcp/setup) > > Copy-paste guides for Claude Code, the Claude apps (custom connectors), and Codex — plus how to manage and > revoke access. For the tool schemas, response formats, discovery endpoints, and the API-key fallback, see the [MCP server technical handbook](/docs/development/technical-handbook/mcp-server). Survey tools map to the [v3 Surveys API](/docs/development/technical-handbook/mcp-server#relationship-to-v3-surveys-api) they wrap; feedback-record tools read and write [Unify Feedback data](/docs/development/technical-handbook/mcp-server#feedback-records-and-the-hub). # Set Up Your MCP Client Source: https://formbricks.com/docs/platform/mcp/setup Connect Claude Code, the Claude apps, or Codex to the Formbricks MCP server over OAuth — plus how to manage and revoke access. These guides connect your MCP client to Formbricks using OAuth (no API keys). They use the Formbricks Cloud URL `https://app.formbricks.com/api/mcp`; if you self-host, swap in your own `https:///api/mcp`. For how the flow works and prerequisites, see [Connect AI agents (MCP)](/docs/platform/mcp/overview). ## Claude Code Claude Code runs on your machine and performs the OAuth handshake itself. **1. Add the server** ```bash theme={null} claude mcp add --transport http formbricks https://app.formbricks.com/api/mcp ``` **2. Authenticate** In a Claude Code session, run `/mcp`, select **formbricks**, and choose **Authenticate**. Your browser opens to Formbricks; sign in if needed and **approve** the requested access on the consent screen. Claude Code registers itself automatically and stores the token — there's no scope to type in. **3. Verify** ```bash theme={null} claude mcp list claude mcp get formbricks ``` Then ask Claude to use it, e.g. *"Use the formbricks MCP server to list my surveys."* To share the server definition with a project (no credentials committed), add it to `.mcp.json` at the repo root and authenticate with `/mcp` on first use: ```json theme={null} { "mcpServers": { "formbricks": { "type": "http", "url": "https://app.formbricks.com/api/mcp" } } } ``` ## Claude apps (custom connectors) Use this for **claude.ai** and **Claude Desktop**, where Formbricks is added as a custom connector. **1. Open the connectors settings** Go to **Settings → Connectors** (**Customize → Connectors**) and click **Add custom connector**. **2. Add the server URL** Enter `https://app.formbricks.com/api/mcp` and confirm. Leave the optional OAuth client fields blank — Formbricks registers the connector automatically. **3. Approve access** Claude opens Formbricks in your browser. Sign in and **approve** the requested access. The connector then shows as connected, and you can enable it per chat from the **+** menu. > [!WARNING] > > **Two things to know about the Claude apps:** > > * **Custom connectors depend on your Claude plan.** They're available on Free, Pro, Max, Team, and > Enterprise, but the Free plan is limited to a single connector. On **Team/Enterprise**, an > **organization owner** must add the connector under **Organization settings → Connectors** first; > members then connect to it individually. > * **The connection runs from Anthropic's servers, not your machine.** A custom connector therefore > **cannot reach a `localhost` server** — the MCP URL must be a **public HTTPS** address. Formbricks > Cloud works out of the box; if you self-host, expose your instance on a public HTTPS domain (a > tunnel such as ngrok/cloudflared works for testing). To connect a local dev server, use **Claude > Code** instead — it runs locally. ## ChatGPT (MCP apps) Use this to add Formbricks to **ChatGPT** as a custom MCP app. Custom MCP apps need ChatGPT **developer mode**, which is available on Business and Enterprise/Edu plans and has to be enabled by a workspace admin first — see OpenAI's [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt). **1. Create the app** In ChatGPT, go to **Settings → Apps → Create**. Enter the MCP URL `https://app.formbricks.com/api/mcp` and choose **OAuth** as the authentication mechanism. **2. Approve access** ChatGPT opens Formbricks in your browser and registers itself. Sign in and **approve** the requested access; ChatGPT then scans the available tools. > [!NOTE] > > Like the Claude apps, ChatGPT connects from OpenAI's servers, so the MCP URL must be a **public > HTTPS** address — not `localhost`. ## Codex **1. Add the server** Include `--oauth-resource` so the access token is audience-bound to the MCP resource: ```bash theme={null} codex mcp add formbricks \ --url https://app.formbricks.com/api/mcp \ --oauth-resource https://app.formbricks.com/api/mcp ``` **2. Authenticate** ```bash theme={null} codex mcp login formbricks ``` Codex opens the browser to Formbricks, registers itself, and you **approve** on the consent screen. For read-only access, restrict the scopes: ```bash theme={null} codex mcp login formbricks --scopes surveys:read,workflows:read,feedbackRecords:read,responses:read,offline_access ``` Scope groups are independent — request only the ones you need (for example `feedbackRecords:read,offline_access` for feedback data alone). **3. Verify** ```bash theme={null} codex mcp list codex mcp get formbricks ``` The equivalent `~/.codex/config.toml` entry: ```toml theme={null} [mcp_servers.formbricks] url = "https://app.formbricks.com/api/mcp" oauth_resource = "https://app.formbricks.com/api/mcp" ``` ## Manage and revoke access Every client you authorize appears under **Settings → Account → Authorized Apps** (`/account/settings/authorized-apps`), showing the client name, granted scopes, and when it was approved. Click **Revoke** to immediately cut off a client's access; it will need to be re-authorized to connect again. Tokens are short-lived by design: an access token lasts **15 minutes** and the client refreshes it silently in the background for up to **30 days** (the refresh window). After that — or after you revoke — the client re-runs the sign-in and consent flow. Approving the write scopes (`surveys:write`, `workflows:write`, `feedbackRecords:write`, `responses:write`) is re-confirmed periodically for safety. ## Troubleshooting > [accordion] claude.ai or ChatGPT says it couldn't register / connect > > Custom connectors connect from the vendor's cloud, which can't reach `localhost` or a private > network. Use a **public HTTPS** MCP URL (Formbricks Cloud, or a tunnel to a self-hosted instance), > or connect a local server with **Claude Code** instead. > > If registration fails with `400 invalid_redirect_uri`, the client asked to register a callback > Formbricks doesn't allow. Formbricks accepts local (`http://localhost`, `127.0.0.1`, `[::1]`) > callbacks and the exact claude.ai and ChatGPT callbacks. To allow another hosted client, a > self-hoster can add its exact callback with `MCP_DCR_ALLOWED_REDIRECT_URIS`. > [accordion] invalid\_client or a stale-registration error after reconnecting > > The client cached a registration that no longer exists on the server (e.g. the server data was > reset). Clear the client's stored credentials for the server and re-authenticate — in Claude Code, > remove and re-add the server (`claude mcp remove formbricks` then `claude mcp add …`) and run > `/mcp` again. > [accordion] invalid\_scope during sign-in > > The client requested a scope it isn't registered for. Reconnect from scratch so it re-registers > with the scopes the server advertises (`surveys:read`, `surveys:write`, `workflows:read`, > `workflows:write`, `feedbackRecords:read`, `feedbackRecords:write`, `responses:read`, > `responses:write`, `offline_access`). > [accordion] Stuck in a consent loop / keeps asking you to sign in > > Usually a cookie or stale-session issue. Make sure you're signed in to Formbricks in the same > browser the client opens, and that third-party-cookie blocking or a private window isn't > discarding the session. If it persists, revoke the app under **Settings → Account → Authorized > Apps**, clear the client's stored credentials for the server, and reconnect. Self-hosters: an > incorrect base URL (see below) also causes repeated redirects. > [accordion] A tool call fails even though you're connected > > Scopes don't override your workspace role. Creating, editing, or deleting surveys or workflows > requires `write` or `manage` permission on that workspace — ask a workspace owner/manager to grant > it. `test_workflow` also needs `write`/`manage` even though it's a read-scoped dry-run, because it > evaluates the live workflow definition. A `:write` tool likewise 403s if your token was only granted > the matching `:read` scope; reconnect and approve write access. > [accordion] Self-hosted: the browser can't complete sign-in / redirects fail > > OAuth discovery and redirects are built from your configured base URL. Serve Formbricks from a > correct, public **HTTPS** origin and set `WEBAPP_URL` (and `BETTER_AUTH_URL`) to it. An > `http://localhost` or mismatched origin breaks the flow for remote clients. See the > [environment variables](/docs/self-hosting/configuration/environment-variables) reference. > > If the Formbricks container or pod cannot resolve that public origin when it verifies a token, set > `MCP_OAUTH_JWKS_URL` to the internal `/api/auth/jwks` endpoint. Keep `WEBAPP_URL` and your auth base > URL public: the internal override is only used for the server-side signing-key fetch. On an instance > that still configures the auth URL under its older name, that is the one that has to stay public. > `/api/auth/jwks` is correct only when no custom application subpath is configured. If Formbricks is > mounted at `/formbricks`, use the complete internal URL, such as > `http://formbricks:3000/formbricks/api/auth/jwks`. > [accordion] Self-hosted behind Cloudflare: the client can't connect, but the URL works in your browser > > Only sign-in and consent happen in your browser. Discovery, registration, the token exchange and > every tool call come straight from the client — for claude.ai and ChatGPT, from Anthropic's or > OpenAI's servers. Cloudflare can treat that traffic as an AI agent or bot and block or challenge it > while still letting your browser through. The client then gets a Cloudflare page instead of the JSON > it expects, and reports what looks like an OAuth, registration or MCP error. So a URL that opens > in your browser, or a consent screen that works, does not rule Cloudflare out. > > Check Cloudflare's **Security Events** for blocked or challenged requests to these paths (prefix > each with your [custom subpath](/docs/self-hosting/configuration/custom-subpath) if you use one): > > * `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, > `/.well-known/openid-configuration` and `/api/auth/.well-known/` — discovery > * `/api/auth/oauth2/` — registration and tokens > * `/api/mcp` — the MCP server itself > > Then let the client through without turning protection off for the whole site: > > * **AI bot policies:** under **Security → Settings → Configure AI bot policies**, set **Agent** to > **Allow**. Agent covers AI tools acting for a person in real time, which is what an MCP client > is. **Training** and **Search** can stay blocked. If you still use the older **Block AI bots** > setting, check that too. > * **Bot Fight Mode** can't be skipped for specific paths, so if it blocks the client, turn it off. > **Super Bot Fight Mode** can: add a WAF custom rule with the **Skip** action for the paths above. > * **WAF custom rules and Cloudflare Access:** make sure no Block, Managed Challenge or Access policy > covers the paths above. An MCP client can't solve a challenge or sign in to Access. > > Formbricks also fetches its own signing keys from your public `/api/auth/jwks` to verify tokens. > If Cloudflare challenges that request, sign-in succeeds but every call to `/api/mcp` is rejected > with `401`, and Formbricks logs `MCP OAuth authentication failed` with `failureSource: "jwks_fetch"`. > Set `MCP_OAUTH_JWKS_URL` to the internal endpoint so that fetch doesn't go through Cloudflare (see > the entry above). *** Need the tool schemas, response shapes, or the API-key fallback? See the [MCP server technical handbook](/docs/development/technical-handbook/mcp-server). # Open-Source Source: https://formbricks.com/docs/platform/open-source Open-source Experience Management. Free & open source. The open core of the Formbricks software is available under the AGPLv3 license. This means you can use, modify, and distribute the software as long as you adhere to the [terms of the license.](https://www.tldrlegal.com/license/gnu-affero-general-public-license-v3-agpl-3-0) The open-source version of Formbricks is free to use, even for commercial purposes. Over time, all survey features will remain part of the free Community Edition. Formbricks also offers a more advanced Enterprise Edition with additional features and support. | Advantage | Open Source Software | Proprietary Software | | - | - | - | | **Data Privacy** | Self-host for maximum control over data | Dependent on third party data processor. | | **Cost** | Often free or significantly lower cost. | Typically, requires a purchase or subscription. | | **Customizability** | Code can be modified to meet specific needs. | Limited customization, restricted to developer's features. | | **Security** | Frequent community reviews identify vulnerabilities quickly. | Security updates depend on vendor's schedule and interest. | | **Flexibility** | Supports a wide range of applications and integrations. | Designed for specific environments and integrations. | | **Community Support** | Large, active communities offer free support and resources. | Paid customer support with limited community help. | | **Innovation** | Fosters rapid innovation through community contributions. | Innovations depend on vendor's vision and development team. | | **Licensing** | Permissive licenses allow broad usage and modification. | Strict licensing with limited redistribution rights. | | **Independence** | Not dependent on a single vendor or developer. | Vendor lock-in can limit future choices. | | **Transparency** | Full visibility into the code base and development. | Closed-source, code is hidden from users. | | **Interoperability** | Supports open standards, ensuring interoperability. | Often requires additional software or plugins for compatibility. | # What is Formbricks? Source: https://formbricks.com/docs/platform/what-is-formbricks Get to know Formbricks and its capabilities. Formbricks is an open-source (AGPLv3) survey platform built to collect feedback from anyone—users, customers, or employees—on any platform. With Formbricks, you can replace many existing survey tools: * **Standalone surveys (share via link):** Replace Google Forms, Typeform or any other link survey tool [with Formbricks Form Builder](https://formbricks.com/open-source-form-builder). Use lots of question types and comprehensive customizations. * **Scalable website surveys:** Even if you have millions of website visitors, Formbricks lets you run well-timed and anonymously targeted [surveys on any public website.](https://formbricks.com/website-survey) * **Highly targeted app surveys:** Identify known users with Formbricks and enrich their profiles with attributes and specific actions. Build cohorts for [highly targeted in-app surveys.](https://formbricks.com/in-app-survey) The survey platform is **mostly free, even for commercial use**. Over time, all survey features will stay part of the free Community Edition. ## An end-to-end XM Suite Formbricks covers the full experience-management loop — from collecting feedback to acting on it — in one platform: > [card] [Ask](/docs/surveys/overview) > > Collect feedback with link, website, and in-app surveys built in a powerful, fully customizable builder. > [card] [Analyze](/docs/unify-feedback/overview) > > Unify feedback from every source into one store, then visualize it with charts and shareable dashboards. > [card] [Act](/docs/workflows/overview) > > Turn responses into action with Workflows that send an email when a response comes in — no code required. ### Formbricks – The Experience Management (XM) Suite To support the development of our open-source platform, we’ve created a premium offering: the **Formbricks XM Suite**. * **What is XM?** Experience Management (XM) involves collecting, analysing, and reporting feedback from stakeholders (like customers or employees) to understand and improve their experience with your organisation. * **Why XM Matters** Helping businesses, governments, and nonprofits understand their users' experiences leads to better services and happier people. Formbricks XM provides the data needed to make decisions that put people first. * **How XM Works in Formbricks** Formbricks XM simplifies experience management. It focuses only on what’s needed to measure specific experiences, with easy-to-use templates, reports, and best practices. We have spent a lot of time and energy building out the open-source survey platform which powers the above. Stick around to see how Formbricks XM Apps will empower everyone to think and work human-centric. [Try Formbricks Cloud ☁️ ](https://app.formbricks.com/) # AI Features Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/ai-features Connect an LLM to your instance and enable AI-powered helpers like survey translation and AI chart creation. > [!NOTE] > > AI features are part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license). A single organization toggle unlocks AI-assisted survey translation and AI chart creation across the app. Formbricks runs fine without AI — nothing is enabled until you connect a model. Connect a provider: [AI Features](/docs/self-hosting/configuration/ai-features). For what the toggle unlocks and how your data is handled, see [AI Features](/docs/platform/features/ai-features). # Audit Logging Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/audit-logging Enable comprehensive audit logs for your Formbricks instance. Audit logs record **who** did **what**, **when**, **from where**, and **with what outcome** across your Formbricks instance. > [!NOTE] > > Audit logging is an Enterprise feature. Configure your > [Enterprise license](/docs/self-hosting/advanced/license) before enabling it. ## Benefits Of Audit Logging * **Compliance evidence** — Exported audit events can support the controls and evidence required by your compliance program. * **Security investigation support** — Audit logs provide visibility into covered user and system actions during an incident. * **Operational accountability** — Track covered changes to answer questions such as "*who modified this?*" or "*when was this deleted?*". ## Enabling Audit Logging 1. Set the following environment variables in your deployment (Docker Compose, Kubernetes, etc.): ```bash title=".env" theme={null} # --- Audit logging --- AUDIT_LOG_ENABLED=1 AUDIT_LOG_GET_USER_IP=1 # Set this to the exact number of trusted proxies in front of Formbricks. TRUSTED_PROXY_HOP_COUNT=1 ``` 2. Redeploy your containers. 3. Confirm you can see audit logs in the output of your containers. Audit logs are written to **stdout** as JSON Lines. Configure your container platform or logging agent to forward records with `level: "audit"` to your central logging destination. ### Configure Trusted Proxy Hops `AUDIT_LOG_GET_USER_IP=1` uses Formbricks' shared client-IP resolver. `TRUSTED_PROXY_HOP_COUNT` must equal the number of trusted CDN, WAF, load-balancer, ingress, and Envoy hops that append to `X-Forwarded-For` before the request reaches Formbricks. The application and Helm chart default to `1`, which assumes one trusted reverse proxy. Examples: | Request Path | `TRUSTED_PROXY_HOP_COUNT` | | - | -: | | Client → ingress → Formbricks | `1` | | Client → load balancer → Envoy → Formbricks | `2` | | Client → CDN/WAF → load balancer → Envoy → Formbricks | `3` | > [!WARNING] > > Count the hops in your real deployment; do not copy an example blindly. A value higher than the real chain can > let a client prepend and spoof the selected address. A value lower than the real chain selects an intermediate > proxy instead of the client. A missing, malformed, or shorter-than-configured chain fails closed to > `untrusted-client-ip`. This setting also affects IP-based rate limits and captured response IP metadata. With the Helm chart, configure the values under `deployment.env`: ```yaml theme={null} deployment: env: AUDIT_LOG_ENABLED: "1" AUDIT_LOG_GET_USER_IP: "1" TRUSTED_PROXY_HOP_COUNT: "2" ``` ## Understanding The Log Format Audit logs are **JSON Lines** (one JSON object per line). A typical entry looks like this: ```json theme={null} {"level":"audit","time":1749207302158,"pid":20023,"hostname":"formbricks-node-1","name":"formbricks","actor":{"id":"cm90t4t7l0000vrws5hpo5ta5","type":"api"},"action":"created","target":{"id":"cmbkov4dn0000vrg72i7oznqv","type":"webhook"},"timestamp":"2025-06-06T10:55:02.145Z","organizationId":"cm8zovtbm0001vr3efa4n03ms","status":"success","ipAddress":"unknown","apiUrl":"http://localhost:3000/api/v1/webhooks","changes":{"id":"cmbkov4dn0000vrg72i7oznqv","name":"********","createdAt":"2025-06-06T10:55:02.123Z","updatedAt":"2025-06-06T10:55:02.123Z","url":"https://eoy8o887lmsqmhz.m.pipedream.net","source":"user","workspaceId":"cm8zowv0b0009vr3ec56w2qf3","environmentId":"cm8zowv0b0009vr3ec56w2qf3","triggers":["responseCreated","responseUpdated","responseFinished"],"surveyIds":[]}} ``` Key fields: | Field | Description | | - | - | | `level` | Log level, always `"audit"` for audit events | | `time` | Unix timestamp in milliseconds | | `pid` | Process ID of the logging instance | | `hostname` | Hostname of the server generating the log | | `name` | Application name, typically `"formbricks"` | | `timestamp` | ISO‑8601 time of the action | | `actor` | User or API key responsible (object with `id` and `type`) | | `action` | Action value such as `created`, `updated`, `authenticationAttempted`, or `signedIn` | | `target` | The resource affected (object with `id` and `type`) | | `status` | `success` or `failure` | | `organizationId` | Organization identifier where the action occurred | | `ipAddress` | Resolved client IP when capture is enabled; otherwise `"unknown"`. An untrusted forwarding chain produces `"untrusted-client-ip"` | | `apiUrl` | (Optional) API endpoint URL when the event was generated through an API call | | `eventId` | (Optional) Available on failure events for correlation with the application log | | `changes` | (Optional) Only the fields that actually changed (sensitive values redacted) | ## Centralized Logging And Compliance Formbricks emits audit events to the application logger. The container's stdout stream is not, by itself, a durable or immutable audit store. Your deployment must forward the events to a logging platform and configure the controls required by your organization, including: * retention and archival periods; * write-once or immutability controls; * access controls and separation of duties; * deletion protection and tamper detection; and * monitoring for delivery failures. Audit logging can support a SOC 2 or other compliance program, but enabling this feature does not make a deployment compliant. Suitability depends on the coverage, forwarding, storage, and operational controls in your environment. ## Additional Details * **Redacted values:** Sensitive fields covered by the audit redaction helpers are replaced with `"********"` before the event is written. * **Success and failure:** Covered operations can emit both `success` and `failure` events. * **Delivery model:** Formbricks writes events through the application logger; query APIs, long-term retention, and exports belong to your logging platform. * **Scope limitation:** For now, **only events triggered inside the `Formbricks` application** are audited. This means: * **Embed and Link Surveys** are **not** included in the audit logs. * **Survey responses** created via the client API or client-side SDKs are **not** audited. # Contact management & segments Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/contact-management-segments Create and manage contacts and attribute-based segments with Formbricks. Contacts are helpful if you want to assign response to specific contacts or users of your mobile application. Also, if you'd like to do [attribute-based targeting](/docs/surveys/website-app-surveys/attribute-based-targeting) of specific cohorts or segments of your user base you need this feature. # Dashboards & Charts Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/dashboards Visualize Feedback Records with charts and group them onto shareable dashboards. Build Area, Bar, Line, Pie, and Big Number charts on top of any Feedback Dataset, then arrange them on dashboards to share with your team. Read the full guide: [Dashboards & Charts](/docs/unify-feedback/dashboards-charts). # Hide 'Powered by Formbricks' signature Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/hide-powered-by-formbricks Hide our brand signature for a more white-labeled experience. Remove the 'Powered by Formbricks' signature in both Link Surveys and In-product surveys as well as on emails sent out via Formbricks. # OAuth & SSO Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/oidc-sso Configure Single Sign-On with your Formbricks instance. > [!NOTE] > > Single Sign-On is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license). Implement enterprise-grade authentication for your survey platform with [Open ID Connect](/docs/self-hosting/configuration/auth-sso/open-id-connect), [Azure AD OAuth](/docs/self-hosting/configuration/auth-sso/azure-ad-oauth), [Google OAuth](/docs/self-hosting/configuration/auth-sso/google-oauth), or [SAML](/docs/self-hosting/configuration/auth-sso/saml-sso) # SAML SSO Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/saml-sso Configure Single Sign-On with SAML for your Formbricks instance. > [!NOTE] > > Single Sign-On is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license). SAML > additionally requires the `saml` entitlement on the licence. Implement enterprise-grade authentication for your survey platform using [SAML SSO](/docs/self-hosting/configuration/auth-sso/saml-sso). # Teams & Roles (RBAC) Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/team-access Granularly control which users have access to specific Workspaces and surveys. Each User can be a member of any number of Teams. Each Team can have Read, Write or Manage access to any number of Workspaces. In the Community Edition, each User has Admin rights. In the Enterprise Edition, you can granularly assign Roles and Memberships to users. Here are [all details of user management](/docs/platform/features/user-management) # Unify Feedback Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/unify-feedback Consolidate feedback from surveys, CSVs, and APIs into one normalized store. Unify Feedback brings survey responses, CSV uploads, and API-ingested records into the same normalized model under organization-scoped Feedback Datasets. Workspaces can be granted access to specific datasets. Read the full guide: [Unify Feedback overview](/docs/unify-feedback/overview). # White-label Follow-ups Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/whitelabel-email-follow-ups Add you own logo to emails sent to respondents With the Enterprise Edition, you can customize the [Follow-up Emails](/docs/platform/features/email-customization) sent to respondents. > [!NOTE] > > Emails sent to the coworkers of your organisation (e.g. invitations to join a Formbricks team) remain Formbricks branded. # Workflows Source: https://formbricks.com/docs/self-hosting/advanced/enterprise-features/workflows Automate response-driven tasks with triggers, filters, and actions. Workflows automate tasks in response to events in Formbricks. You choose a trigger, narrow down which events qualify with optional filters, and run an action. Today that action is sending an email. Read the full guide: [Workflows overview](/docs/workflows/overview). # License Source: https://formbricks.com/docs/self-hosting/advanced/license License for Formbricks The Formbricks core source code is licensed under AGPLv3 and available on GitHub. Additionally, we offer features for bigger organisations & enterprises under a separate, paid Enterprise License. This assures the long-term sustainability of the open-source codebase. All free features are listed [below](#what-features-are-free). > [!NOTE] > > Want to get your hands on the Enterprise Edition? [Request a free Enterprise Edition > Trial](https://app.formbricks.com/s/trvp8tzy5uvsps9rc9qi9l9w?delivery=onpremise\&source=docs\&type=licenseRequest) License to build a fully functioning Proof of > Concept. ## Enterprise Edition Additional to the AGPLv3 licensed Formbricks core, the Formbricks repository contains code licensed under our [Enterprise License](https://github.com/formbricks/formbricks/blob/main/apps/web/modules/ee/LICENSE). This additional functionality is not part of the AGPLv3 licensed Formbricks core and is designed to meet the needs of larger teams and enterprises. ## When do I need an Enterprise License? | | Community Edition | Enterprise Edition | | - | - | - | | Self-host for commercial purposes | ✅ | ✅ | | Fork codebase, make changes, release under AGPLv3 | ✅ | ✅ | | Fork codebase, make changes, **keep private** | ❌ | ✅ | | Unlimited responses | ✅ | Pay per response | | Unlimited surveys | ✅ | ✅ | | Unlimited users | ✅ | ✅ | | Workspaces | 1 | Pay per workspace | | Use all [free features](#what-features-are-free) | ✅ | ✅ | | Use [paid features](#what-features-are-free) | ❌ | Pay per feature | ## Open Core Licensing ### The AGPL Formbricks Core The Formbricks core application is licensed under the [AGPLv3 Open Source License](https://github.com/formbricks/formbricks/blob/main/LICENSE). The core application is fully functional and includes everything you need to design & run link surveys, website surveys and in-app surveys. You can use the software for free for personal and commercial use. You're also allowed to create and distribute modified versions as long as you document the changes you make incl. date and **publish your complete code under the AGPLv3 license as well.** ### The Enterprise Edition Additional to the AGPL licensed Formbricks core, this repository contains code licensed under an Enterprise license. The [code](https://github.com/formbricks/formbricks/tree/main/apps/web/modules/ee) and [license](https://github.com/formbricks/formbricks/blob/main/apps/web/modules/ee/LICENSE) for the enterprise functionality can be found in the `/apps/web/modules/ee` folder of this repository. This additional functionality is not part of the AGPLv3 licensed Formbricks core and is designed to meet the needs of larger teams and enterprises. This advanced functionality is already included in the Docker images, but you need an [Enterprise License Key](https://app.formbricks.com/s/trvp8tzy5uvsps9rc9qi9l9w?delivery=onpremise\&source=docs\&type=licenseRequest) to unlock it. > [!NOTE] > > Want to get your hands on the Enterprise Edition? [Request a free Enterprise Edition > Trial](https://app.formbricks.com/s/trvp8tzy5uvsps9rc9qi9l9w?delivery=onpremise\&source=docs\&type=licenseRequest) License to build a fully functioning Proof of > Concept. ## White-Labeling Formbricks and Other Licensing Needs We offer Formbricks white-labeled in some cases. [Please send us an email with a deployment description and we'll get back to you.](mailto:hola@formbricks.com). ## Why charge for Enterprise Features? The Enterprise Edition allows us to fund the development of Formbricks sustainably. It guarantees that the open-source surveying infrastructure we're building will be around for decades to come. ## What features are free? | Feature | Community Edition | Enterprise Edition | | - | - | - | | Unlimited surveys | ✅ | ✅ | | Full API Access | ✅ | ✅ | | All SDKs | ✅ | ✅ | | Website & App surveys | ✅ | ✅ | | Link surveys | ✅ | ✅ | | Email embedded surveys | ✅ | ✅ | | Advanced logic | ✅ | ✅ | | Custom styling | ✅ | ✅ | | Custom URL | ✅ | ✅ | | Recall information | ✅ | ✅ | | All question types | ✅ | ✅ | | Multi-media backgrounds | ✅ | ✅ | | Partial responses | ✅ | ✅ | | File upload | ✅ | ✅ | | Hidden fields | ✅ | ✅ | | Single-use links | ✅ | ✅ | | Pin-protected surveys | ✅ | ✅ | | Webhooks | ✅ | ✅ | | Email follow-ups | ✅ | ✅ | | Multi-language surveys | ✅ | ✅ | | Multi-language UI | ✅ | ✅ | | All integrations (Slack, Zapier, Notion, etc.) | ✅ | ✅ | | Domain Split Configuration | ✅ | ✅ | | Cluster Hosting via Formbricks Helm Chart | ✅ | ✅ | | Hide "Powered by Formbricks" | ❌ | ✅ | | Whitelabel email follow-ups | ❌ | ✅ | | Teams & access roles | ❌ | ✅ | | Contact management & segments | ❌ | ✅ | | Quota Management | ❌ | ✅ | | Workflows | ❌ | ✅ | | Unify Feedback Inbox | ❌ | ✅ | | Feedback Datasets | ❌ | ✅ | | Insights Dashboards | ❌ | ✅ | | Audit Logs | ❌ | ✅ | | OIDC SSO (AzureAD, Google, OpenID) | ❌ | ✅ | | SAML SSO | ❌ | ✅ | | Spam protection (ReCaptchaV3) | ❌ | ✅ | | Two-factor authentication | ❌ | ✅ | | Custom 'Workspace' count | ❌ | ✅ | | White-glove onboarding | ❌ | ✅ | | Support SLAs | ❌ | ✅ | Questions? [Send us an email](mailto:johannes@formbricks.com) or [book a call with us.](https://cal.com/johannes/license) # License Activation Source: https://formbricks.com/docs/self-hosting/advanced/license-activation How to activate your Formbricks Enterprise License To unlock Formbricks Enterprise Edition features, you need to activate your Enterprise License Key. Follow these steps to activate your license: **1. Set the License Key** Add your Enterprise License Key as an environment variable in your deployment: ```bash theme={null} ENTERPRISE_LICENSE_KEY= ``` * Add your Enterprise License Key after `ENTERPRISE_LICENSE_KEY=` with the key you received from Formbricks. * How you set environment variables depends on your deployment (Docker, Kubernetes, .env file, etc.). **2. Restart Your Instance** After setting the environment variable, **restart your Formbricks instance** to apply the changes. **3. Verify License Activation** To verify if your license is active, visit **Settings → Organization → Enterprise License** to check the confirmation screen. **4. Ensure License Server is Reachable** Your Formbricks instance performs a daily license check to verify your Enterprise License. If you're deploying Formbricks behind a firewall or have network restrictions, you need to whitelist the following: * **Domain**: `ee.formbricks.com` * **URL**: `https://ee.formbricks.com/api/licenses/check` * **Protocol**: HTTPS (Port 443) * **Method**: POST * **Frequency**: Every 24 hours The license check includes a 3-day grace period. If a check fails temporarily — or reports your key as expired — your instance continues using its cached license information for up to 3 days before falling back to the Community Edition. If you have questions or need assistance with network configuration, please reach out to [hola@formbricks.com](mailto:hola@formbricks.com). # Migrating Surveys Source: https://formbricks.com/docs/self-hosting/advanced/migrating-surveys Copy surveys and their responses from one Formbricks instance to another with the management API. This page is about moving **selected surveys and their response data** between two running Formbricks instances — a staging box to production, a self-hosted instance to Formbricks Cloud, one company's instance to another after a split. It uses nothing but the public management API, so the two instances can be on different versions, different databases, and different object storage. > [!NOTE] > > **Moving a whole instance? Do not use this page.** If you control both machines and want everything > — users, organizations, workspaces, contacts, displays, tags, file uploads, webhooks — then a > Postgres dump plus a copy of your S3 bucket is faster, complete, and keeps every ID intact: > > ```bash theme={null} > pg_dump "$OLD_DB_URL" -Fc -f formbricks.dump > pg_restore -d "$NEW_DB_URL" --no-owner formbricks.dump > ``` > > Restore into an instance running the **same Formbricks version** as the source, then upgrade it > following the [migration guide](/docs/self-hosting/advanced/migration). The API route below exists for > the cases a dump cannot serve: you only want some surveys, the target already has data you must > keep, or you do not own the database on one of the two ends. ## What carries over The API route rebuilds surveys from their public survey document and replays responses onto them. That is enough to keep every answer readable and correctly dated, but it is not a byte-for-byte copy. **Carried over** * Survey name, type, status, metadata, languages and every translation * Blocks, elements, choices, logic, endings, variables, hidden fields * **Block, element and ending IDs, verbatim.** This is the part that matters: a response's `data` is keyed by element ID and its `endingId` names an ending, so keeping those IDs is what makes a replayed response land on the right question instead of being rejected * App-survey display settings and triggers (see [App surveys](#app-surveys)) * Every response's `data`, `variables`, `ttc`, `meta`, `language`, `endingId` and `singleUseId` — `ttc` with [one caveat](#time-to-complete-needs-_total-stripped) * Each response's `createdAt` and `updatedAt`, so your charts keep their shape **Not carried over** * **The survey ID.** Every survey gets a fresh one, so every link URL changes — see [Finish by hand](#step-4-finish-by-hand) * Response IDs — fresh ones are assigned * Styling and theme overrides, follow-up emails, quotas, single-use link settings, survey PIN, reCAPTCHA, custom head scripts, custom slug * Contact targeting (segments) on app surveys * Uploaded files, display records, response tags, contacts — see [Known limitations](#known-limitations) > [!WARNING] > > **Importing responses fires the target's response pipeline.** Every `POST` to the responses endpoint > emits `responseCreated` and, for finished responses, `responseFinished` — which dispatches webhooks, > integrations (Airtable, Google Sheets, Notion, Slack), workflows, and survey follow-up emails > configured in the **target** workspace. > > Before importing, remove or disable webhooks, integrations and workflows in the target workspace, and > add follow-up emails only **after** the import has finished. Otherwise a few thousand replayed > responses become a few thousand real emails. ## Before you start **1. Create an API key on each instance** On both instances, create a key that covers the workspace you are moving from or to — see [Generate API Key](/docs/api-reference/generate-key). Read access is enough on the source; the target needs **write** or **manage**. > [!WARNING] > > **Pick the workspaces when you create the key — they cannot be changed later.** A key's > Workspace Access list and permission levels are fixed at creation; editing a key afterwards only > renames it. There is no "all workspaces" option either, so a workspace created *after* the key is > unreachable by it. In both cases the symptom is a `403` on every write while reads elsewhere keep > working, and the fix is to delete the key and create a new one with the right workspaces selected. **2. Note both workspace IDs** The workspace ID is in the app URL: `https://your-instance.com/workspaces//surveys`. (`GET /api/v2/me` also lists them, but only for keys that additionally have Organization read access.) **3. Install curl and jq** The scripts below use nothing else. `jq` 1.6 or newer. **4. Plan around the rate limit** Management API requests are limited to **100 per minute per API key**. Every survey and every single response is one request, so 5,000 responses take at least 50 minutes. The scripts pace themselves with a `THROTTLE` sleep and retry on `429`. If you own the target instance and want it to go faster, set [`RATE_LIMITING_DISABLED=1`](/docs/self-hosting/configuration/rate-limiting#disabling-rate-limiting) there for the duration of the import and restart it, then turn it back on. ## Copying a single survey If you only need one survey moved, this is the whole job: one script, one command, no intermediate directory. It reads the survey and its responses straight from the source and writes them to the target as it goes. The workspace-wide workflow starts at [Step 1](#step-1-export-the-source-workspace) below. Everything on this page still applies — the same fields are dropped, the same file-upload answers are refused, the same response pipeline fires on the target. The one difference is app-survey triggers: with no export directory to build an ID map from, this script matches the source's action classes to the target's **by name** and drops any trigger with no counterpart, falling back to `status: draft` so the survey cannot go live half-configured. Create the missing actions in the target first if you want the trigger to survive. ```bash fb-copy-survey.sh theme={null} #!/usr/bin/env bash # Copy one survey and all of its responses from one Formbricks instance to another. set -euo pipefail SOURCE_URL="${SOURCE_URL:?e.g. https://old.formbricks.example.com}" SOURCE_API_KEY="${SOURCE_API_KEY:?read access on the source workspace is enough}" SOURCE_SURVEY_ID="${SOURCE_SURVEY_ID:?survey id, see the survey URL in the app}" TARGET_URL="${TARGET_URL:?e.g. https://new.formbricks.example.com}" TARGET_API_KEY="${TARGET_API_KEY:?needs manage access on the target workspace}" TARGET_WORKSPACE_ID="${TARGET_WORKSPACE_ID:?workspace id, see the app URL}" THROTTLE="${THROTTLE:-0.7}" # seconds between requests; keeps you under 100/minute # fb [json-body] -> sets FB_BODY and FB_CODE, retries 429/5xx. fb() { local method="$1" url="$2" key="$3" body="${4:-}" attempt=0 tmp code local -a args tmp=$(mktemp) while :; do args=(-sS -g -o "$tmp" -w '%{http_code}' -X "$method" -H "x-api-key: ${key}" -H 'content-type: application/json') if [ -n "$body" ]; then args+=(--data-binary "$body"); fi code=$(curl "${args[@]}" "$url" || echo 000) case "$code" in 429 | 000 | 5??) attempt=$((attempt + 1)) [ "$attempt" -le 6 ] || break echo " HTTP ${code} on ${method} ${url} — retry ${attempt} in $((attempt * 10))s" >&2 sleep $((attempt * 10)) ;; *) break ;; esac done FB_BODY=$(cat "$tmp"); rm -f "$tmp"; FB_CODE="$code" case "$code" in 2??) return 0 ;; *) return 1 ;; esac } die() { echo "$1" >&2; exit 1; } # Every action class in a workspace, as a JSON array. The v3 endpoint caps limit at 100 and pages by # cursor, so a workspace with more than 100 actions needs the loop or the name map silently loses # entries and live app surveys come out as drafts. fb_action_classes() { # local url="$1" key="$2" ws="$3" cursor="" acc='[]' while :; do fb GET "${url}/api/v3/action-classes?workspaceId=${ws}&limit=100${cursor:+&cursor=${cursor}}" "$key" || die "could not list action classes for ${ws} (HTTP ${FB_CODE}): ${FB_BODY}" acc=$(jq -c --argjson acc "$acc" '$acc + .data' <<<"$FB_BODY") cursor=$(jq -r '.meta.nextCursor // empty' <<<"$FB_BODY") [ -n "$cursor" ] || break done printf '%s' "$acc" } # 1. Read the survey document from the source. fb GET "${SOURCE_URL}/api/v3/surveys/${SOURCE_SURVEY_ID}" "$SOURCE_API_KEY" || die "could not read source survey (HTTP ${FB_CODE}): ${FB_BODY}" survey=$(jq '.data' <<<"$FB_BODY") echo "source: $(jq -r '.name' <<<"$survey") ($(jq -r '.type' <<<"$survey"), $(jq -r '.status' <<<"$survey"))" # 2. App surveys only: match the source triggers to target action classes by NAME. Ids differ per # instance, and an app survey with no trigger cannot be live. trigger_map='{}' if [ "$(jq -r '.type' <<<"$survey")" != "link" ]; then source_actions=$(fb_action_classes "$SOURCE_URL" "$SOURCE_API_KEY" "$(jq -r '.workspaceId' <<<"$survey")") target_actions=$(fb_action_classes "$TARGET_URL" "$TARGET_API_KEY" "$TARGET_WORKSPACE_ID") trigger_map=$(jq -n --argjson src "$source_actions" --argjson dst "$target_actions" ' ($dst | map({key: .name, value: .id}) | from_entries) as $byName | $src | map(select($byName[.name])) | map({key: .id, value: $byName[.name]}) | from_entries') echo "triggers: mapped $(jq 'length' <<<"$trigger_map") of $(jq 'length' <<<"$source_actions") action classes by name" fi # 3. Translate the resource into a create document and post it. body=$(jq -c --arg ws "$TARGET_WORKSPACE_ID" --argjson ac "$trigger_map" ' del(.id, .workspaceId, .createdAt, .updatedAt, .archivedAt, .targeting) | .workspaceId = $ws | .metadata = (.metadata // {}) | .type = (if .type == "link" then "link" else "app" end) | .languages |= map({code, default, enabled}) | if .type == "app" and (.distribution | type) == "object" then .distribution.triggers = [.distribution.triggers[] | select($ac[.actionClassId]) | {actionClassId: $ac[.actionClassId]}] else . end | if .type == "app" and ((.distribution.triggers // []) | length) == 0 then .status = "draft" else . end ' <<<"$survey") fb POST "${TARGET_URL}/api/v3/surveys" "$TARGET_API_KEY" "$body" || die "creating the survey failed (HTTP ${FB_CODE}): ${FB_BODY}" new_id=$(jq -r '.data.id' <<<"$FB_BODY") echo "target: ${new_id}" sleep "$THROTTLE" if [ "$(jq -r '.archivedAt // "null"' <<<"$survey")" != "null" ]; then fb POST "${TARGET_URL}/api/v3/surveys/${new_id}/archive" "$TARGET_API_KEY" '{}' || echo "could not re-archive ${new_id} (HTTP ${FB_CODE}): ${FB_BODY}" >&2 sleep "$THROTTLE" fi # 4. Replay the responses, oldest first, 250 at a time. ok=0; failed=0; skip=0 while :; do fb GET "${SOURCE_URL}/api/v2/management/responses?surveyId=${SOURCE_SURVEY_ID}&limit=250&skip=${skip}&sortBy=createdAt&order=asc" \ "$SOURCE_API_KEY" || die "reading responses failed (HTTP ${FB_CODE}): ${FB_BODY}" batch="$FB_BODY" count=$(jq '.data | length' <<<"$batch") while read -r response; do [ -n "$response" ] || continue payload=$(jq -c --arg sid "$new_id" ' {surveyId: $sid, createdAt, updatedAt, finished, data, variables, meta, language, endingId, singleUseId, # ttc._total is recomputed on the target for finished responses; sending the stored one doubles it. ttc: (.ttc | del(._total)), userId: (.contactAttributes.userId // null)} | with_entries(select(.value != null)) | .finished = (.finished // false) ' <<<"$response") if fb POST "${TARGET_URL}/api/v2/management/responses" "$TARGET_API_KEY" "$payload"; then ok=$((ok + 1)) else failed=$((failed + 1)) echo "response $(jq -r '.id' <<<"$response") failed (HTTP ${FB_CODE}): ${FB_BODY}" >&2 fi sleep "$THROTTLE" done < <(jq -c '.data[]' <<<"$batch") [ "$count" -eq 250 ] || break skip=$((skip + 250)) done echo "responses: ${ok} imported, ${failed} failed" echo "link: ${TARGET_URL}/s/${new_id}" ``` The survey ID is the last path segment of the survey's URL in the app, `/workspaces//surveys//edit`. ```bash theme={null} SOURCE_URL=https://old.formbricks.example.com \ SOURCE_API_KEY=fbk_xxx \ SOURCE_SURVEY_ID=cmrsxxwej0009tm06aq5i4lx0 \ TARGET_URL=https://new.formbricks.example.com \ TARGET_API_KEY=fbk_yyy \ TARGET_WORKSPACE_ID=cmt8fp2zt00024906cy3ysb8g \ ./fb-copy-survey.sh ``` ``` source: Link survey (link, inProgress) target: cmt8wewit0008s706rsqaqtf1 response cmrszt8n7000btm06nbo0evhh failed (HTTP 400): {"error":{"code":400,"message":"Bad Request", … responses: 1 imported, 1 failed link: https://new.formbricks.example.com/s/cmt8wewit0008s706rsqaqtf1 ``` Failures are printed per response on stderr and counted, but they do not stop the run — redirect stderr to a file if you are moving enough responses that you will want to read them afterwards. For an app survey, the trigger line tells you whether the survey came out live or as a draft: ``` source: Start from scratch (app, inProgress) triggers: mapped 0 of 4 action classes by name target: cmt8we5b20000s706bn4yzoyz ← created as a draft, no trigger matched ``` ## Step 1: Export the source workspace Steps 1 to 4 are the workspace-wide path: every survey at once, with the export kept on disk so you can inspect it, hold it as a backup, and re-run the import from it. This step touches nothing on the source instance. ```bash fb-export.sh theme={null} #!/usr/bin/env bash # Export every survey, response and action class of one Formbricks workspace. set -euo pipefail SOURCE_URL="${SOURCE_URL:?e.g. https://old.formbricks.example.com}" SOURCE_API_KEY="${SOURCE_API_KEY:?API key with manage access on the source workspace}" SOURCE_WORKSPACE_ID="${SOURCE_WORKSPACE_ID:?workspace id, see the app URL}" OUT_DIR="${OUT_DIR:-./fb-export}" # GET with retry on 429 (100 requests/minute per API key) and on 5xx. fb_get() { local url="$1" attempt=0 tmp code tmp=$(mktemp) while :; do code=$(curl -sS -g -o "$tmp" -w '%{http_code}' -H "x-api-key: ${SOURCE_API_KEY}" "$url" || echo 000) case "$code" in 429 | 000 | 5??) attempt=$((attempt + 1)) [ "$attempt" -le 6 ] || break echo " HTTP ${code} on ${url} — retry ${attempt} in $((attempt * 10))s" >&2 sleep $((attempt * 10)) ;; *) break ;; esac done cat "$tmp"; rm -f "$tmp" case "$code" in 2??) ;; *) echo "GET ${url} failed with HTTP ${code}" >&2; return 1 ;; esac } mkdir -p "$OUT_DIR/surveys" "$OUT_DIR/responses" # 1. All survey ids, archived ones included, via cursor pagination. : > "$OUT_DIR/survey-ids.txt" cursor="" while :; do page=$(fb_get "${SOURCE_URL}/api/v3/surveys?workspaceId=${SOURCE_WORKSPACE_ID}&limit=100&includeTotalCount=false&filter[status][in]=draft,inProgress,paused,completed,archived${cursor:+&cursor=${cursor}}") jq -r '.data[].id' <<<"$page" >> "$OUT_DIR/survey-ids.txt" cursor=$(jq -r '.meta.nextCursor // empty' <<<"$page") [ -n "$cursor" ] || break done # 2. Action classes — app-survey triggers reference these by id. This v1 endpoint returns action # classes for EVERY workspace the key can reach, so filter to the one being exported; otherwise # the import recreates another workspace's actions in the target. fb_get "${SOURCE_URL}/api/v1/management/action-classes" \ | jq --arg ws "$SOURCE_WORKSPACE_ID" '[.data[] | select(.workspaceId == $ws)]' \ > "$OUT_DIR/action-classes.json" # 3. Full survey document + every response, one JSON Lines file per survey. while read -r id; do [ -n "$id" ] || continue fb_get "${SOURCE_URL}/api/v3/surveys/${id}" | jq '.data' > "$OUT_DIR/surveys/${id}.json" : > "$OUT_DIR/responses/${id}.json" skip=0 while :; do batch=$(fb_get "${SOURCE_URL}/api/v2/management/responses?surveyId=${id}&limit=250&skip=${skip}&sortBy=createdAt&order=asc") jq -c '.data[]' <<<"$batch" >> "$OUT_DIR/responses/${id}.json" [ "$(jq '.data | length' <<<"$batch")" -eq 250 ] || break skip=$((skip + 250)) done printf '%s %s responses %s\n' "$id" "$(wc -l < "$OUT_DIR/responses/${id}.json" | tr -d ' ')" \ "$(jq -r '.name' "$OUT_DIR/surveys/${id}.json")" done < "$OUT_DIR/survey-ids.txt" echo "exported $(wc -l < "$OUT_DIR/survey-ids.txt" | tr -d ' ') surveys to ${OUT_DIR}" ``` ```bash theme={null} SOURCE_URL=https://old.formbricks.example.com \ SOURCE_API_KEY=fbk_xxx \ SOURCE_WORKSPACE_ID=cmrsx9nej0001tm061tt2pmbk \ ./fb-export.sh ``` ``` cms67qmmi000022c25w0ztniy 20 responses Product Market Fit (Superhuman) cmrsxa61o0008tm067ak8vqxc 1 responses Start from scratch cmrsxxwej0009tm06aq5i4lx0 2 responses Link survey exported 3 surveys to ./fb-export ``` The `-g` flag on `curl` is not optional — the `filter[status][in]` parameter contains square brackets, which curl otherwise reads as a globbing range. ## Step 2: Import into the target workspace The endpoints used to create surveys are strict: they accept a survey **document**, not the resource you just read. The `jq` filter in the script does the translation, and each line of it exists because the API rejects the request without it: * `del(.id, .workspaceId, .createdAt, .updatedAt, .archivedAt)` — read-only fields. The document endpoint rejects unknown keys rather than ignoring them, so leaving them in returns `400` with `invalid_params`. * `.languages |= map({code, default, enabled})` — `GET` returns an extra `alias` per language that `POST` rejects. * `.type = (if .type == "link" then "link" else "app" end)` — older instances still store the legacy `website` and `web` types; only `link` and `app` can be created. * `.metadata = (.metadata // {})` — `metadata` may be `null` on read but must be an object on write. * Trigger rewriting and the app-survey `status` fallback — see [App surveys](#app-surveys). Block, element and ending IDs are **not** stripped. The API accepts them, and keeping them is the whole trick: a replayed response's `data` is keyed by element ID and its `endingId` points at an ending, so carrying those IDs over is what makes the responses land on the right questions instead of being rejected as invalid. ```bash fb-import.sh theme={null} #!/usr/bin/env bash # Import a ./fb-export dump into a target Formbricks workspace. Idempotent it is not: # running it twice creates a second copy of everything. set -euo pipefail TARGET_URL="${TARGET_URL:?e.g. https://new.formbricks.example.com}" TARGET_API_KEY="${TARGET_API_KEY:?API key with manage access on the target workspace}" TARGET_WORKSPACE_ID="${TARGET_WORKSPACE_ID:?workspace id, see the app URL}" IN_DIR="${IN_DIR:-./fb-export}" THROTTLE="${THROTTLE:-0.7}" # seconds between writes; keeps you under 100 requests/minute fb_post() { local url="$1" body="$2" attempt=0 tmp code tmp=$(mktemp) while :; do code=$(curl -sS -g -o "$tmp" -w '%{http_code}' -X POST \ -H "x-api-key: ${TARGET_API_KEY}" -H 'content-type: application/json' \ --data-binary "$body" "$url" || echo 000) case "$code" in 429 | 000 | 5??) attempt=$((attempt + 1)) [ "$attempt" -le 6 ] || break echo " HTTP ${code} on ${url} — retry ${attempt} in $((attempt * 10))s" >&2 sleep $((attempt * 10)) ;; *) break ;; esac done FB_BODY=$(cat "$tmp"); rm -f "$tmp"; FB_CODE="$code" case "$code" in 2??) return 0 ;; *) return 1 ;; esac } # 1. Action classes. Keyed by source id so app-survey triggers can be rewritten below. : > "$IN_DIR/action-class-map.tsv" jq -c '.[]' "$IN_DIR/action-classes.json" | while read -r ac; do body=$(jq -c --arg ws "$TARGET_WORKSPACE_ID" \ '{workspaceId: $ws, name, description, type, key, noCodeConfig} | with_entries(select(.value != null))' <<<"$ac") if fb_post "${TARGET_URL}/api/v1/management/action-classes" "$body"; then printf '%s\t%s\n' "$(jq -r '.id' <<<"$ac")" "$(jq -r '.data.id' <<<"$FB_BODY")" >> "$IN_DIR/action-class-map.tsv" else echo "action class $(jq -r '.name' <<<"$ac") failed (HTTP ${FB_CODE}): ${FB_BODY}" >&2 fi sleep "$THROTTLE" done # 2. Surveys. The target assigns fresh survey ids; block, element and ending ids are carried over # verbatim, which is what keeps the imported responses readable. : > "$IN_DIR/survey-id-map.tsv" for file in "$IN_DIR"/surveys/*.json; do old_id=$(jq -r '.id' "$file") body=$(jq -c --arg ws "$TARGET_WORKSPACE_ID" --slurpfile acmap <( jq -R 'split("\t") | {(.[0]): .[1]}' "$IN_DIR/action-class-map.tsv" | jq -s 'add // {}' ) ' ($acmap[0] // {}) as $ac | del(.id, .workspaceId, .createdAt, .updatedAt, .archivedAt, .targeting) | .workspaceId = $ws | .metadata = (.metadata // {}) # POST accepts only link and app; legacy website/web surveys are app surveys. | .type = (if .type == "link" then "link" else "app" end) # GET returns an "alias" per language that POST rejects. | .languages |= map({code, default, enabled}) | if .type == "app" and (.distribution | type) == "object" then .distribution.triggers = [.distribution.triggers[] | select($ac[.actionClassId]) | {actionClassId: $ac[.actionClassId]}] else . end # An app survey with no trigger cannot be live. | if .type == "app" and ((.distribution.triggers // []) | length) == 0 then .status = "draft" else . end ' "$file") if ! fb_post "${TARGET_URL}/api/v3/surveys" "$body"; then echo "survey ${old_id} failed (HTTP ${FB_CODE}): ${FB_BODY}" >&2 continue fi new_id=$(jq -r '.data.id' <<<"$FB_BODY") printf '%s\t%s\n' "$old_id" "$new_id" >> "$IN_DIR/survey-id-map.tsv" echo "survey ${old_id} -> ${new_id}" sleep "$THROTTLE" # Archived surveys are recreated active; archive them again. if [ "$(jq -r '.archivedAt // "null"' "$file")" != "null" ]; then fb_post "${TARGET_URL}/api/v3/surveys/${new_id}/archive" '{}' || echo "could not re-archive ${new_id} (HTTP ${FB_CODE}): ${FB_BODY}" >&2 sleep "$THROTTLE" fi done # 3. Responses. createdAt/updatedAt survive; response ids do not. while IFS=$'\t' read -r old_id new_id; do [ -s "$IN_DIR/responses/${old_id}.json" ] || continue ok=0; failed=0 while read -r response; do body=$(jq -c --arg sid "$new_id" ' {surveyId: $sid, createdAt, updatedAt, finished, data, variables, meta, language, endingId, singleUseId, # ttc._total is recomputed on the target for finished responses; sending the stored one doubles it. ttc: (.ttc | del(._total)), userId: (.contactAttributes.userId // null)} | with_entries(select(.value != null)) | .finished = (.finished // false) ' <<<"$response") if fb_post "${TARGET_URL}/api/v2/management/responses" "$body"; then ok=$((ok + 1)) else failed=$((failed + 1)) echo "response $(jq -r '.id' <<<"$response") failed (HTTP ${FB_CODE}): ${FB_BODY}" >&2 fi sleep "$THROTTLE" done < "$IN_DIR/responses/${old_id}.json" echo "responses ${old_id} -> ${new_id}: ${ok} imported, ${failed} failed" done < "$IN_DIR/survey-id-map.tsv" ``` ```bash theme={null} TARGET_URL=https://new.formbricks.example.com \ TARGET_API_KEY=fbk_yyy \ TARGET_WORKSPACE_ID=cmt8fp2zt00024906cy3ysb8g \ ./fb-import.sh ``` ``` survey cmrsxa61o0008tm067ak8vqxc -> cmt8onri8000uj606c2wei9ao survey cmrsxxwej0009tm06aq5i4lx0 -> cmt8onsvj000xj606qo8mevz6 survey cms67qmmi000022c25w0ztniy -> cmt8ontog000yj606jpfqxpeb responses cmrsxa61o0008tm067ak8vqxc -> cmt8onri8000uj606c2wei9ao: 1 imported, 0 failed responses cmrsxxwej0009tm06aq5i4lx0 -> cmt8onsvj000xj606qo8mevz6: 1 imported, 1 failed responses cms67qmmi000022c25w0ztniy -> cmt8ontog000yj606jpfqxpeb: 20 imported, 0 failed ``` Two files are written next to the dump and are worth keeping: `survey-id-map.tsv` maps every old survey ID to its new one, and `action-class-map.tsv` does the same for actions. You need the survey map to update links, QR codes, embed snippets and SDK calls that referenced the old IDs. > [!WARNING] > > The import is **not** idempotent. There is no natural unique key on a survey or a response, so a > second run creates a second copy of everything rather than skipping what exists. If a run fails > partway, delete what it created in the target before retrying — or trim the input files down to what > is missing. ## Step 3: Verify Compare the exported count against what landed, survey by survey. ```bash fb-verify.sh theme={null} #!/usr/bin/env bash # Compare the exported response count with what actually landed in the target, survey by survey. set -euo pipefail TARGET_URL="${TARGET_URL:?}" TARGET_API_KEY="${TARGET_API_KEY:?}" IN_DIR="${IN_DIR:-./fb-export}" count_target() { local survey_id="$1" skip=0 total=0 n while :; do n=$(curl -sS -g -H "x-api-key: ${TARGET_API_KEY}" \ "${TARGET_URL}/api/v2/management/responses?surveyId=${survey_id}&limit=250&skip=${skip}" | jq '.data | length') total=$((total + n)) [ "$n" -eq 250 ] || break skip=$((skip + 250)) done echo "$total" } printf '%-26s %-26s %9s %9s %s\n' SOURCE TARGET EXPORTED IMPORTED '' while IFS=$'\t' read -r old_id new_id; do expected=$(wc -l < "${IN_DIR}/responses/${old_id}.json" | tr -d ' ') actual=$(count_target "$new_id") [ "$expected" = "$actual" ] && flag=ok || flag='MISMATCH' printf '%-26s %-26s %9s %9s %s\n' "$old_id" "$new_id" "$expected" "$actual" "$flag" done < "${IN_DIR}/survey-id-map.tsv" ``` ``` SOURCE TARGET EXPORTED IMPORTED cmrsxa61o0008tm067ak8vqxc cmt8onri8000uj606c2wei9ao 1 1 ok cmrsxxwej0009tm06aq5i4lx0 cmt8onsvj000xj606qo8mevz6 2 1 MISMATCH cms67qmmi000022c25w0ztniy cmt8ontog000yj606jpfqxpeb 20 20 ok ``` A `MISMATCH` line points at responses the target refused. `fb-import.sh` printed the reason for each on stderr — the usual cause is a file upload, see below. Then open one imported survey's summary page and confirm the answers are attributed to the right questions. If element IDs had been lost, the responses would have been rejected outright rather than silently misfiled, so a summary that reads correctly is a good signal. ## Step 4: Finish by hand * **Re-point everything that used the old survey ID.** Link survey URLs are `https://your-instance.com/s/`, so every shared link, QR code, email campaign and embed snippet needs the new ID from `survey-id-map.tsv`. Old links keep working on the source instance if it is still running — if it is not, they break. * **Rebuild what the survey document does not carry**: styling, follow-up emails, quotas, single-use link settings, survey PIN, reCAPTCHA, custom head scripts, custom slug. * **Re-create app-survey targeting** (see below), then re-enable webhooks, integrations and workflows. * **Update your SDK setup** if you are moving app surveys: `workspaceId` and `appUrl` in `Formbricks.setup()` both still point at the old instance. ## App surveys App surveys reference things that live inside a workspace and therefore cannot be copied by value. **Triggers** point at action classes by ID. `fb-import.sh` handles this: it re-creates every action class in the target first (`POST /api/v1/management/action-classes`, which unlike the v3 read endpoint also accepts a `noCodeConfig`), then rewrites `distribution.triggers[].actionClassId` through the resulting map. Triggers whose action class failed to create are dropped. That matters, because an app survey with no trigger cannot be live: ```json theme={null} { "title": "Bad Request", "status": 400, "detail": "An app survey must have at least one trigger to be set to a non-draft status." } ``` The script therefore forces `status: "draft"` on any app survey that ended up with an empty trigger list, rather than failing the whole survey. **Targeting** is dropped by the script (`del(.targeting)`). Segment filters reference contact-attribute keys, segments and — for `surveyInteraction` filters — other survey IDs, none of which exist under the same IDs in the target. Re-create targeting in the app after the import. > [!WARNING] > > A live app survey that loses its targeting **targets everyone**. If the source survey was scoped to a > segment, keep it as a draft until you have rebuilt the filters in the target. ## Known limitations ### Renamed choices reject their older responses This is the one that costs the most responses in practice. A choice answer is stored as the choice's **label**, not its id — so if anyone renamed or removed a choice after responses came in, the stored answers no longer match the survey. The source instance keeps them either way; it never re-validates on read. The target does validate on create, and rejects them: ```json theme={null} { "error": { "code": 400, "message": "Bad Request", "details": [{ "field": "response.data.s0wo6kf11l25dotzibaptcx8", "issue": "Please enter a valid format", "meta": { "elementId": "s0wo6kf11l25dotzibaptcx8", "ruleId": "invalidOption" } }] } } ``` Run this against the export **before** importing, so you find out from a dump rather than from a half-migrated survey: ```bash fb-check-choices.sh theme={null} #!/usr/bin/env bash # Pre-flight: list stored answers that no longer match their element's current choices. set -euo pipefail IN_DIR="${IN_DIR:-./fb-export}" for survey in "$IN_DIR"/surveys/*.json; do id=$(jq -r '.id' "$survey") responses="$IN_DIR/responses/${id}.json" [ -s "$responses" ] || continue elements=$(jq -c '[.blocks[].elements[] | select(.choices) | {id, labels: [.choices[].label | to_entries[].value]}]' "$survey") if [ "$elements" = "[]" ]; then continue; fi offenders=$(jq -r --argjson els "$elements" ' . as $r | $els[] | . as $el | ($r.data[$el.id] // empty) | (if type == "array" then .[] else . end) | . as $v | select(($v | type) == "string" and (($el.labels | index($v)) == null)) | "\($el.id)\t\($v)" ' "$responses" | sort | uniq -c | sort -rn) if [ -n "$offenders" ]; then echo "$(jq -r '.name' "$survey") ($id)" echo "$offenders" | sed 's/^/ /' fi done ``` ``` Feedback Box (cmr22qltt7qju01x5t3x68mbn) 8 s0wo6kf11l25dotzibaptcx8 Feature Request 💡 4 s0wo6kf11l25dotzibaptcx8 Bug report 🐞 ``` Twelve of that survey's thirteen responses predate a choice rename, and all twelve would be refused. Your options, in order of how much they cost you: 1. **Add the historical labels back as choices on the target survey**, import, then remove them again. Validation only runs on create, so the imported responses stay valid afterwards. This keeps every response at the price of two `PATCH` calls. 2. **Rewrite the old label to the new one** in the export, if the mapping is unambiguous — `jq -c '.data. = "I have a problem"'`. You are editing history, so only do this when the rename was cosmetic. 3. **Accept the loss** and import the rest. The script reports each failure with its response id. > [!NOTE] > > An element with an **Other** option will list its free-text answers here too, because they match no > choice label by definition. Those import fine — ignore them. ### File-upload answers are rejected Uploaded files stay in the source instance's object storage, and their URLs encode the workspace and survey they belong to: ``` /storage/{workspaceId}/private/surveys/{surveyId}/elements/{elementId}/{fileName} ``` Both IDs change during the migration, so the target refuses the response: ```json theme={null} { "error": { "code": 400, "message": "Bad Request", "details": [{ "field": "response", "issue": "Invalid file upload response: each file URL must reference a file uploaded to this survey's file-upload element" }] } } ``` To carry these responses over you have to move the files first: download each one from the source, upload it to the target under the new survey and element, rewrite the URL in the response's `data`, and only then `POST` the response. If the files are not worth that, strip the file-upload element's key from `data` so the rest of the answer imports — you lose the attachment, not the response: ```bash theme={null} jq -c 'del(.data[""])' response.json ``` ### Surveys with no blocks cannot be created An untouched draft can have zero blocks. Reading it works, creating it does not: ```json theme={null} { "title": "Bad Request", "status": 400, "invalid_params": [{ "name": "blocks", "reason": "At least one block is required" }] } ``` Either skip these (there is nothing in them) or recreate them in the app. ### Time-to-complete needs `_total` stripped A finished response's `ttc` (time to complete, in milliseconds) carries a `_total` key alongside the per-element timings. On create, the target **recomputes** `_total` by summing the values it was given — and if you passed the stored `_total` along, that sum includes it, so the imported response ends up with exactly double the real total. Nothing errors; the number is just silently wrong. The scripts on this page therefore send `ttc` with `_total` removed and let the target recompute it: ``` ttc: (.ttc | del(._total)) ``` Only finished responses carry `_total`, and stripping it is safe either way. If you wrote your own importer, check one finished response's `ttc._total` against the source before trusting the rest. ### Displays are not migrated The **Displays** figure on a survey summary, and the *Starts %* / *Completed %* / drop-off numbers derived from it, come from display records — impressions, not responses. Those are not exposed by the management API, so an imported survey shows `-` for displays and 0% for the rates that divide by them. Response counts, completion counts and every per-question summary are correct. ### Response tags and contacts Response tags are readable via `GET /api/v1/management/responses` but no create endpoint accepts them, so they cannot be restored through the API. Contacts are workspace-scoped and are not migrated by these scripts. Responses that were tied to a contact are imported unlinked. `fb-import.sh` passes the source contact's `userId` through as the response's `userId`: if a contact with that `userId` already exists in the target workspace, the response is attached to it and the target's own contact attributes are copied onto the response. If no such contact exists, the response is created anonymously — this is silent, not an error. ### Everything outside surveys and responses Users, teams, organization settings, contacts and their attributes, segments, webhooks, integrations, API keys, workflows and dashboards are out of scope here. Contacts and contact-attribute keys have their own management endpoints (`/api/v2/management/contacts`, `/api/v2/management/contact-attribute-keys`) if you need them; the rest is a `pg_dump` job. ## Troubleshooting | Response | Cause | Fix | | - | - | - | | `400` `invalid_params` naming a field you did not touch | A read-only or unknown field left in the survey document — the endpoint rejects unknown keys rather than ignoring them | Check the `jq` filter is applied. The document accepts only `workspaceId`, `name`, `type`, `status`, `metadata`, `defaultLanguage`, `languages`, `welcomeCard`, `blocks`, `endings`, `hiddenFields`, `variables`, `distribution`, `targeting` | | `400` `unsupported_locale` | A translation uses a locale that is not declared in `languages` | Add the locale to `languages`, or drop the translation | | `400` `invalid_reference` | Logic jumps to a block or ending ID that is not in the same request | Import the whole survey document at once, never block by block | | `400` on a response, `field: "response"` | The response does not validate against the target survey — usually a file upload, or element IDs that were not carried over | See [File-upload answers](#file-upload-answers-are-rejected); confirm the survey was imported with its original element IDs | | `404` `display not found` on a response | A `displayId` from the source instance was sent along | Do not send `displayId` — the script omits it | | `403` on a create, while `TARGET_API_KEY` can still *list* surveys in the target | `TARGET_API_KEY` has read but not write on the target workspace, or that workspace was created after the key. A successful source read proves nothing here — the two ends use different keys | Create a **new** key on the target instance with the target workspace selected and `write`/`manage`; a key's workspace access cannot be edited after creation. Confirm with `GET /api/v3/surveys?workspaceId=` using `TARGET_API_KEY` | | `401` | The key is revoked, or the endpoint needs Organization access the key lacks (`/api/v2/me`) | Check the key still exists; add the workspace under Workspace Access with `manage` | | `429` | 100 requests/minute per API key | Raise `THROTTLE`; the scripts already back off and retry six times | *** **Need help?** Reach out in [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Migration Source: https://formbricks.com/docs/self-hosting/advanced/migration Formbricks Self-hosted version migration ## If a migration fails From Formbricks 5.3 on, one runner applies every database migration in order: the `formbricks-migrate` service on Docker Compose, the `formbricks-migration` Job on Kubernetes (the application pods themselves when the chart sets `migration.enabled: false`), or `formbricks-authzed-prepare` during a v5 to v6 upgrade. When a migration fails, the runner stops and no later migration runs. A failed schema migration then blocks every later run until you resolve it; a failed data migration is retried on the next run. > [!WARNING] > > Do not delete volumes, restore a backup or roll the images back before you know which migration failed and > why. Most failures are fixed in place. The output below can contain SQL and data from your instance, so keep > it out of public issues. ### Open a SQL session The steps below run SQL as the user that owns the Formbricks tables: > [tab] One-Click / Docker Compose > > ```bash theme={null} > docker compose exec postgres psql -U postgres -d formbricks > ``` > [tab] Kubernetes > > ```bash theme={null} > kubectl exec -it -n formbricks formbricks-postgresql-0 -- psql -U formbricks -d formbricks > ``` > > > [!NOTE] > > > > If your PostgreSQL pod has a different name, run `kubectl get pods -n formbricks` to find it. With an external or managed PostgreSQL, connect with `psql` as the user in `MIGRATE_DATABASE_URL`, or in `DATABASE_URL` if you do not set it. The migrations themselves need a direct or session-pooled connection: a transaction-mode pooler such as PgBouncer can split their session settings across server connections. ### 1. Find the failed migration The runner's output names it. `docker compose run … formbricks-migrate` and the update script print it to your terminal; `docker compose logs --tail=200 formbricks-migrate` has it only when the service ran under `docker compose up`. On Kubernetes, read `kubectl logs -n formbricks job/formbricks-migration` (by default the chart deletes the Job 300 seconds after it fails). A first failure prints `Schema migration batch failed:` with every migration in that batch; the error names the failed one as `Migration name:`, or as `migration_name="…"` when the real error was hidden. Every run after that stops with `P3009` and names it again. If you have no log, including with `formbricks-authzed-prepare`, which prints only `upgrade_database_migration_failed` (plus `"reason":"timeout"` when the step ran out its time limit rather than failing), the database always knows: ```sql theme={null} SELECT migration_name, started_at FROM "_prisma_migrations" WHERE finished_at IS NULL AND rolled_back_at IS NULL; ``` If that returns no row but the log says `Data migration … failed`, see [Data migrations](#data-migrations) below. If the log just stops without an error, the runner was stopped (Compose stops it after 300 seconds) and its last statement may still be running in PostgreSQL: check that first, as step 3 describes. ### 2. Find the real error The runner's error usually shows it after `Database error:`. If it shows only `current transaction is aborted, commands ignored until end of transaction block`, the migration runs in a transaction of its own and the [real error was hidden](https://github.com/prisma/prisma/issues/15295). Find it in the PostgreSQL log, on the `ERROR` line just before that one: ```bash theme={null} docker compose logs postgres | grep -E "ERROR|STATEMENT" kubectl logs -n formbricks formbricks-postgresql-0 | grep -E "ERROR|STATEMENT" ``` On a managed service, use your provider's database log. `canceling statement due to lock timeout` is the most common cause: another session held a lock on the table the migration changes, for example a long-running query, a backup, or an old Formbricks pod still running. Stop it, or retry at a quieter time. If the error itself lists recovery steps, as some migrations' guards do, follow those. ### 3. Check what the migration left behind First make sure nothing is still running it. On Compose, the runner has exited. On Kubernetes, the Job has finished retrying (`kubectl wait -n formbricks --for=condition=Failed job/formbricks-migration --timeout=10m` returns, or the Job is gone). With `migration.enabled: false` the application pods are the runner and retry on every restart, so scale them to 0 (`kubectl scale deploy -n formbricks formbricks --replicas=0`) until step 4. A statement keeps running in PostgreSQL after its runner is stopped, so also list what the database is still running: ```sql theme={null} SELECT pid, now() - query_start AS running_for, left(query, 80) AS query, pid IN (SELECT pid FROM pg_locks WHERE locktype = 'advisory' AND objid = 72707369) AS migration_lock FROM pg_stat_activity WHERE datname = current_database() AND state IS DISTINCT FROM 'idle' AND pid <> pg_backend_pid(); ``` `migration_lock` marks a schema migration: Prisma holds that lock while it applies one. Data migrations take no such lock, so also look for statements on the tables the migration changes. Wait for every migration statement to end. Then read the failed migration's file. A released migration never changes, so the copy in your image is the one that ran: ```bash theme={null} migration_name='' docker compose run --rm --no-deps --entrypoint cat formbricks-migrate \ "packages/database/dist/migration/${migration_name}/migration.sql" ``` It is also on GitHub under any release that ships it, for example `https://github.com/formbricks/formbricks/blob/6.0.2/packages/database/migration//migration.sql`. * **The runner printed an error, and the whole file is one `BEGIN; … COMMIT;` block, with no statement before `BEGIN;` or after `COMMIT;`:** PostgreSQL rolled the whole file back, so there is nothing to undo. A file that commits a block and then runs more statements, such as `20250911192630_remove_deprecated_fields_and_tables`, belongs under the next case. * **Otherwise, including any migration whose runner was stopped instead of printing an error:** the statements before the failing one may have taken effect, even inside a `BEGIN; … COMMIT;` block. For a stopped runner, possibly every statement in the file did: a file Prisma sends as one string runs to its end without a client. Check which did (`\d "Table"` for schema changes, a `SELECT` for data) and undo those before you continue. If the new version is already serving, stop it first (`docker compose stop formbricks`, or scale the Deployment to 0\) and keep it stopped until you run the migrations again. Undoing a `DROP` means recreating the object so the retry can drop it again; if a change cannot be undone, such as an `UPDATE` whose old values are gone, stop and restore the pre-upgrade backup instead. You need not undo: * `IF NOT EXISTS`, `IF EXISTS` and `CREATE OR REPLACE` statements are safe to repeat, apart from a failed `CREATE INDEX CONCURRENTLY`. That leaves an invalid index which `IF NOT EXISTS` then skips: list invalid indexes with `SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;` and drop only those the migration's file creates, with `SET lock_timeout = 0;` and then `DROP INDEX CONCURRENTLY`. * An `UPDATE`, `INSERT` or `DELETE` is safe to repeat only if running it twice changes nothing. ### 4. Mark it rolled back and run the migrations again Once the cause is fixed, mark the failed migration rolled back. This is what `prisma migrate resolve --rolled-back` does. It should report `UPDATE 1`; `UPDATE 0` means the name is wrong or the migration is not recorded as failed: ```sql theme={null} UPDATE "_prisma_migrations" SET rolled_back_at = now() WHERE migration_name = '' AND finished_at IS NULL AND rolled_back_at IS NULL; ``` Then run the migrations again: > [tab] One-Click / Docker Compose > > ```bash theme={null} > docker compose run --rm --no-deps formbricks-migrate && > docker compose up -d > ``` > > The service stops the runner after 300 seconds. If a migration needs longer, run it without that limit: > > ```bash theme={null} > docker compose run --rm --no-deps formbricks-migrate "node packages/database/dist/scripts/apply-migrations.js" && > docker compose up -d > ``` > > During a v5 to v6 upgrade, re-run `formbricks-authzed-prepare` as the > [v6 maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade) describes instead. > [tab] Kubernetes > > Delete the failed Job, then run the same `helm upgrade` (or Argo CD sync) again. Helm does not re-run a Job > that still exists, and refuses to change one (`field is immutable`): > > ```bash theme={null} > kubectl delete job -n formbricks formbricks-migration --ignore-not-found > ``` > > With `migration.enabled: false`, scale the Deployment back up instead; its pods run the migrations on start. > > Otherwise, if you scaled the Deployment to 0 in step 3, scale it back up once the Job succeeds > (`kubectl scale deploy -n formbricks formbricks --replicas=`). `helm upgrade` restores the count > only when `autoscaling.enabled` is false and `deployment.replicas` is set, and an autoscaler does not scale up > from 0. > > During a v5 to v6 upgrade, delete and re-create the `formbricks-v6-prepare` Job as the > [v6 maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade) describes instead. ### Data migrations Most data migrations run in a transaction of their own and leave nothing behind when they fail; the large ones commit in batches and are written to resume where they stopped. Either way the runner records the failure and retries the migration on the next run: fix the cause and run the migrations again. The exception is `Migration is pending. Please resolve the issue manually.`, left by an interrupted run of a version before 5.3. Make sure nothing is still running it (step 3), then mark it failed so the next run retries it: ```sql theme={null} SELECT name, status, started_at FROM "DataMigration" WHERE status <> 'applied'; UPDATE "DataMigration" SET status = 'failed' WHERE name = '' AND status = 'pending'; ``` ## v6 Formbricks v6 replaces the legacy authorization evaluator with SpiceDB, maintained by AuthZed. PostgreSQL remains the source of roles and grants, but SpiceDB is the sole decision engine. There is no runtime fallback, so an existing installation must prepare its complete authorization graph before serving v6 traffic. Use the supported source/target pair in the release notes and the [maintenance upgrade procedure](/docs/self-hosting/advanced/v6-maintenance-upgrade). A self-hosted v5 bridge is not required: 1. Enter maintenance, stop all writers, suspend their controllers, and drain in-flight work. Take recoverable backups of the databases, secrets, configuration, and source image versions. 2. Merge the release-matched AuthZed deployment services or Helm values without overwriting proxy, storage, SMTP, or external-datastore customization. 3. Run the target-image database migrations while writers remain stopped, never against the still-running v5 app. 4. Run `formbricks-authzed-prepare --backup-confirmed --writers-stopped`; it runs migrations, reconciliation, one clean full audit, and a second independent `upgrade check` audit. 5. For one-click or Compose, set `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true`. For Helm, set `authzed.migrationAcknowledged=true` in the v6 upgrade values. 6. Deploy v6 and verify critical allow, deny, revocation, and cross-tenant cases. The update script and Helm upgrade hook verify the prepared graph without repairing it. Do not bypass a failed gate. Keep maintenance active on failure: after database changes, recovery may require restoring coordinated backups rather than running `helm rollback`. Pin explicit releases and digests, not floating tags. The Helm chart and Formbricks image are versioned independently. A chart-only patch can retain the same `appVersion`; review both pins and the rendered image rather than assuming their version numbers match. ### Survey visibility (opt-in) Surveys can now be restricted to their owner and the organization's owners and managers. New columns on the `Survey` table record each survey's owner and visibility. The migrations set every existing survey to workspace-visible and make its creator the owner, so **access is unchanged after the upgrade**. > [!NOTE] > > Once the marker is set, every survey a person creates starts **Restricted** to its author and the > organization's owners and managers. They can make it visible to the workspace from **Collaborate** or > when activating it. See [Survey visibility](/docs/surveys/general-features/visibility). Stored visibility is always enforced. New visibility mutations and survey graph checks become available once an operator marks the survey scope ready: ```bash theme={null} formbricks-authzed backfill --scope=survey --apply --mark-ready ``` Once activated, a survey a person creates is restricted until they share it with the workspace. Regardless of readiness, API keys cannot see restricted surveys or responses; webhooks, integrations, feedback sources, follow-ups and workflows cannot receive them. Two new environment variables: * **SURVEY\_VISIBILITY\_FORCE\_DISABLED**: `1` disables visibility mutations. Stored restrictions remain enforced. Takes effect on restart. * **SURVEY\_WORKSPACE\_LIMIT**: most surveys one workspace may hold, archived ones included (default `10000`). This applies whether or not visibility is enforced: creating a survey past it answers `422 workspace_survey_limit_reached`. Raise it before upgrading if a workspace is near the default. To stop new visibility mutations and use PostgreSQL policy while repairing the survey graph, clear the marker. Stored restrictions remain enforced: ```bash theme={null} formbricks-authzed backfill --scope=survey --clear-ready ``` ### Bundled TEI log level The Helm chart now defaults `hub.embeddings.env.RUST_LOG` to `warn` because TEI 1.9 includes its API key in INFO-level startup arguments. If you need a different log level, set `hub.embeddings.env.RUST_LOG` explicitly and use it only with a runtime that redacts credentials from its logs. ### Database transaction limits Formbricks now sets its database transaction limits explicitly instead of relying on library defaults. Under load, the old 5-second limit was cancelling writes that were about to succeed: user identification, response updates and survey resets. The new limits are at least as permissive as the old ones, so they need no upgrade step of their own. * Transactions may run for up to 20 seconds. * Waiting for a free database connection is bounded by `connect_timeout` in `DATABASE_URL` (5 seconds by default). With `connect_timeout=0`, transactions give up waiting after 6 seconds; other queries wait until a connection is free. #### Idle transactions (opt-in) PostgreSQL can end any session left idle inside an open transaction, which releases the locks that session holds and frees its connection. Formbricks does not ask for this by default: it travels as a startup parameter, and a server or pooler that does not accept the parameter refuses the whole connection instead of ignoring it. Turn it on by adding it to `DATABASE_URL` in **milliseconds**: ```bash theme={null} DATABASE_URL="postgresql://user:password@host:5432/formbricks?idle_in_transaction_session_timeout=60000" ``` Leaving the parameter out, or setting it to `0`, sends nothing and keeps your server's own setting. An invalid value (anything but digits, or past PostgreSQL's 32-bit limit) sends nothing and logs a warning. It applies to every process that connects with that `DATABASE_URL` — the migration runner uses `MIGRATE_DATABASE_URL` instead when that is set, so it follows that one. Keep the value well above the longest a migration leaves a transaction idle, or leave the parameter out. > [!WARNING] > > Do not set it if Formbricks reaches PostgreSQL through **PgBouncer, Supavisor, RDS Proxy or another > pooler**: PgBouncer answers a connection carrying a startup parameter it does not know with > `FATAL: unsupported startup parameter: idle_in_transaction_session_timeout`. Listing the parameter in > PgBouncer's `ignore_startup_parameters` lets the connection through, but PgBouncer then drops it, so the > safeguard does not apply either way. If `DATABASE_URL` carries both the parameter and `pgbouncer=true`, > Formbricks sends it and logs a warning. ### One-click: port 3000 is published on the host only The one-click installer now publishes the Formbricks container's port `3000` on `127.0.0.1` instead of every interface, and `./formbricks.sh update` changes an existing one-click installation the same way, in `docker-compose.yml` and in your Compose override file if you have one, keeping each original as `.before-loopback-port`. Traefik keeps serving Formbricks on ports `80` and `443`, so the app is only reachable from outside through Traefik and its TLS and request limits. For that to hold against other machines on the same local network, Docker Engine must be 28.0 or later and not 28.2.0 to 28.3.2; the installer and the update warn on those versions. If you reach port `3000` from other machines on purpose, publish it on an explicit address after updating, such as `- 0.0.0.0:3000:3000` (add `- "[::]:3000:3000"` for IPv6). The update only rewrites the bare `- 3000:3000` mapping, so it leaves an address you chose alone; putting the bare mapping back would be narrowed again next time. Compose setups that don't use the one-click script are not changed. If yours publishes `3000:3000` and a reverse proxy on the same host is the intended way in, bind it to `127.0.0.1:3000:3000` as well. ### Changes in Environment Variables > [!NOTE] > > `DEFAULT_ORGANIZATION_ID` and `DEFAULT_ORGANIZATION_ROLE` drive SSO just-in-time provisioning, which is > part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license). On a community instance > they have no effect, so there is nothing to rename. * **DEFAULT\_ORGANIZATION\_ID** has been renamed to **AUTH\_SSO\_DEFAULT\_ORGANIZATION\_ID**, matching the `AUTH_SSO_DEFAULT_TEAM_ID` naming pattern. Rename the variable in your configuration; the value is unchanged. Support for this variable was missing between v3.0 and v5.x, so it takes effect again on v6. * **DEFAULT\_ORGANIZATION\_ROLE** has been renamed to **AUTH\_SSO\_DEFAULT\_ORGANIZATION\_ROLE**. * **AUTHZED\_CONSISTENCY** must be `fully_consistent`. v6 refuses to start with any other value, or with the variable unset. An existing `.env` that still sets `AUTHZED_CONSISTENCY=minimize_latency` must be changed to `AUTHZED_CONSISTENCY=fully_consistent` before upgrading. * **BETTER\_AUTH\_URL** and **BETTER\_AUTH\_SECRET** are now the documented names for the auth base URL and the session-signing secret. This is a documentation change, not a rename: `NEXTAUTH_URL` and `NEXTAUTH_SECRET` keep working exactly as before, so **an existing instance needs no action**. New installs configure the `BETTER_AUTH_*` names, which is what the setup guides now show. > [!WARNING] > > If you do choose to move to the new names, **copy the existing value across** rather than generating a > new one. `BETTER_AUTH_SECRET` takes precedence, so setting it to a *different* value signs everyone > out and invalidates outstanding invite, email-verification and email-change links. Formbricks logs a > warning at startup when both are set to different values. The secret is no longer rejected for being > shorter than 32 characters, so a shorter legacy value can be renamed as-is — you will see a startup > warning recommending a longer one, which you can act on whenever a forced sign-out is acceptable. Formbricks now refuses to start when neither variable has a value, in every environment. Before this release that refusal applied only when `NODE_ENV=production`; a development or test instance with neither variable set still started, using a fallback value for the signing secret, and only invites and verification links failed. So a production instance is already required to have one of these set and is unaffected. If a non-production instance of yours set neither, generate a secret before upgrading — doing so **signs every current user out**, because their cookies were signed with that fallback value rather than with a secret of yours. ### Encrypted single-use survey links must be regenerated (action required if you use them) Encrypted single-use survey links issued before v6 stop working and have to be regenerated. #### What to do when upgrading **Regenerate after upgrading, not before.** Links minted by the old version are unsigned whichever day you mint them, so regenerating first produces a second batch that the new version rejects exactly like the first. 1. Plan a maintenance window covering the deploy and the redistribution. Outstanding links stop working the moment the new version serves traffic, and a respondent who opened one before the deploy and submits after it sees the invitation error and loses their answers. 2. Deploy v6. 3. Regenerate the links for any survey with single-use enabled and **URL encryption of single-use ID** on, from the survey's share modal or via `GET /api/v1/management/surveys/{surveyId}/singleUseIds`. The new version signs them. 4. Re-send. Formbricks never stores generated links, so there is nothing to migrate and nothing to back up — the new links simply replace the old ones. **Links with URL encryption off are unaffected**, including custom single-use IDs. Those have carried a `suToken` signature since 5.0 and validate exactly as before, so integrations that mint their own IDs need no changes. #### What you will see if you skip it Opening an old encrypted link shows *"This survey can only be taken by invitation"*, and submissions against it are rejected. Server logs record one `warn` per rejection carrying the survey id and a `reason` of `missing_signature`. #### Why An encrypted single-use link carried only an encrypted id and no signature, so nothing tied it to the survey it was issued for and any survey on the same deployment accepted it. Both modes now carry the same signature, which is what the old links are missing. #### If you cannot re-issue in time `SINGLE_USE_LEGACY_UNSIGNED_UNTIL` keeps the old links working for a fixed period, so an in-flight campaign does not die on upgrade day. It takes an ISO 8601 date and is unset by default: ```sh theme={null} SINGLE_USE_LEGACY_UNSIGNED_UNTIL=2026-11-15 ``` Unsigned **encrypted** links are accepted until 00:00 UTC on that date, and rejected from then on. Nothing else changes: links with URL encryption off are untouched, a `suToken` that is present but wrong is still rejected, and the id must still decrypt under your `ENCRYPTION_KEY`. > [!WARNING] > > This re-opens the vulnerability the release closed, for as long as it is set. An unsigned encrypted > link is bound to no survey, so a link issued for one survey opens **any** survey on the same > instance — on a deployment serving more than one organisation, that is across organisations. Set it > only on a single-tenant instance, only for as long as re-issuing takes, and only as a deliberate > decision. It is not a substitute for step 3 above. Each accepted legacy link is logged at `warn` with the survey id and the configured expiry, and counted on `formbricks_survey_single_use_link_validations_total` with `reason="legacy_unsigned"`. Watch that series fall to zero, then remove the variable — it tells you when the window has stopped carrying traffic and re-issuing is complete. #### Rollback Downgrading restores the old links, since nothing about them changed on disk — but it also restores the behaviour above, so treat it as a stopgap while you regenerate rather than a fix. ### Hub worker for Docker Fresh Docker and one-click installations start `hub-worker` with the Hub API. It has been part of the stack since v5 and is what the bundled Compose file ships. The worker consumes every PostgreSQL-backed asynchronous Hub job, including webhook deliveries and any configured enrichment, so an installation that runs the Hub API without it leaves those jobs queued. An existing installation keeps its local `docker-compose.yml` during `formbricks.sh update`, so the updater cannot add the service for you. Adding it is recommended rather than required in this release: the updater prints a warning and continues when the resolved Compose project does not contain `hub-worker`. The next major release will require it, so merging it now avoids the interruption later. 1. Start in the directory containing your customized `docker-compose.yml`, then back it up and download the file from the release you are upgrading to. For a one-click installation, run `cd formbricks` first. Use that release's tag instead of `stable` when your deployment is pinned. ```bash theme={null} cp -p docker-compose.yml docker-compose.yml.before-hub-worker curl -fsSL -o docker-compose.release.yml \ https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/docker-compose.yml ``` 2. Compare the two files. Merge `x-hub-runtime-environment` and the release's `hub` and `hub-worker` sections as one unit so the API and worker retain the same database and taxonomy configuration. Preserve local proxy, storage, database, and image-pin customizations. `hub`, `hub-worker`, and `hub-migrate` must resolve to the same Hub image reference. 3. Validate the result before changing the running stack: ```bash theme={null} docker compose config >/dev/null docker compose config --services | grep -Fx hub-worker ``` 4. For a one-click installation, rerun `./formbricks.sh update` — the warning disappears once the resolved project contains `hub-worker`. For a manually managed Compose installation, apply Hub migrations before starting the API and worker from the new image: ```bash theme={null} docker compose pull hub hub-migrate hub-worker docker compose up --force-recreate hub-migrate docker compose up -d hub hub-worker ``` 5. Verify that the worker stays running and that the existing River backlog decreases: ```bash theme={null} docker compose ps hub-worker docker compose logs --tail=200 hub-worker ``` The worker has no HTTP health endpoint. A stable process and decreasing queue are the readiness signals. If it restarts, verify PostgreSQL connectivity and every configured enrichment provider credential. Jobs already in River remain stored in PostgreSQL and begin draining when the worker starts; no repair or re-enqueue is required. To roll back only this change, remove the worker container before restoring the backed-up Compose file so its `restart: always` policy cannot start it again: ```bash theme={null} docker compose rm -fs hub-worker cp -p docker-compose.yml.before-hub-worker docker-compose.yml ``` Completed jobs remain committed and pending jobs remain queued, but all Hub asynchronous processing pauses again. A fully custom deployment that runs Hub workers outside this Compose project can ignore the warning: the update is not blocked. ### Cube model files for Docker 6.1 adds the `npsCount` measure and the `valueBand` dimension to the Cube model. The **NPS breakdown** and **CSAT breakdown** chart presets use them. On Docker the model is two files next to your Compose file, `cube/cube.js` and `cube/schema/FeedbackRecords.js`. Until they are refreshed, those presets fail with `'npsCount' not found`. * **One-click:** `./formbricks.sh update`, run with the current updater as described under [Update](/docs/self-hosting/setup/one-click#update), refreshes both files while the stack is stopped. It takes them from the release your Formbricks image runs, and keeps the previous copies in `cube/previous/`. If either file cannot be refreshed, both stay as they were, and the update finishes and prints the command to retry. If the image is pinned to a digest or a custom tag, the updater leaves both files alone; use the Docker Compose step below with your release's tag. * **Docker Compose:** run the Cube refresh step of the [Docker update](/docs/self-hosting/setup/docker#update) from the directory containing your `docker-compose.yml`. If you refresh outside an update, recreate Cube afterwards with `docker compose up -d --force-recreate cube`. * **Helm:** the chart ships the model, so `helm upgrade` replaces it. No action is needed. ### Bundled Cube image (action required for some deployments) From 6.0.2, the bundled Cube service runs `ghcr.io/formbricks/cube:1.7.47-2` instead of `cubejs/cube:v1.6.6`; 6.0.0 and 6.0.1 still run the upstream image. 5.4.5 makes the same change (see [Bundled Cube image update](#bundled-cube-image-update-action-required-for-some-deployments)). The new image contains only the Cube 1.7.47 API server and its Postgres driver on a distroless Node 24 runtime, without the shell, Python and Cube Store that made image scanners report critical CVEs against the upstream image. Cube 1.7 returns every numeric measure and dimension as a JSON string. Formbricks converts number-typed members back into numbers, so dashboards need no change; anything else that queries your Cube API directly now receives strings for them. * **Docker Compose and one-click**: `formbricks.sh update` keeps your local `docker-compose.yml`, so the stack stays on `cubejs/cube:v1.6.6` until you replace its whole `cube` service with the one from the release you are upgrading to. Changing only `image:` is not enough. The new image has no shell, so the old `command: sh -c '… exec cubejs server'` wrapper exits with `Error: Cannot find module '/cube/conf/sh'`. The image's own command starts Cube, which still refuses to start without `CUBEJS_API_SECRET`. Keep your own `CUBEJS_*` overrides when you merge the block. ```bash theme={null} version=6.0.2 # the release you are upgrading to, for example 5.4.5 cp -p docker-compose.yml docker-compose.yml.before-cube-image curl -fsSL -o docker-compose.release.yml \ "https://raw.githubusercontent.com/formbricks/formbricks/${version}/docker/docker-compose.yml" # Copy the release's `cube` service into docker-compose.yml, then: docker compose config >/dev/null docker compose pull cube docker compose up -d --no-deps --force-recreate cube docker compose ps cube ``` * **Helm**: the chart defaults to the new image. If your values set `cube.image.tag` without `cube.image.repository`, the chart now pulls a non-existent `ghcr.io/formbricks/cube:` and the pod fails with `ImagePullBackOff`. Drop the tag override, or set both values. Pointing them back at an upstream `cubejs/cube` release is supported. * **Helm security context**: the Cube container now runs with a read-only root filesystem, no privilege escalation and all capabilities dropped. The bundled image and upstream `cubejs/cube` releases need no change. A custom image or configuration that writes files, or dev mode on an upstream image, needs `cube.containerSecurityContext.readOnlyRootFilesystem: false`. * **`CUBEJS_DEV_MODE=true`**: not supported on the new image. Dev mode relies on the embedded Cube Store the image leaves out, so `/readyz` answers 500 and the Helm probes and Compose healthcheck never pass. Leave it unset in production. * **Air-gapped installs and registry mirrors**: mirror `ghcr.io/formbricks/cube:1.7.47-2` along with the other Formbricks images, then point the Compose `image:` or `cube.image.repository` at your mirror. Cube keeps no state of its own, so rolling back only this change means restoring the backed-up Compose file or your previous `cube.image` values and recreating the `cube` service. ## v5.4 v5.4 carries one application-level breaking change, and it is narrow: it affects **API keys** used against the Feedback Records API or the MCP server. If you do not use Unify Feedback, or you only reach it through the UI, there is nothing to do for it. The release adds no new environment variables. It does ship **seven database migrations**, applied automatically during the upgrade. Six are quick — new columns and tables, two of them data migrations that run on their own. The seventh builds an index on the `Response` table, and it is the one that needs planning: it blocks response writes while it builds, unless you build the index yourself first. Other migrations add indexes too, but only on new or small tables. See [Database migrations](#database-migrations) before scheduling the upgrade. v5.4 also upgrades the **Better Auth** authentication core to 1.7. That upgrade needs no manual database step — every migration is additive and applies automatically, including the backfills over existing rows — and **your SSO callback URLs do not change**. It carries one narrow exception, and only for custom code: an MCP access token is now bound to the session that authorized it, so an integration that caches one across sessions has to fetch a fresh token — see [MCP access tokens now end with their session](#mcp-access-tokens-now-end-with-their-session). The bundled Valkey image moves from an amd64-only 8.1.1 image to the native amd64/arm64 Valkey 8.1.9 Alpine image. Fresh Docker and Helm installations receive it automatically. Existing installations that retain an older Compose file or explicitly reuse the previous Helm digest need the one-time update below. ### Bundled Cube image update (action required for some deployments) 5.4.5 makes the same Cube change as 6.0.2: the bundled service moves from `cubejs/cube:v1.6.6` to `ghcr.io/formbricks/cube:1.7.47-2`, and Helm runs it with a read-only root filesystem. Follow [Bundled Cube image](#bundled-cube-image-action-required-for-some-deployments) with `version=5.4.5`, so the `cube` service you copy comes from the 5.4.5 Compose file rather than a 6.x one. ### Envoy Gateway 1.8.4 CRD Upgrade The updated Helm chart replaces Envoy Gateway 1.7.1 and Gateway API 1.4.1 with Envoy Gateway 1.8.4 and Gateway API 1.5.1. Fresh installations receive the new CRDs automatically. Helm does not update CRDs during an ordinary upgrade, so existing installations using the bundled controller must apply the matching CRDs before upgrading: ```bash theme={null} crd_dir="$(mktemp -d)" helm pull oci://docker.io/envoyproxy/gateway-crds-helm \ --version v1.8.4 --untar --untardir "${crd_dir}" helm template envoy-gateway-crds "${crd_dir}/gateway-crds-helm" \ --set crds.gatewayAPI.enabled=true \ --set crds.gatewayAPI.channel=experimental \ --set crds.envoyGateway.enabled=true \ | kubectl apply --server-side --force-conflicts -f - ``` `--force-conflicts` transfers the existing CRD fields from Helm's field manager to this explicit CRD upgrade. Pulling the OCI chart first keeps Helm 4's pull messages out of the manifest pipe. Remove the temporary directory after the apply succeeds. The chart does not install Envoy Gateway's cluster-wide safe-upgrade admission policy by default. Enabling `envoy.crds.gatewayAPI.safeUpgradePolicy.enabled` denies Gateway API CRD versions older than v1.5.0 across the whole cluster, including CRDs reconciled by unrelated releases. Enable it only after platform review; a chart rollback does not remove that policy automatically. If the platform already manages compatible Gateway API CRDs, do not install another Gateway API bundle. Install only the Envoy Gateway CRDs as described in the [Kubernetes guide](/docs/self-hosting/setup/kubernetes), set `envoy.crds.enabled=false`, and configure Flux to skip CRD installation and upgrades. Upgrade the CRDs before the controller and never downgrade them during rollback. The controller scheduling values also move from the ineffective `envoy.deployment.envoyGateway.pod` path to `envoy.deployment.pod`. Move any node selectors, tolerations, topology spread constraints, extra volumes, or pod annotations that you placed under the old path before upgrading. The parent chart no longer repeats the bundled controller's default port list. The `envoy.deployment.ports` override remains supported, so existing port overrides need no migration. ### Database migrations All seven migrations apply automatically during the upgrade. Two want something from you first: one needs `WEBAPP_URL` set if you use MCP OAuth, and one deserves a step of its own on large instances. So here is the full list rather than a summary: | Migration | What it does | Impact | | - | - | - | | `add_feedback_source_import_mode` | Adds `FeedbackSource.import_mode`, which controls whether a source's historical import includes partial responses. Existing sources take the `completedOnly` default, which aligns the historical import with the live ingestion path — that path only ever ran on finished responses, while the import used to pull partials too. Records already in Hub are left alone, so this shows up the next time you run an import: set a source to `all` if it should keep importing partial responses. | Instant | | `add_organization_display_time_zone` | Adds the nullable `Organization.displayTimeZone`, which formats response timestamps in file exports and in the payloads pushed to Google Sheets, Slack and Airtable (Notion is passed a raw date and is unaffected). | Instant | | `eng_2343_better_auth_17_resource_model` | The Better Auth 1.7 schema: the `oauthResource` tables, resource columns on OAuth tokens and consents, `alg`/`crv` on `jwks`, and `Account.issuer` with its backfill. Details in the Better Auth 1.7 section below. | Additive and fast. The issuer backfill is what keeps password sign-in working on 1.7, so it must not be skipped — it runs on its own, listed here so it is not mistaken for optional | | `eng_2343_backfill_oauth_resource_links` | Data migration linking existing MCP OAuth clients, refresh tokens and consents to this instance's `${WEBAPP_URL}/api/mcp` resource, so already-registered MCP clients survive the upgrade. It is a no-op only when the instance has no OAuth client at all, which in practice means a fresh install. | **Set `WEBAPP_URL` before upgrading if you use MCP OAuth.** The resource identifier is derived from it, so on an instance that has OAuth clients an unset or unparseable `WEBAPP_URL` fails this migration and stops the upgrade — set it and re-run | | `add_feedback_source_element_scope` | Adds `FeedbackSource.elementScope`, which controls whether a source picks up survey questions added later. Existing sources keep the current behaviour (`specific`). | Instant | | `add_response_survey_finished_index` | Adds an index on `Response(surveyId, finished)` so the survey list's response counts are served from the index instead of scanning the table. | **Blocks response writes while it builds, unless you build the index first — see below** | | `repair_account_issuer` | Data migration rewriting `Account.issuer` rows that were written with a non-canonical value, which locked the affected Google SSO users into a sign-in loop. Idempotent; a no-op when nothing is wrong. | Fast | > [!WARNING] > > `add_response_survey_finished_index` builds its index with a plain `CREATE INDEX`, which holds a `SHARE` > lock on `Response` for the whole build: reads keep working, but **survey responses cannot be written until > the index is built**. `Response` is usually the largest table on an instance. On small instances the build > takes seconds. If yours holds millions of responses, [build the index before you > upgrade](#build-the-response-index-before-you-upgrade) so the migration has nothing left to do, or run the > upgrade in a window where a pause in response collection is acceptable. > > If you leave the build to the migration, neither documented deployment avoids the pause. On Kubernetes the > chart runs migrations in their own job while the pods already running keep serving traffic, so the > responses arriving during the build are the ones that block. On Docker Compose the app container does > **not** wait for `formbricks-migrate` — it has no `depends_on` on that service and skips startup > migrations itself — so after the documented `docker compose down && docker compose up -d` the two come up > in parallel: you get downtime while the app boots, and then blocked writes for however much of the index > build is left once it starts serving. Compose also stops the migration runner after 300 seconds, so a longer > build ends as a failed migration; see [If a migration fails](#if-a-migration-fails). #### Build the response index before you upgrade The migration creates its index only `IF NOT EXISTS`, so an index you build beforehand makes it a no-op. Built with `CONCURRENTLY`, the index takes longer but never locks out writes, and the instance keeps running v5.3 while it builds. It does add disk and WAL load, so some writes can slow down while it runs. On a large table the build can take a while, so run it from a session that survives a dropped connection, such as `tmux` or `screen`: > [tab] One-Click / Docker Compose > > From the directory that contains your `docker-compose.yml` (`formbricks` for One-Click installs): > > ```bash theme={null} > docker compose exec -T postgres psql -U postgres -d formbricks <<'SQL' > SET statement_timeout = 0; > SET lock_timeout = 0; > CREATE INDEX CONCURRENTLY IF NOT EXISTS "Response_surveyId_finished_idx" ON "Response"("surveyId", "finished"); > SELECT indisvalid FROM pg_index WHERE indexrelid = to_regclass('"Response_surveyId_finished_idx"'); > SQL > ``` > [tab] Kubernetes > > If you are using the in-cluster PostgreSQL deployed by the Helm chart: > > ```bash theme={null} > kubectl exec -i -n formbricks formbricks-postgresql-0 -- psql -U formbricks -d formbricks <<'SQL' > SET statement_timeout = 0; > SET lock_timeout = 0; > CREATE INDEX CONCURRENTLY IF NOT EXISTS "Response_surveyId_finished_idx" ON "Response"("surveyId", "finished"); > SELECT indisvalid FROM pg_index WHERE indexrelid = to_regclass('"Response_surveyId_finished_idx"'); > SQL > ``` > > > [!NOTE] > > > > If your PostgreSQL pod has a different name, run `kubectl get pods -n formbricks` to find it. With an external or managed PostgreSQL, run the same statements with `psql` as the user that owns the Formbricks tables, connected directly to the primary rather than through a transaction-pooling connection pooler such as PgBouncer. A pooler can run the `SET` and the `CREATE` on different server connections. Any other SQL client must run the `CREATE INDEX` statement on its own, outside a transaction, because `CONCURRENTLY` cannot run inside one. The two `SET` lines keep a timeout configured on the server, the database or your user from cancelling the build: `lock_timeout` also limits how long the build waits for other transactions to finish. On PostgreSQL 17 or later, if `SHOW transaction_timeout;` returns anything other than `0`, add `SET transaction_timeout = 0;` before the `CREATE` line too. Then read the `indisvalid` result: * **`t`**: the index is ready. Upgrade as usual; the migration finds the index and skips the build. * **`f`**: the index exists but is not usable yet. Do not upgrade over it, because the migration would see the name, skip the build, and leave `Response` with an index PostgreSQL never uses. See below. * **No row**: the `CREATE` failed before it started, for example under the wrong user or on a read-only replica. Fix the error it printed and run the commands again. * **No result at all**: `psql` lost its connection, or never got one, before the check ran. Read on under `f`. An `f`, or no result at all, means the build is still running or stopped part-way. If the `CREATE` printed an error, it stopped: fix that cause (often a timeout), drop the index as below, and run the commands again. If your session dropped instead, the build can still be running on the server, so first check, the same way and as the same user as above: ```sql theme={null} SELECT phase, current_locker_pid FROM pg_stat_progress_create_index WHERE datname = current_database() AND relid = '"Response"'::regclass; ``` While that returns a row, wait for it to finish and check `indisvalid` again. A `waiting for writers` phase is waiting for transactions that wrote to `Response`. `waiting for old snapshots` waits for every older transaction in this database that still holds a snapshot, on any table, so a long report or a `pg_dump` backup counts too. Either way, `current_locker_pid` is the session it waits for, which you can look up in `pg_stat_activity`. If the query returns nothing, the build has ended: check `indisvalid` again. `t` means it finished after all, so upgrade as usual. Still `f` means it was interrupted: drop the index the same way, with the same `SET` lines first, since a concurrent drop waits under `lock_timeout` too: ```sql theme={null} SET statement_timeout = 0; SET lock_timeout = 0; DROP INDEX CONCURRENTLY IF EXISTS "Response_surveyId_finished_idx"; ``` Add `SET transaction_timeout = 0;` here too if you needed it for the build. Then run the commands above again. An extra index is harmless to v5.3, so building it early needs no rollback plan of its own. None of the seven constrains a rollback. v5.3 reads none of the new columns and tables, and the two `NOT NULL` columns added to existing tables both carry a database default, so a v5.3 instance keeps writing to those tables exactly as before. Rolling the application images / Helm values back to v5.3 is safe without touching the database. Coming back **forward** has one catch, and only if accounts were created while you were rolled back. `Account.issuer` does not exist in v5.3, so any account signed up or linked on that version is written without one — and both issuer backfills are already recorded as applied, so rolling forward does not re-run them. Better Auth 1.7 keys accounts on `(issuer, accountId)`, which makes those rows invisible to password sign-in and password reset. SSO accounts repair themselves on the next successful sign-in; password accounts have no such path. If anyone signed up during the rollback window, re-run the repair after rolling forward. This is the statement the `repair_account_issuer` migration runs, and it is idempotent — it matches the providers v5.4 ships, so if you have since enabled one that is not listed here, take the current mapping from that migration rather than this copy: ```sql theme={null} UPDATE "Account" SET "issuer" = CASE WHEN "provider" = 'credential' THEN 'local:credential' WHEN "provider" = 'google' THEN 'https://accounts.google.com' ELSE 'local:oauth:' || "provider" END WHERE "issuer" IS DISTINCT FROM ( CASE WHEN "provider" = 'credential' THEN 'local:credential' WHEN "provider" = 'google' THEN 'https://accounts.google.com' ELSE 'local:oauth:' || "provider" END ); ``` ### Bundled Valkey 8.1.9 Upgrade (action required for some self-hosted deployments) The old bundled digest selects only `linux/amd64`. The new digest selects the matching native image on `linux/amd64` and `linux/arm64`, without requiring QEMU or `binfmt`. Valkey 8.1.9 also contains upstream security fixes that are not present in 8.1.1. > [!WARNING] > > Valkey stores sessions, queues, cache entries and rate-limit state in the named `redis` volume with AOF > enabled. Do not run `docker compose down -v`, delete the volume, or use `FLUSHDB` during this upgrade. > Recreating only the container preserves the volume. Expect a brief interruption while Valkey restarts. > [tab] One-Click > > Download the current stable updater so it can migrate the exact old Valkey pin in your existing Compose > file. It creates `formbricks/docker-compose.yml.before-valkey-8.1.9`, validates the updated Compose file, > and restores the backup if validation fails. Custom Valkey images are left unchanged. > > ```bash theme={null} > curl -fsSL https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/formbricks.sh \ > -o formbricks.sh > chmod +x formbricks.sh > ./formbricks.sh update > ``` > [tab] Docker Compose > > Back up your Compose file before changing it: > > ```bash theme={null} > cp docker-compose.yml docker-compose.yml.before-valkey-8.1.9 > ``` > > Then replace the `redis` service's old image with the new multi-architecture index: > > ```yaml theme={null} > image: valkey/valkey@sha256:e0eb7c480958d32bdc4357a74bdd70653ae15f2f9b4c93c4a5a9fad1dc471c84 > ``` > > Validate the file, then pull and recreate only Valkey: > > ```bash theme={null} > docker compose config >/dev/null > docker compose pull redis > docker compose up -d --no-deps --force-recreate redis > docker compose exec redis valkey-cli ping > docker compose exec redis valkey-server --version > redis_image_id=$(docker inspect --format '{{.Image}}' "$(docker compose ps -q redis)") > docker image inspect --format '{{.Architecture}}' "$redis_image_id" > ``` > [tab] Helm > > A normal upgrade with the current chart uses the new default digest. If you explicitly set > `redis.image.digest`, pass a complete older values file, or use `--reuse-values`, override it during the > upgrade: > > ```bash theme={null} > helm upgrade formbricks formbricks/formbricks \ > --reuse-values \ > --set-string redis.image.repository=valkey/valkey \ > --set-string redis.image.digest=sha256:e0eb7c480958d32bdc4357a74bdd70653ae15f2f9b4c93c4a5a9fad1dc471c84 > ``` > > The Valkey StatefulSet rolls while its existing PVC remains attached. Check the rendered image and > `valkey-cli ping` after the rollout. ### Feedback Record Mutations by API Key (action required for some integrations) A feedback dataset can be assigned to more than one workspace, and the records inside it carry no workspace of their own. When a dataset is shared that way, a workspace-scoped permission cannot establish which workspace a given record belongs to. Two rules now follow from that: * **Deleting a feedback record requires `manage`.** A key with `write` is no longer enough. This brings feedback records in line with every other `DELETE` in the API, which has always required `manage`. * **A key cannot update or delete records in a shared dataset.** If a dataset is assigned to two or more workspaces, an API key is refused regardless of its permission level, with a `403` explaining why. | Operation | Before | After | | - | - | - | | `GET`, search, similar, count | `read` | unchanged | | `POST /api/v3/feedbackRecords` (create) | `write` | unchanged | | `PATCH /api/v3/feedbackRecords/{id}` | `write` | `write`, **and** the dataset assigned to one workspace | | `DELETE /api/v3/feedbackRecords/{id}` | `write` | `manage`, **and** the dataset assigned to one workspace | | `DELETE /api/v3/feedbackRecords?tenant_id=…` | `write` | `manage`, **and** the dataset assigned to one workspace | The same applies to the MCP tools `update_feedback_record` and `delete_feedback_record` when the client authenticates with an API key. The required MCP **scope** is unchanged — both remain `feedbackRecords:write`. > [!NOTE] > > **Only API keys are affected.** Users signing in through the UI, OAuth/MCP connections, and SAML/OIDC > sessions authorize through their organization role instead, which is unchanged: organization owners and > managers can still update and delete feedback records, including in a shared dataset. Reading, searching > and creating records are unaffected for every principal. To find out whether any dataset on your instance is shared, and would therefore start refusing API-key mutations: ```sql theme={null} SELECT d.id, d.name, d."organizationId", COUNT(w."workspaceId") AS workspaces FROM "FeedbackDirectory" d JOIN "FeedbackDirectoryWorkspace" w ON w."feedbackDirectoryId" = d.id WHERE d."isArchived" = false GROUP BY d.id, d.name, d."organizationId" HAVING COUNT(w."workspaceId") > 1; ``` Most instances return no rows: a workspace is normally assigned a single dataset, so sharing only exists where an administrator deliberately assigned a second workspace. For any row that does come back, an integration that mutates records in that dataset has two ways forward — assign the dataset to a single workspace under **Settings → Organization → Datasets**, or have the integration authenticate as an organization owner or manager instead of with a workspace-scoped key. #### What to do before upgrading 1. Run the query above. If it returns rows, decide how each affected integration should proceed. 2. Raise any API key that deletes feedback records from `write` to `manage`. 3. After deploying, smoke test your feedback-record integrations. Two log lines identify an integration caught by the new rules — grep for `Feedback record mutation denied` (the MCP path, which names the reason) and for `Feedback records gateway authorization denied` (the REST path, which logs `verdict: "deny"` alongside the `operation` and `feedbackDirectoryId`). #### Rollback This access-rule change itself ships no migration and touches no schema (the release's migrations are listed [above](#database-migrations)), so rolling the application images / Helm values back to v5.3 undoes it with nothing to restore. An API key raised to `manage` in step 2 keeps working on v5.3 — `manage` was always accepted wherever `write` was — so that step does not need reverting either. ### Better Auth 1.7 upgrade (no action required for most instances) v5.4 upgrades the Better Auth authentication core from the 1.6 line to 1.7, which fixes [GHSA-p2fr-6hmx-4528](https://github.com/advisories/GHSA-p2fr-6hmx-4528): MCP OAuth access-token audiences are now bound to the resource a user actually approved during authorization, instead of trusting whatever the client requested. This is a coupled core upgrade — it touches login, sessions, 2FA, SSO and MCP OAuth — but for self-hosted instances it needs no manual database step. Every schema change is additive and nullable, and the required backfills (account identity, existing OAuth clients, refresh tokens, consents) run automatically during the upgrade — they are the two `eng_2343` entries in the [Database migrations](#database-migrations) table above. The migration also adds two nullable columns, `alg` and `crv`, to the `jwks` table that holds your instance's JWT signing keys. Keys created before the upgrade keep working untouched — Better Auth reads a null `alg` as the default algorithm — so there is nothing to backfill, but the columns must exist before the new version mints its next key. #### AZUREAD\_TENANT\_ID: set a concrete tenant for full id\_token verification Better Auth 1.7 verifies Microsoft id\_tokens against the issuer advertised by the tenant's OpenID discovery document whenever `AZUREAD_TENANT_ID` names a concrete tenant — a Directory (tenant) ID GUID or a verified domain. That is strictly stronger than v5.3 and needs no action. Two of Microsoft's multi-tenant authorities are different. `common` and `organizations` advertise the literal placeholder `https://login.microsoftonline.com/{tenantid}/v2.0` as their issuer, so verifying real tokens against it fails every Microsoft sign-in with `?error=unable_to_get_user_info`. Formbricks therefore handles those two the way it already handles an unset `AZUREAD_TENANT_ID`: sign-in identity comes from Microsoft's userinfo endpoint over a client-authenticated call (the v5.3 behavior) and id\_tokens are not verified. The authority you configure still applies at sign-in, so `organizations` keeps restricting sign-in to work/school accounts, and an unset value behaves as `common`. Formbricks logs a warning at startup when either is set and Microsoft SSO is enabled. To get full id\_token verification, set your Directory (tenant) ID instead. `consumers` needs no action and is not affected: every personal Microsoft account lives in one well-known tenant, so that authority advertises a real issuer and keeps full id\_token verification. #### SSO callback URLs are unchanged Your SSO callback URLs stay exactly as they are: | Provider | Callback URL | Action required? | | - | - | - | | Azure AD / Entra ID | `https://your-domain.com/api/auth/oauth2/callback/azuread` | No | | Generic OIDC / Keycloak | `https://your-domain.com/api/auth/oauth2/callback/openid` | No | | SAML (BoxyHQ / Jackson) | `https://your-domain.com/api/auth/oauth2/callback/saml` | No | | Google / GitHub | `https://your-domain.com/api/auth/callback/{provider}` | No | Better Auth 1.7 rebuilds its generic-OAuth support on top of the built-in social-provider route, which would otherwise have moved these three callbacks to `/api/auth/callback/{providerId}` and required you to register a new redirect URI at your identity provider. OAuth requires redirect URIs to match exactly, so a path change means editing every provider configuration by hand. Formbricks pins the callback URL instead, so it no longer follows the authentication library's internal routing. The URLs above are the ones introduced in v5.2 and they are now a stable part of the Formbricks API — a future authentication-core upgrade will not move them either. > [!NOTE] > > The table writes `your-domain.com` as your `WEBAPP_URL`, which is correct for a default install. The > callback is derived from the same auth base URL Better Auth itself uses, not from `WEBAPP_URL`: that is > `BETTER_AUTH_URL`, or `NEXTAUTH_URL` when only the legacy name is set, falling back to `WEBAPP_URL` when > neither is. So if either auth URL names a different origin, the callback lives on **that** origin — register > that URI at your identity provider. Either way it is unchanged by this upgrade. > [!NOTE] > > Nothing to do, and nothing to undo. If you added a `/api/auth/callback/{providerId}` redirect URI in > advance based on an earlier draft of these notes, leaving it registered is harmless — most identity > providers accept several redirect URIs, and Formbricks simply will not use it. #### MCP access tokens now end with their session An MCP access token used to stay valid until its own expiry, independently of the session that authorized it. In 1.7 it is bound to that session: once the session ends — the user signs out, or the session is revoked — the token is inactive. `/introspect` reports `active: false` for it and `/api/auth/oauth2/userinfo` rejects it, rather than honouring it until its TTL runs out. This is upstream hardening, and it is the stricter of the two behaviours: a token that outlives the sign-out which created it is exactly what a revocation is supposed to stop. It applies to **access** tokens. A refresh token granted `offline_access` deliberately survives the session ending, per OIDC Back-Channel Logout 1.0 §2.7, so that long-lived API access can outlive a browser session — which is what MCP clients rely on. Signing out is therefore not a way to cut a client off permanently. **No action is required.** MCP clients re-authorize on their own — Claude Code and MCP Inspector both do — so a user who signs out and back in sees nothing. It is listed here for one case only: a custom integration that caches a Formbricks MCP access token and reuses it across sessions will start receiving rejections where it previously succeeded, and should obtain a fresh token instead of treating the cached one as valid until its expiry. #### Rollback (Better Auth 1.7) The `Account.issuer` column and the new `oauthResource`, `oauthClientResource` and `oauthClientAssertion` tables are additive and nullable, and are not read by v5.3, so rolling the application images / Helm values back to v5.3 is safe without touching the database. SSO needs no attention in either direction: v5.3 and v5.4 use the same callback URLs. If accounts are created while you are rolled back, see the [rollback note above](#database-migrations) before rolling forward — `Account.issuer` is the one value a v5.3 instance cannot write. ## v5.3 Formbricks v5.3 is a **drop-in upgrade for most self-hosted instances**. There are no breaking API, webhook, or authentication changes, and every database migration is additive and runs automatically on startup. The only self-hosting-relevant changes are a few new optional variables. The main thing worth setting before you deploy is `TRUSTED_PROXY_HOP_COUNT` for your proxy setup; everything else is optional. > [!NOTE] > > All new environment variables are optional and defaulted — none of them block startup. You can upgrade > to v5.3 without changing any environment variables and everything will run. ### Client IP Resolution Behind a Proxy (recommended) v5.3 resolves the client IP from the `X-Forwarded-For` chain using a configurable number of trusted proxy hops: * `TRUSTED_PROXY_HOP_COUNT` — optional, **defaults to `1`**. Set it to the number of trusted proxies / load balancers in front of Formbricks (e.g. an ingress plus a CDN = `2`). An explicit `0` trusts no proxy at all: the runtime exposes no socket peer address, so the client IP then resolves to a fixed "untrusted" placeholder that rate limiting and response audit logging record in place of a real address. A forwarding chain shorter than the configured count, or a malformed selected hop, also fails closed. Ports appended by gateways such as [Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/how-application-gateway-works#modifications-to-the-request) are removed, and IPv6 addresses are normalized to their `/64` network. Leave the setting at `1` (or your real hop count) unless you deliberately want to stop capturing client IPs. > [!WARNING] > > Setting `TRUSTED_PROXY_HOP_COUNT` **higher** than your real hop count lets a client spoof its IP by > sending a forged `X-Forwarded-For` header. Set it to the exact number of proxies in front of the app — > no higher. The default of `1` is correct for a single reverse proxy / ingress. ### Renamed Configuration * **Scheduling variables renamed.** `NEXT_PUBLIC_SURVEY_SCHEDULING_*` → `SURVEY_SCHEDULING_*` (the `NEXT_PUBLIC_` prefix was dropped). This only affects you if you ran a v5.3 release candidate that used the old names; a clean v5.2 → v5.3 upgrade never set them. ### Optional New Configuration None of the following is required to run v5.3. Add them only if you want the associated feature. #### Survey Scheduling The new survey-scheduling feature runs on a fixed daily local time. All three are optional and defaulted: * `SURVEY_SCHEDULING_TIME_ZONE` — a valid IANA time zone. Default `Europe/Berlin`. * `SURVEY_SCHEDULING_LOCAL_HOUR` — default `0`. * `SURVEY_SCHEDULING_LOCAL_MINUTE` — default `0`. #### Password Breach Check * `PASSWORD_HIBP_CHECK_DISABLED` — set to `"1"` to disable the "Have I Been Pwned" breached-password check on sign-up and password reset (`"0"` or unset keeps it on). ### Analytics (Cube) Two Cube-related deltas in v5.3. Neither changes the Cube schema, so there is **no schema refresh to run**: * **`CUBEJS_EXTERNAL_DEFAULT` now defaults to `false`** (in both `docker/docker-compose.yml` and the Helm chart). Cube Store is used only when you explicitly opt into external pre-aggregations — a safe default for most self-hosters. Set it back to `true` only if you run external pre-aggregations. * **The Hub image moves to `0.8.1`.** The Helm chart pins `0.8.1`. Docker Compose instead resolves the Hub image through `${HUB_IMAGE_REF:-:latest}`, so a plain `docker compose pull` fetches whatever `:latest` currently is — set `HUB_IMAGE_REF=:0.8.1` in `docker/.env` before pulling for a deterministic upgrade. ### Upgrade Steps 1. Back up your database. 2. Set `TRUSTED_PROXY_HOP_COUNT` to the number of proxies in front of your instance (default `1`). 3. Update your deployment assets to v5.3 **before** pulling images — `docker compose pull` reads your local Compose file, so fetch the v5.3 `docker-compose.yml` first (Helm users use the v5.3 chart). For a deterministic Hub image on Compose, set `HUB_IMAGE_REF=:0.8.1` in `docker/.env`. 4. Pull and restart (`docker compose pull && docker compose down && docker compose up -d`, or `helm upgrade` with the new chart / tag). Migrations apply automatically on startup. 5. Smoke test: sign in (including 2FA), create and schedule a survey, and open the Feedback Records dashboards / charts to confirm analytics render correctly. ### Rollback The v5.3 migrations are additive and are not read by v5.2, so rolling back the application images / Helm values to v5.2 is safe without touching the database. Restore a database backup only if you specifically need to undo the schema additions — and note that doing so discards any data written after the backup was taken, so perform it within a maintenance window. ## v5.2 Formbricks v5.2 migrates authentication from NextAuth to **Better Auth**. For most self-hosted instances this is a drop-in upgrade, but **if you use SSO (Azure AD / Entra ID, generic OIDC, or SAML) you must re-register the OAuth callback URL at your identity provider before the first v5.2 restart**, or SSO sign-in will fail with a redirect-URI mismatch. > [!WARNING] > > All users are signed out once when you upgrade to v5.2. Better Auth takes over session handling and > there is no dual-read from the old NextAuth sessions, so the cutover is a one-time forced re-login. > Passwords are preserved — existing credential hashes are migrated automatically, so no password reset > is needed. ### SSO Callback URL Change (action required for SSO users) Better Auth serves the OAuth2/OIDC callback at a new path: * old (NextAuth): `/api/auth/callback/{provider}` * new (Better Auth): `/api/auth/oauth2/callback/{providerId}` Update the redirect / callback URIs at your identity provider to the new path. Replace `https://your-domain.com` with your instance URL: | Provider | Where to update | New callback URL | | - | - | - | | Azure AD / Entra ID | Azure portal -> App registration -> Authentication -> Redirect URIs | `https://your-domain.com/api/auth/oauth2/callback/azuread` | | Generic OIDC | At your OIDC provider | `https://your-domain.com/api/auth/oauth2/callback/openid` | | SAML (BoxyHQ / Jackson) | The Jackson connection's `redirect_uri` | `https://your-domain.com/api/auth/oauth2/callback/saml` | > [!NOTE] > > **Google and GitHub sign-in do not change.** They use Better Auth's built-in social providers, whose > callback path (`/api/auth/callback/{provider}`) is unchanged — nothing to do there. > > For SAML, only the Jackson connection's `redirect_uri` changes. The IdP-side ACS endpoint > (`/api/auth/saml/callback`) is unchanged, so you do **not** need to reconfigure your IdP's SAML app. > > Leave the old `/api/auth/callback/*` redirect URIs registered through the transition. Keeping them in > place is harmless and makes a rollback to v5.1 clean. ### Authentication Environment Variables Better Auth introduces two optional variables. **Neither is required** for a standard upgrade — both fall back to your existing NextAuth configuration: * `BETTER_AUTH_SECRET` — cookie/session signing secret. Falls back to `NEXTAUTH_SECRET` when unset. On these releases it must be at least 32 characters when set explicitly. Use the value `NEXTAUTH_SECRET` already holds: a *different* one invalidates every session and every outstanding invite and verification link. * `BETTER_AUTH_URL` — the auth base URL. Falls back to `NEXTAUTH_URL` (and then `WEBAPP_URL`) when unset. > [!NOTE] > > If your instance already sets `NEXTAUTH_SECRET` and `NEXTAUTH_URL` (all v5.1 instances do), you can > upgrade without adding any new auth variables. **Removed:** `DISABLE_ACCOUNT_DELETION_SSO_CONFIRMATION` no longer exists. Remove it from your environment if you set it; it now has no effect. ### Optional New Configuration None of the following is required to run v5.2. Add them only if you want the associated feature. #### Hub Enrichment (sentiment, emotion, translation) Hub `>= 0.8.0` can classify sentiment and emotion and translate feedback. These are **off** unless you set a provider and model, and they run in both the Hub API and the hub-worker, so set the variables on **both** services. Bump your Hub image to `>= 0.8.0` (via `HUB_IMAGE_REF`) to pick up these features. * `SENTIMENT_PROVIDER`, `SENTIMENT_MODEL`, `SENTIMENT_PROVIDER_API_KEY` * `EMOTIONS_PROVIDER`, `EMOTIONS_MODEL`, `EMOTIONS_PROVIDER_API_KEY` * `TRANSLATION_PROVIDER`, `TRANSLATION_MODEL`, `TRANSLATION_PROVIDER_API_KEY`, `TRANSLATION_DEFAULT_LANGUAGE` Supported providers: `openai`, `google` (AI Studio, needs `*_PROVIDER_API_KEY`), and `google-gemini` (Vertex, needs `*_GOOGLE_CLOUD_PROJECT` / `*_LOCATION` plus Application Default Credentials). > [!WARNING] > > A provider set **without** its required credentials crash-loops both Hub containers on startup — it does > not degrade gracefully. Set the credentials, or leave the provider unset. #### AI Taxonomy (beta) An optional standalone taxonomy service, enabled in Docker Compose with `COMPOSE_PROFILES=taxonomy`. It shares an internal token with Hub: * `TAXONOMY_SERVICE_URL` (the internal URL to the taxonomy service) * `HUB_INTERNAL_API_TOKEN`, `TAXONOMY_SERVICE_TOKEN` (strong random secrets) * `TAXONOMY_LLM_PROVIDER` / `TAXONOMY_LLM_MODEL` / `TAXONOMY_LLM_BASE_URL` / `TAXONOMY_LLM_API_KEY` (`openai-compatible` by default; `bedrock` and `vertex-gemini` also supported) * `TAXONOMY_IMAGE_REF` to pin a released image (e.g. `:v0.1.0`) Use `COMPOSE_PROFILES=qwen,taxonomy` to back it with the bundled Qwen/vLLM service. #### Bundled Qwen / vLLM Runtime Docker Compose can now run a bundled OpenAI-compatible LLM for self-hosted AI features with `COMPOSE_PROFILES=qwen`. Tunable via `QWEN_VLLM_IMAGE`, `QWEN_MODEL_ID`, `QWEN_SERVED_MODEL_NAME`, `QWEN_MAX_MODEL_LEN`, `QWEN_MAX_NUM_SEQS`, `QWEN_GPU_MEMORY_UTILIZATION`, `QWEN_VLLM_HOST`, and `QWEN_VLLM_PORT`. #### OpenTelemetry Log Export * `OTEL_LOGS_ENABLED=1` — export Pino application logs via OTLP (off by default; also needs `OTEL_EXPORTER_OTLP_ENDPOINT`). ### Upgrade Steps v5.2 requires no manual database migration step beyond the standard automatic Prisma migrations on startup (the credential-account backfill runs automatically). The Helm chart is unchanged from v5.1. 1. **If you use SSO**, add the new `/api/auth/oauth2/callback/{providerId}` redirect URIs at your IdP (see the table above), keeping the old ones in place. 2. Back up your database. 3. Pull the v5.2 images and restart (`docker compose pull && docker compose down && docker compose up -d`, or `helm upgrade` with the new tag). 4. After startup, sign in again (the one-time forced re-login) and verify each configured SSO provider completes sign-in. ### Rollback Because the old `/api/auth/callback/*` redirect URIs are left in place, rolling back to v5.1 is clean: revert your image tags / Helm values, and the previous NextAuth callback path works again. Restore the database backup only if you need to undo schema changes. ## v5 Formbricks v5 changes the self-hosted runtime contract. If you are upgrading an existing Formbricks 4.x deployment, review this section before starting the new version. ### What Changes In v5 * **Formbricks Hub is now mandatory** for self-hosted Formbricks v5 deployments. * **Cube is now part of the baseline stack** alongside Hub. Docker, one-click, and Helm all bundle Cube by default; `CUBEJS_API_SECRET` is required. Operators can disable the bundled Cube deployment in Helm to use an external cluster instead. * **Edge rate limiting is now required** for specific public and API-key routes. Those routes are no longer throttled inside the application server. * **AI features are configured at the instance level** via `AI_*` environment variables. > [!WARNING] > > Formbricks v5 removes application-level rate limiting for several routes that are now expected to be > protected by Envoy Gateway or an equivalent edge rate limiter. If your self-hosted instance does not > already have equivalent edge protection, add it before exposing the v5 stack. ### Before You Upgrade Before you restart your instance on Formbricks v5: * back up your database * identify your current deployment type: one-click, manual Docker Compose, or Kubernetes/Helm * confirm Redis/Valkey and your file storage setup are already healthy from your v4 baseline * identify whether file uploads use external S3-compatible storage or a legacy bundled MinIO service * budget approximately \~500 MB additional RAM headroom for the bundled Cube container (dashboards and analysis are part of the baseline now) * decide whether this instance needs optional AI features * verify whether you already run Envoy Gateway or another equivalent edge rate limiter for the covered routes ### Required Config And Infrastructure Changes #### Formbricks Hub Formbricks v5 expects Hub to be part of the self-hosted stack. * `HUB_API_KEY` is required * `HUB_API_URL` must point to the Hub service the Formbricks app can reach * `HUB_DATABASE_URL` is optional; when unset, Hub can share the same PostgreSQL database as Formbricks * bundled Docker and Helm assets run Hub database migrations automatically during startup or upgrade, and the migration steps are idempotent > [!NOTE] > > Hub-specific source code and standalone deployment assets live in the > [Formbricks Hub repository](https://github.com/formbricks/hub). For a normal Formbricks v5 upgrade, use that > repository as reference material only; the canonical migration steps stay in these Formbricks docs. #### Edge Rate Limiting Formbricks v5 splits rate limiting across two layers: * Envoy Gateway, or an equivalent edge rate limiter, for covered public and API-key routes * the application server for the remaining session-authenticated routes, server actions, and uncovered APIs Keep Redis/Valkey enabled for the remaining application-enforced limits. For the covered route groups and exact thresholds, use the [rate-limiting guide](/docs/self-hosting/configuration/rate-limiting) as the source of truth. #### AI Features AI features are optional and only need instance-level configuration if you want to enable the related enterprise functionality. * `AI_PROVIDER` and `AI_MODEL` are the base settings * `AI_PROVIDER=aws` requires `AI_AWS_REGION`, `AI_AWS_ACCESS_KEY_ID`, and `AI_AWS_SECRET_ACCESS_KEY` * `AI_PROVIDER=google` requires `AI_GOOGLE_CLOUD_PROJECT` and `AI_GOOGLE_CLOUD_LOCATION`; credentials are optional overrides when Application Default Credentials are unavailable * `AI_PROVIDER=azure` requires `AI_AZURE_API_KEY` and either `AI_AZURE_BASE_URL` or `AI_AZURE_RESOURCE_NAME` * `AI_PROVIDER=openai-compatible` requires `AI_OPENAI_COMPATIBLE_BASE_URL`; the LLM GA v1 self-hosted path is Qwen served by vLLM * Helm operators can set `llm.enabled: true` to deploy the bundled Qwen/vLLM runtime * Docker Compose operators can set `COMPOSE_PROFILES=qwen` to deploy the bundled Qwen/vLLM runtime * Keep the bundled runtime disabled when you configure Google Vertex, Azure, AWS Bedrock, or an external OpenAI-compatible endpoint manually #### Cube Cube is part of the baseline Formbricks v5 stack. * the Docker, one-click, and Helm deployments all bundle the `cube` service by default * the Formbricks app requires `CUBEJS_API_URL` and `CUBEJS_API_SECRET`; the install/dev-setup scripts generate the secret automatically for new installs * Helm operators who want to run an external Cube cluster can set `cube.enabled: false` and provide their own endpoint via `deployment.env.CUBEJS_API_URL` * if you run Cube yourself, you may also need to override `CUBEJS_DB_*` values for the Cube service ### Upgrade Steps By Deployment Type **1. Back up your database** > [tab] One-Click > > From the `formbricks` directory created by the installer: > > ```bash theme={null} > cd formbricks > docker compose exec postgres pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v5_$(date +%Y%m%d_%H%M%S).dump > ``` > > > [!NOTE] > > > > If your PostgreSQL service name differs, run `docker compose ps` first and adjust the command. > [tab] Docker Compose > > From the directory that contains your `docker-compose.yml`: > > ```bash theme={null} > docker compose exec postgres pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v5_$(date +%Y%m%d_%H%M%S).dump > ``` > > > [!NOTE] > > > > If your service is not named `postgres`, use `docker compose ps` to find the correct > > name. > [tab] Kubernetes > > If you are using the in-cluster PostgreSQL released by the Helm chart: > > ```bash theme={null} > kubectl exec -n formbricks formbricks-postgresql-0 -- pg_dump -Fc -U formbricks -d formbricks > formbricks_pre_v5_$(date +%Y%m%d_%H%M%S).dump > ``` > > If you use a managed PostgreSQL service, create a provider snapshot or run `pg_dump` directly against the > external host before continuing. **2. Update your deployment config and restart on v5** > [tab] One-Click > > The one-click `./formbricks.sh update` command only pulls new images. It does **not** rewrite your existing > `formbricks/docker-compose.yml`, so you must merge the v5 stack changes before the first v5 restart. > > ```bash theme={null} > curl -fsSL -o formbricks/docker-compose.v5.yml https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/docker-compose.yml > ``` > > Then compare `formbricks/docker-compose.v5.yml` with your existing `formbricks/docker-compose.yml` and merge > the v5 additions: > > * set `POSTGRES_PASSWORD` in `formbricks/.env` to the exact password used by the existing PostgreSQL > volume; do not generate a new value during the upgrade. If it contains URI-reserved characters, also set > `POSTGRES_PASSWORD_URL_ENCODED` to its percent-encoded form > * add a non-empty `HUB_API_KEY` and reuse the same value wherever your deployment resolves Hub auth > * keep `HUB_API_URL` at `http://hub:8080` unless Hub runs elsewhere > * include the bundled `formbricks-migrate`, `hub-migrate`, `hub`, and `hub-worker` services > * sync `formbricks/cube/cube.js` and `formbricks/cube/schema/FeedbackRecords.js` from the current > release and ensure `formbricks/.env` contains `CUBEJS_API_SECRET` (Cube is part of the baseline stack > in v5) > * if your older setup still uses bundled MinIO for uploads, review that storage path separately before the > first v5 restart; newer self-hosting updates move the bundled object-storage path to RustFS, while > external S3-compatible storage keeps the same `S3_*` app contract > * add any `AI_*` variables you need > * if you prefer to run an external Cube instance, point `CUBEJS_API_URL` at it and provide the matching > `CUBEJS_API_SECRET`; otherwise the bundled `cube` service runs against the local Postgres > > After the compose file is updated and your edge rate limiter is in place: > > ```bash theme={null} > ./formbricks.sh update > ``` > [tab] Docker Compose > > Pull the current production compose file and merge the v5 changes into your existing deployment config before > only updating images: > > ```bash theme={null} > curl -fsSL -o docker-compose.v5.yml https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/docker-compose.yml > ``` > > At minimum, confirm: > > * `POSTGRES_PASSWORD` contains the exact password used by the existing PostgreSQL volume; replacing the > Compose file does not rotate the database password. If it contains URI-reserved characters, also set > `POSTGRES_PASSWORD_URL_ENCODED` to its percent-encoded form > * `HUB_API_KEY` is configured and the same value is available wherever your deployment resolves Hub auth > * `HUB_API_URL` points to the Hub service the app can reach > * the compose stack includes `formbricks-migrate`, `hub-migrate`, `hub`, and `hub-worker` > * the v5 stack also includes `cube`, `cube/cube.js`, and `cube/schema/FeedbackRecords.js`, with > `CUBEJS_API_SECRET` available through your `.env` or shell environment > * if your legacy Compose file still includes bundled MinIO for uploads, treat that as a separate storage > review when comparing files; newer bundled storage guidance uses RustFS, while external S3-compatible > storage keeps the same `S3_*` app contract > * any `AI_*` variables you need are set > * if you prefer to run an external Cube instance, point `CUBEJS_API_URL` at it and supply the matching > `CUBEJS_API_SECRET`; otherwise the bundled `cube` service runs against the local Postgres > > Then restart the stack: > > ```bash theme={null} > docker compose pull > docker compose down > docker compose up -d > ``` > > > [!NOTE] > > > > The v5 Docker Compose stack bundles Hub and Cube. Keep the bundled `cube/` config files in sync with > > `docker-compose.yml` when you update this path. > [tab] Kubernetes > > Upgrade using the current Formbricks chart: > > ```bash theme={null} > helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \ > -n formbricks \ > -f values.yaml > ``` > > Before running the upgrade, confirm these v5 expectations in your values: > > * keep `hub.enabled=true`; Hub is mandatory in v5 > * if you want the bundled Envoy path, configure `envoy.enabled=true` and then choose: > * `envoy.controller.enabled=true` for the bundled controller mode > * `envoy.controller.enabled=false` when the cluster already has a compatible Envoy Gateway controller > * if you use bundled Envoy rate limiting, enable a dedicated backend with `envoyRedis.enabled=true` > * if you already have an equivalent edge rate limiter outside the chart, keep that protection in place > * `CUBEJS_API_SECRET` is provided (Cube is bundled by default at `cube.enabled: true`; set to `false` > and point `CUBEJS_API_URL` at your own endpoint if you prefer an external Cube cluster) ### Post-Upgrade Verification After the upgrade: * confirm the Formbricks app starts and `GET /health` returns successfully * confirm the Hub service is healthy and reachable from the Formbricks app * verify any Hub-backed connector or feedback flows you use * verify covered routes are rate-limited at the edge layer * verify AI features only if you configured the required `AI_*` variables * verify dashboards and analysis flows against the bundled (or external) Cube endpoint ### Troubleshooting And Rollback Common upgrade issues: * **Missing `HUB_API_KEY`**: Formbricks cannot authenticate to Hub, and Hub itself may fail to start * **Bad `HUB_API_URL`**: the app starts, but Hub-backed features fail because the service cannot be reached * **No edge rate limiter in front of covered routes**: the v5 deployment runs, but those routes are no longer protected by the legacy in-app limiter * **Missing AI provider configuration**: AI features remain unavailable until `AI_PROVIDER`, `AI_MODEL`, and the matching provider settings are set correctly * **Missing `CUBEJS_API_SECRET`** (or unreachable Cube endpoint): the Formbricks app fails env validation at boot, or — if env vars are present but Cube is unreachable — dashboards and analysis queries fail while the rest of the app stays healthy * **Cube healthcheck fails with `wget: not found`**: older v5 Docker Compose files used `wget` for the bundled Cube healthcheck, but the bundled Cube image does not include it. Sync the whole `cube` service from the current Docker Compose file so the healthcheck checks `/readyz` with Node instead (see [Bundled Cube image](#bundled-cube-image-action-required-for-some-deployments)). If you need to roll back: * restore the pre-upgrade database backup if schema or data changes require it * revert your image tags or Helm release values to the last known-good Formbricks 4.x version * revert compose or Helm configuration changes introduced for the v5 rollout **Workspaces and Environment IDs** Environment IDs were deprecated to simplify SDK setup around a single Workspace ID while keeping existing integrations backward compatible during migration. **Website & App Surveys SDK: Migrate to Workspace ID** > [!NOTE] > > Formbricks v5 also includes the Environment ID to Workspace ID transition for SDK setup. If you still rely on a > legacy Environment ID, read the [Migrate to Workspace ID guide](/docs/surveys/website-app-surveys/workspace-id-migration). ## v4.7 Formbricks v4.7 introduces **typed contact attributes** with native `number` and `date` data types. This enables comparison-based segment filters (e.g. "signup date before 2025-01-01") that were previously not possible with string-only attribute values. ### What Happens Automatically When Formbricks v4.7 starts for the first time, the data migration will: 1. Analyze all existing contact attribute keys and infer their data types (`text`, `number`, or `date`) based on the stored values 2. Update the `ContactAttributeKey` table with the detected `dataType` for each key 3. **If your instance has fewer than 1,000,000 contact attribute rows**: backfill the new `valueNumber` and `valueDate` columns inline. No manual action is needed. 4. **If your instance has 1,000,000 or more contact attribute rows**: the value backfill is skipped to avoid hitting the migration timeout. You will need to run a standalone backfill script after the upgrade. > [!NOTE] > > Most self-hosted instances have far fewer than 1,000,000 contact attribute rows (a typical setup with 100K > contacts and 5-10 attributes each lands around 500K-1M rows). If you are below the threshold, the migration > handles everything automatically and you can skip the manual backfill step below. ### Steps to Migrate **1. Backup your Database** > [tab] Docker > > Before running these steps, navigate to the `formbricks` directory where your `docker-compose.yml` file is located. > > ```bash theme={null} > docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v4.7_$(date +%Y%m%d_%H%M%S).dump > ``` > > > [!NOTE] > > > > If you run into "**No such container**", use `docker ps` to find your container name, e.g. > > `formbricks_postgres_1`. > [tab] Kubernetes > > If you are using the **in-cluster PostgreSQL** deployed by the Helm chart: > > ```bash theme={null} > kubectl exec -n formbricks formbricks-postgresql-0 -- pg_dump -Fc -U formbricks -d formbricks > formbricks_pre_v4.7_$(date +%Y%m%d_%H%M%S).dump > ``` > > > [!NOTE] > > > > If your PostgreSQL pod has a different name, run `kubectl get pods -n formbricks` to find it. > > If you are using a **managed PostgreSQL** service (e.g. AWS RDS, Cloud SQL), use your provider's backup/snapshot feature or run `pg_dump` directly against the external host. **2. Upgrade to Formbricks v4.7** > [tab] Docker > > ```bash theme={null} > # Pull the latest version > docker compose pull > > # Stop the current instance > docker compose down > > # Start with Formbricks v4.7 > docker compose up -d > ``` > [tab] Kubernetes > > ```bash theme={null} > helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \ > -n formbricks \ > --set deployment.image.tag=v4.7.0 > ``` > > > [!NOTE] > > > > The Helm chart includes a migration Job that automatically runs Prisma schema migrations as a > > PreSync hook before the new pods start. No manual migration step is needed. **3. Check the Migration Logs** After Formbricks starts, check the logs to see whether the value backfill was completed or skipped: > [tab] Docker > > ```bash theme={null} > docker compose logs formbricks | grep -i "backfill" > ``` > [tab] Kubernetes > > ```bash theme={null} > # Check the application pod logs > kubectl logs -n formbricks -l app.kubernetes.io/name=formbricks --tail=200 | grep -i "backfill" > ``` > > If the Helm migration Job ran, you can also inspect its logs: > > ```bash theme={null} > kubectl logs -n formbricks job/formbricks-migration > ``` If you see a message like `Skipping value backfill (X rows >= 1000000 threshold)`, proceed to step 4. Otherwise, the migration is complete and no further action is needed. **4. Run the Backfill Script (large datasets only)** If the migration skipped the value backfill, run the standalone backfill script inside the running Formbricks container: > [tab] Docker > > ```bash theme={null} > docker exec formbricks node packages/database/dist/scripts/backfill-attribute-values.js > ``` > > > [!NOTE] > > > > Replace `formbricks` with your actual container name if it differs. Use `docker ps` to find it. > [tab] Kubernetes > > ```bash theme={null} > kubectl exec -n formbricks deploy/formbricks -- node packages/database/dist/scripts/backfill-attribute-values.js > ``` > > > [!NOTE] > > > > If your Formbricks deployment has a different name, run `kubectl get deploy -n formbricks` to find it. The script will output progress as it runs: ``` ======================================== Attribute Value Backfill Script ======================================== Fetching number-type attribute keys... Found 12 number-type keys. Backfilling valueNumber... Number backfill progress: 10/12 keys (48230 rows updated) Number backfill progress: 12/12 keys (52104 rows updated) Fetching date-type attribute keys... Found 5 date-type keys. Backfilling valueDate... Date backfill progress: 5/5 keys (31200 rows updated) ======================================== Backfill Complete! ======================================== valueNumber rows updated: 52104 valueDate rows updated: 31200 Duration: 42.3s ======================================== ``` Key characteristics of the backfill script: * **Safe to run while Formbricks is live** -- it does not lock the entire table or wrap work in a long transaction * **Idempotent** -- it only updates rows where the typed columns are still `NULL`, so you can safely run it multiple times * **Resumable** -- each batch commits independently, so if the process is interrupted you can re-run it and it picks up where it left off * **No timeout risk** -- unlike the migration, this script runs outside the migration transaction and has no time limit **5. Verify the Upgrade** * Access your Formbricks instance at the same URL as before * If you use contact segments with number or date filters, verify they return the expected results * Check that existing surveys and response data are intact *** ## v4.0 > [!WARNING] > > **Important: Migration Required** > > Formbricks 4 introduces additional requirements for self-hosting setups and makes a dedicated Redis cache as well as S3-compatible file storage mandatory. Formbricks 4.0 is a **major milestone** that sets up the technical foundation for future iterations and feature improvements. This release focuses on modernizing core infrastructure components to improve reliability, scalability, and enable advanced features going forward. ### What's New in Formbricks 4.0 **🚀 New Enterprise Features:** * **Quotas Management**: Advanced quota controls for enterprise users **🏗️ Technical Foundation Improvements:** * **Enhanced File Storage**: Improved file handling with better performance and reliability * **Improved Caching**: New caching functionality improving speed, extensibility and reliability * **Database Optimization**: Removal of unused database tables and fields for better performance * **Future-Ready Architecture**: Standardized infrastructure components for upcoming features ### What This Means for Your Self-Hosting Setup These improvements in Formbricks 4.0 also make some infrastructure requirements mandatory going forward: * **Redis** for caching * **RustFS or S3-compatible storage** for file uploads These services are already included in the updated one-click setup for self-hosters, but existing users need to upgrade their setup. More information on this below. ### Why We Made These Changes We know this represents more moving parts in your infrastructure and might even introduce more complexity in hosting Formbricks, and we don't take this decision lightly. As Formbricks grows into a comprehensive Survey and Experience Management platform, we've reached a point where the simple, single-service approach was holding back our ability to deliver the reliable, feature-rich product our users demand and deserve. By moving to dedicated, professional-grade services for these critical functions, we're building the foundation needed to deliver: * **Enterprise-grade reliability** with proper redundancy and backup capabilities * **Advanced features** that require sophisticated caching and file processing * **Better performance** through optimized, dedicated services * **Future scalability** to support larger deployments and more complex use cases without the need to maintain two different approaches We believe this is the only path forward to build the comprehensive Survey and Experience Management software we're aiming for. ### Migration Steps for v4.0 Additional migration steps are needed if you are using a self-hosted Formbricks setup that uses either local file storage (not S3-compatible file storage) or doesn't already use a Redis cache. ### Legacy one-click v4.0 upgrade For historical v4.0 upgrades, our original one-click migration script is still available: ```bash theme={null} # Download the latest script curl -fsSL -o migrate-to-v4.sh \ https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/migrate-to-v4.sh # Make it executable chmod +x migrate-to-v4.sh # Launch the guided migration ./migrate-to-v4.sh ``` This script guides you through the steps for the infrastructure migration and does the following: * Adds a Redis service to your setup and configures it * Adds a bundled MinIO service to your setup, configures it, and migrates local files to it * Pulls the latest Formbricks image and updates your instance ### Manual Setup If you use a different setup to host your Formbricks instance, you need to make sure to make the necessary adjustments to run Formbricks 4.0. #### Redis Formbricks 4.0 requires a Redis instance to work properly. Please add a Redis instance to your Docker setup, your K8s infrastructure, or however you are hosting Formbricks at the moment. Formbricks works with the latest versions of Redis as well as Valkey. You need to configure the `REDIS_URL` environment variable and point it to your Redis instance. #### S3-compatible storage To use file storage (e.g., file upload questions, image choice questions, custom survey backgrounds, etc.), you need to have S3-compatible file storage set up and connected to Formbricks. Formbricks supports multiple storage providers (among many other S3-compatible storages): * AWS S3 * Digital Ocean Spaces * Hetzner Object Storage * Custom RustFS server Please make sure to set up a storage bucket with one of these solutions and then link it to Formbricks using the following environment variables: ``` S3_ACCESS_KEY: your-access-key S3_SECRET_KEY: your-secret-key S3_REGION: us-east-1 S3_BUCKET_NAME: formbricks-uploads S3_ENDPOINT_URL: https://files.yourdomain.com # not needed for AWS S3 S3_FORCE_PATH_STYLE: 1 # set this only for custom endpoints like RustFS, MinIO, or LocalStack; omit for AWS S3 ``` #### Upgrade Process **1. Backup your Database** **Critical Step**: Create a complete database backup before proceeding. Formbricks 4.0 will automatically remove unused database tables and fields during startup. ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v4.0_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into "**No such container**", use `docker ps` to find your container name, e.g. > `formbricks_postgres_1`. **2. Upgrade to Formbricks 4.0** Pull the latest Docker images and restart the setup (example for docker-compose): ```bash theme={null} # Pull the latest version docker compose pull # Stop the current instance docker compose down # Start with Formbricks 4.0 docker compose up -d ``` **3. Automatic Database Migration** When you start Formbricks 4.0 for the first time, it will **automatically**: * Detect and apply required database schema updates * Remove unused database tables and fields * Optimize the database structure for better performance No manual intervention is required for the database migration. **4. Verify Your Upgrade** * Access your Formbricks instance at the same URL as before * Test file uploads to ensure S3 storage integration works correctly. Check the [File Upload Troubleshooting](/docs/self-hosting/configuration/file-uploads#troubleshooting) section if you face any issues. * Verify that existing surveys and data are intact * Check that previously uploaded files are accessible ### v3.3 > [!NOTE] > > With Formbricks 3.0, we introduced an automatic data migration system. If you're using a version older than > **v2.7**, you must upgrade step-by-step through earlier versions (e.g. **2.4 → 2.5 → 2.6 → 2.7**). Once you > reach **v2.7**, you can upgrade directly to **any v3.x or future release** without needing intermediate > migrations. ### Steps to Migrate This guide is for users who are **self-hosting Formbricks** using the **one-click setup**. If you have a different setup, you may need to adjust the commands accordingly. Before running these steps, **navigate to the `formbricks` directory** where your `docker-compose.yml` file is located. 1. **Backup your Database**: Backing up your database is crucial before upgrading. Use the following command to create a backup: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.3_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “**No such container**”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a restore scenario you will need to use `psql` then with an empty `formbricks` database. 1. Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` 1. Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` 1. Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` When you start the latest version of **Formbricks**, it will **automatically detect and apply any required data migrations** during startup. You don’t need to run any manual migration steps or download separate migration images. * Access your updated instance Once the containers are running, simply go to the **same URL** as before to access your updated **Formbricks** instance. That’s it! This new process ensures your **Formbricks** setup stays up to date with the latest schema changes as soon as you run the updated container. ### v3.2 > [!NOTE] > > With Formbricks 3.0, we introduced an automatic data migration system. If you're using a version older than > **v2.7**, you must upgrade step-by-step through earlier versions (e.g. **2.4 → 2.5 → 2.6 → 2.7**). Once you > reach **v2.7**, you can upgrade directly to **any v3.x or future release** without needing intermediate > migrations. ### Steps to Migrate This guide is for users who are **self-hosting Formbricks** using the **one-click setup**. If you have a different setup, you may need to adjust the commands accordingly. Before running these steps, **navigate to the `formbricks` directory** where your `docker-compose.yml` file is located. 1. **Backup your Database**: Backing up your database is crucial before upgrading. Use the following command to create a backup: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.2_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “**No such container**”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a restore scenario you will need to use `psql` then with an empty `formbricks` database. 1. Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` 1. Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` 1. Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` When you start the latest version of **Formbricks**, it will **automatically detect and apply any required data migrations** during startup. You don’t need to run any manual migration steps or download separate migration images. * Access your updated instance Once the containers are running, simply go to the **same URL** as before to access your updated **Formbricks** instance. That’s it! This new process ensures your **Formbricks** setup stays up to date with the latest schema changes as soon as you run the updated container. ### v3.1 > [!NOTE] > > With Formbricks 3.0, we introduced an automatic data migration system. If you're using a version older than > **v2.7**, you must upgrade step-by-step through earlier versions (e.g. **2.4 → 2.5 → 2.6 → 2.7**). Once you > reach **v2.7**, you can upgrade directly to **any v3.x or future release** without needing intermediate > migrations. ### Steps to Migrate This guide is for users who are **self-hosting Formbricks** using the **one-click setup**. If you have a different setup, you may need to adjust the commands accordingly. Before running these steps, **navigate to the `formbricks` directory** where your `docker-compose.yml` file is located. 1. **Backup your Database**: Backing up your database is crucial before upgrading. Use the following command to create a backup: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.1_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “**No such container**”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a restore scenario you will need to use `psql` then with an empty `formbricks` database. 1. Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` 1. Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` 1. Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` When you start the latest version of **Formbricks**, it will **automatically detect and apply any required data migrations** during startup. You don’t need to run any manual migration steps or download separate migration images. * Access your updated instance Once the containers are running, simply go to the **same URL** as before to access your updated **Formbricks** instance. That’s it! This new process ensures your **Formbricks** setup stays up to date with the latest schema changes as soon as you run the updated container. ## v3.0 > [!WARNING] > > **Important: Do Not Upgrade to 3.0 If You Need SSO, User Identification, or Cluster Support** > > With **Formbricks 3.0**, we're making changes to ensure long-term sustainability while still supporting open source. While the **Community Edition** has gained [new features](https://formbricks.com/blog/formbricks-3-0), some [advanced capabilities](https://formbricks.com/docs/self-hosting/license) are now part of the **Enterprise Edition**. > > ⚠️ **No Downgrade Option:** If you upgrade to **3.0** and run the data migration, **you cannot revert to 2.7.2**. If you rely on **SSO, user identification, or cluster support**, either **stay on version 2.7.x** or reach out to us on [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions) **for a custom quote**. This major release brings a better approach to **data migrations**. * If you're using **Formbricks v2.7 or later**, you can upgrade **directly** to **v3.x** and future versions. * If you're on a version **older than v2.7**, you **must upgrade step-by-step** (e.g. **2.4 → 2.5 → 2.6 → 2.7**) before moving to v3.x. ### Steps to Migrate This guide is for users **self-hosting** Formbricks with the **one-click setup**. If you're using a different setup, you might adjust the commands. * Navigate to the Formbricks Directory Before running any steps, go to the directory where your `docker-compose.yml` file is located. * Backup Your Database Backing up your database is **crucial** before upgrading. Use the following command to create a backup: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v3.0_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > **Note:** If you see a “No such container” error, run `docker ps` to find your actual container name (e.g. > `formbricks_postgres_1`). > [!NOTE] > > Tip: If you want to store the backup as a `.sql` file, remove the `-Fc` (custom format) option. If you need > to restore it later, use `psql` with an empty Formbricks database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` When you start the latest version of Formbricks, it will automatically detect and run any necessary data migrations during startup. There is no need to run any manual migration steps or pull any separate migration images. * Access your updated instance That’s it! Once the containers are up and running, simply navigate to the same URL as before to access your fully migrated Formbricks instance. ## v2.7 > [!NOTE] > > AI Features & Database Update: This release lays the groundwork for upcoming AI features, now in private beta. Formbricks requires the `pgvector` extension in PostgreSQL. > > One-Click Setup Users: Use the `pgvector/pgvector:pg15` image instead of `postgres:15-alpine` to ensure compatibility. Formbricks v2.7 includes all the features and improvements developed by the community during Hacktoberfest 2024. Additionally, this release introduces an advanced team-based access control system, which is available in the Formbricks Enterprise Edition. ### Additional Updates If you previously used organisation-based access control (an enterprise feature) and the `DEFAULT_ORGANIZATION_ROLE` environment variable, update its value to one of these roles: `owner`, `manager`, or `member`. Read more about the new roles in the [documentation](/docs/platform/features/user-management). ### Steps to Migrate This guide is for users who are self-hosting Formbricks using our one-click setup. If you are using a different setup, you might adjust the commands accordingly. To run all these steps, please navigate to the Formbricks folder where your `docker-compose.yml` file is located. * **Backup your Database:** This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database. ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.7_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. > [!NOTE] > > If you want to store the backup as an \*.sql file, remove the `-Fc` option. To restore, use `psql` with an > empty Formbricks database. * If you use an older `docker-compose.yml` file from the one-click setup, modify it to use the `pgvector/pgvector:pg15` image instead of `postgres:15-alpine`: ```yaml theme={null} services: postgres: image: pgvector/pgvector:pg15 volumes: - postgres:/var/lib/postgresql/data environment: - POSTGRES_DB=postgres - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres ports: - 5432:5432 ``` * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance and remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!TIP] > > To find the Docker network name for your Postgres database, run `docker network ls`. ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:latest && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.7" \ ghcr.io/formbricks/data-migrations:v2.7.0 ``` The command above will migrate your data to the latest schema. This step is important to update your existing data to the new structure. The changes will only be made if the script runs successfully. You can run the script multiple times safely. * That's it! Once the migration is finished, you can **access your Formbricks instance** at the same URL as before. ## v2.6 Formbricks v2.6 introduces advanced logic jumps for surveys, allowing more complex branching logic, including variables, conditions, and more. This release also includes numerous bug fixes, significant performance improvements for website and app surveys, and enhanced stability. > [!NOTE] > > This release includes the final step of deprecating server-side action tracking (previously used for segment > filtering by performed actions). The migrations will delete all tracked actions from the database. If you > still need these action records, ensure you export them before upgrading. ### Steps to Migrate This guide is for users who are self-hosting Formbricks using our one-click setup. If you're using a different setup, you might need to adjust the commands accordingly. To run these steps, navigate to the folder where your `docker-compose.yml` file is located. * **Backup your Database:** This is an important step. Make sure to back up your database before proceeding with the upgrade. You can use this command to back up your database: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.6_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you get a "No such container" error, run `docker ps` to find your container name, for example, > `formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a > restore scenario, you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find the Docker network name for your Postgres database, run the command: ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:latest && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.6" \ ghcr.io/formbricks/data-migrations:v2.6.0 ``` The command above will migrate your data to the latest schema. This is an important step to update your existing data to the new structure. Changes will only be made if the script runs successfully. You can run the script multiple times without issues. * Once the migration is complete, **you can access your Formbricks instance** at the same URL as before. ## v2.5 Formbricks v2.5 lets you visualise responses in a data table format. This release also brings a few bug fixes and performance improvements. > [!NOTE] > > This release fixes the inconsistency of CTA and consent question values when a question is skipped. The > value will now be set to an empty string instead of "dismissed" to maintain consistency with other > questions. ### Steps to Migrate This guide is for users self-hosting Formbricks with our one-click setup. If you're using a different setup, you may need to adjust the commands. To begin, navigate to the folder where your `docker-compose.yml` file is located. * **Backup your Database**: This step is important. Please make sure to back up your database before upgrading. You can use the following command to back up your database: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.5_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, > e.g.`formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a > restore scenario you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find your Docker Network name for your Postgres Database, find it using `docker network ls` ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:latest && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.5" \ ghcr.io/formbricks/data-migrations:v2.5.3 ``` The command will migrate your data to the latest schema, ensuring your existing data is updated to the new structure. Changes will only be made if the script runs successfully, and you can safely run the script multiple times. * Once the migration is complete, **you can access your Formbricks instance** at the same URL as before. ## v2.4 Formbricks v2.4 lets you create multiple endings for your surveys and choose which one users see based on logic jumps. This version also includes bug fixes and performance improvements. > [!NOTE] > > This release will remove support for advanced targeting (enterprise targeting for app surveys) using actions > (e.g. targeting users who triggered action x 3 times in the last month). Actions can still be used as > triggers, but they will no longer be stored on the server to improve Formbricks' overall performance. ### Steps to Migrate This guide is for users who are self-hosting Formbricks with our one-click setup. If you're using a different setup, you may need to adjust the commands accordingly. To follow these steps, go to the folder where your `docker-compose.yml` file is located. 1. **Backup your Database**: This step is important. Please make sure to back up your database before upgrading. You can use the following command to back up your database: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.4_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as a `*.sql` file, remove the `-Fc` (custom format) option. In case of a > restore scenario, you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` Now let's migrate the data to the latest schema: To find your Docker Network name for your Postgres Database, find it using `docker network ls` ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:v2.4.3 && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.4" \ ghcr.io/formbricks/data-migrations:v2.4.3 ``` The command above will migrate your data to the latest schema. This is an important step to update your data structure. Changes are only applied if the script runs successfully. You can run the script multiple times without issues. * That's it! Once the migration is done, you can access your Formbricks instance at the same URL as before. ### Additional Updates * The `CRON_SECRET` environment variable is now required to enhance the security of the internal cron APIs. Please ensure that this variable is set in your environment or `docker-compose.yml`. You can generate a secure secret using `openssl rand -hex 32` ## v2.3 Formbricks v2.3 introduces new colour options for rating questions, enhanced multi-language support for Chinese (Simplified & Traditional), and includes several bug fixes and performance improvements. ### Steps to Migrate > [!NOTE] > > You only need to run the data migration if you have surveys set up in Chinese (`zh`). If you don't have any > surveys in Chinese, you can skip the migration step. This guide is for users self-hosting Formbricks with our one-click setup. If you're using a different setup, adjust the commands as needed. To proceed, go to the folder where your `docker-compose.yml` file is located. * **Backup your Database**: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.3_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “**No such containe**r”, use `docker ps` to find your container name, e.g. > `formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a > restore scenario you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find your Docker Network name for your Postgres Database, find it using `docker network ls` ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:v2.3.0 && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.3" \ ghcr.io/formbricks/data-migrations:v2.3.0 ``` The command above will migrate your data to the latest schema, which is essential for updating your data structure. Changes will only be made if the script runs successfully. You can safely run the script multiple times. * Once the migration is complete, **you can access your Formbricks instance** at the same URL as before. ### Additional Updates The feature to create short URLs in Formbricks is now deprecated. Existing short URLs will continue to work for now, but it is recommended to use long URLs instead. Support for short URL redirects will be removed in a future release. ## v2.2 Formbricks v2.2 introduces XM research presets, providing a brand-new product onboarding experience. Our goal is to make user research "obviously easy" across different industries, starting with Software-as-a-Service and E-Commerce. ### Steps to Migrate This guide is for users who are self-hosting Formbricks with our one-click setup. If you're using a different setup, you may need to adjust the commands accordingly. To run all these steps, please navigate to the `formbricks` folder where your `docker-compose.yml` file is located. 1. **Backup your Database**: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.2_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, e.g. > `formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a > restore scenario you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find your Docker Network name for your Postgres Database, find it using `docker network ls` ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:v2.2 && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.2" \ ghcr.io/formbricks/data-migrations:v2.2 ``` The command above will migrate your data to the latest schema. This is an important step to update your existing data. Changes will only be made if the script runs successfully. You can safely run the script multiple times. * Once the migration is complete, **you can access your Formbricks instance** at the same URL as before. ### Changes in Environment Variables * The `ONBOARDING_DISABLED` environment variable is now deprecated. We have replaced the user onboarding with a product onboarding process that only runs when creating a new product. ## v2.1 Formbricks v2.1 introduces more options for creating No-Code Actions and improves the self-hosting experience with a new onboarding process for fresh instances. > [!NOTE] > > To improve the user experience and simplify setup for self-hosting instances, we are transitioning to a single organization model. This change allows self-hosts to manage their instance centrally and more easily control access. A new permissions system will also be introduced soon, providing more granular control over projects and resources within an organization. > > If you've previously created multiple organizations, you can still switch between them in the UI, but creating new organizations will no longer be possible. ### Steps to Migrate This guide is for users self-hosting Formbricks using our one-click setup. If you are using a different setup, you may need to adjust the commands accordingly. To follow these steps, please navigate to the Formbricks folder where your `docker-compose.yml` file is located. * **Backup your Database**: This is an essential step. Please ensure that you back up your database before proceeding with the upgrade. You can use the following command to back it up: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.1_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, e.g. > `formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as a `*.sql` file remove the `-Fc` (custom format) option. In case of a > restore scenario you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers. ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find your Docker network name for the Postgres database, run the following `docker network ls` ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:v2.1.0 && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.1" \ ghcr.io/formbricks/data-migrations:v2.1.0 ``` Once the migration script runs successfully, your data will be migrated to the latest schema. The script is designed to run safely multiple times, so you don’t need to worry if it’s executed more than once. After completing the migration, you can continue to access your Formbricks instance at the same URL as before. * That's it! Once the migration is complete, you can **now access your Formbricks instance** at the same URL as before. ### Changes in Environment Variables * **SIGNUP\_DISABLED** is now deprecated. Self-hosting instances have signup disabled by default, and new users can only be invited by the organization owner or admin. * **DEFAULT\_TEAM\_ID** has been renamed to **DEFAULT\_ORGANIZATION\_ID**. * **DEFAULT\_TEAM\_ROLE** has been renamed to **DEFAULT\_ORGANIZATION\_ROLE**. ## v2.0 Formbricks v2.0 introduces significant features such as **Multi-Language Surveys** and **Advanced Styling for Surveys**, aimed at improving the flexibility and appearance of your surveys. Additionally, the release includes several optimisations, bug fixes, and smaller improvements to ensure a smoother user experience. If you are upgrading to Formbricks v2.0, follow this guide to ensure a smooth migration of your existing Formbricks instance without encountering issues or build errors. > [!NOTE] > > This upgrade requires a **data migration**. Please make sure to back up your database before proceeding. > Follow the steps below to upgrade your Formbricks instance to v2.0. > [!NOTE] > > If you've used the Formbricks Enterprise Edition with a free beta license key, your instance will be > downgraded to the Community Edition 2.0. You can find all license details on the [license > page](https://formbricks.com/docs/self-hosting/license). > [!WARNING] > > We are moving from DockerHub to GitHub Packages for our images. If you are still pulling the images from > DockerHub please change `image: > formbricks/formbricks:latest` to `image:ghcr.io/formbricks/formbricks:latest` in > your `docker-compose.yml` file. ### Steps to Migrate This guide is for users who are self-hosting Formbricks using our one-click setup. If you are using a different setup, you might adjust the commands accordingly. To run all these steps, please navigate to the `formbricks` folder where your `docker-compose.yml` file is located. 1. **Backup your Database**: This is an essential step. Please ensure that you back up your database before proceeding with the upgrade. You can use the following command to back it up: ```bash theme={null} docker exec formbricks-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v2.0_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. If you prefer storing the backup as an `*.sql` file remove the `-Fc` (custom format) option. In case of a restore scenario you will need to use `psql` then with an empty `formbricks` database. * Pull the latest version of Formbricks: ```bash theme={null} docker compose pull ``` * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers with the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find your Docker Network name for your Postgres Database, find it using `docker network ls` ```bash theme={null} docker pull ghcr.io/formbricks/data-migrations:v2.0.3 && \ docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v2.0" \ ghcr.io/formbricks/data-migrations:v2.0.3 ``` The above command will migrate your data to the latest schema. This is a crucial step to migrate your existing data to the new structure. Only if the script runs successful, changes are made to the database. The script can safely run multiple times. * That's it! Once the migration is complete, you can **now access your Formbricks instance** at the same URL as before. ### App Surveys with @formbricks/js With this upgrade, we now dynamically fetch the package from our API endpoint and have updated the package entry points to support both app and website surveys. This ensures that you always have the latest version of the package (v2.0.0+). **Old approach:** (v1.6.5) ```ts theme={null} import formbricks from "@formbricks/js"; formbricks.init({ environmentId: "", apiHost: "", userId: "", // optional }); ``` **New approach:** (v2.0.0) Website surveys: ```ts theme={null} import formbricks from "@formbricks/js/website"; formbricks.init({ environmentId: "", apiHost: "", // userId is not supported here }); ``` App surveys: ```ts theme={null} import formbricks from "@formbricks/js/app"; formbricks.init({ environmentId: "", apiHost: "", userId: "", // required }); ``` ## v1.6 Formbricks v1.6 introduces key features like Advanced Targeting, Segmentation, on-the-fly survey triggers, and stability improvements. This update also changes some environment variables. Follow this guide to upgrade your Formbricks instance to v1.6 smoothly. > [!NOTE] > > This upgrade requires a data migration. Ensure you back up your database before proceeding. Follow the steps > below to upgrade your Formbricks instance to v1.6. ### Steps to Migrate This guide is for users self-hosting Formbricks with our one-click setup. If you're using a different setup, adjust the commands accordingly. Navigate to the Formbricks folder containing your `docker-compose.yml` file to run the steps. * **Backup your Database**: This is a crucial step. Please make sure to backup your database before proceeding with the upgrade. You can use the following command to backup your database: ```bash theme={null} docker exec formbricks-quickstart-postgres-1 pg_dump -Fc -U postgres -d formbricks > formbricks_pre_v1.6_$(date +%Y%m%d_%H%M%S).dump ``` > [!NOTE] > > If you run into “No such container”, use `docker ps` to find your container name, > e.g. `formbricks_postgres_1`. > [!NOTE] > > If you prefer storing the backup as a `*.sql` file remove the `-Fc` (custom format) option. In case of a > restore scenario you will need to use `psql` then with an empty `formbricks` database. * Stop the running Formbricks instance & remove the related containers: ```bash theme={null} docker compose down ``` * Restarting the containers will automatically pull the latest version of Formbricks: ```bash theme={null} docker compose up -d ``` * Now let's migrate the data to the latest schema: > [!NOTE] > > To find your Docker Network name for your Postgres Database, find it using `docker network ps` ```bash theme={null} docker run --rm \ --network=formbricks_default \ -e DATABASE_URL="postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" \ -e UPGRADE_TO_VERSION="v1.6" \ ghcr.io/formbricks/data-migrations:v1.6.1 ``` The above command will migrate your data to the latest schema. This is a crucial step to migrate your existing data to the new structure. Only if the script runs successful, changes are made to the database. The script can safely run multiple times. 1. That's it! Once the migration is complete, you can **now access your Formbricks instance** at the same URL as before. #### Restoring the database after a failed upgrade ```bash theme={null} docker exec -i formbricks-quickstart-postgres-1 pg_restore --clean -U postgres -v -d formbricks < formbricks_pre_v1.6_.dump ``` > [!NOTE] > > Replace the path to `formbricks_pre_v1.6_.dump` with the exact path to your `.dump` file. > [!NOTE] > > This will wipe the database and restore from the `.dump` file. ### App Surveys with `@formbricks/js` If you're using the `@formbricks/js` package, update it to version \~1.6.5 to access the latest features and improvements. > [!NOTE] > > Currently, the package needs to be pinned to `~1.6.5`, see [this > issue](https://github.com/formbricks/formbricks/issues/2273). ### Upgrade and pin the client package ```bash theme={null} npm install @formbricks/js@~1.6.5 ``` ### Deprecated Environment Variables | Environment Variable | Comments | | - | - | | `GITHUB_AUTH_ENABLED` | Was used to enable GitHub OAuth, but from v1.6, you can just set the `GITHUB_ID` and `GITHUB_SECRET` environment variables. | | `GOOGLE_AUTH_ENABLED` | Was used to enable Google OAuth, but from v1.6, you can just set the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables. | | `AZUREAD_AUTH_ENABLED` | Was used to enable AzureAD OAuth, but from v1.6, you can just set the `AZUREAD_CLIENT_ID`, `AZUREAD_CLIENT_SECRET` & `AZUREAD_TENANT_ID` environment variables. | ## v1.2 Formbricks v1.2 introduces new features for Link Surveys and enhances security. However, there are some breaking changes related to environment variables. This guide will help you upgrade your Formbricks instance to v1.2 smoothly. ### New Environment Variables | Environment Variable | Required | Recommended Generation | Comments | | - | - | - | - | | `ENCRYPTION_KEY` | true | `openssl rand -hex 32` | Needed for 2 Factor Authentication | ### Deprecated / Removed Environment Variables | Environment Variable | Comments | | - | - | | `SURVEY_BASE_URL` | The `WEBAPP_URL` is now used to determine the survey base URL in all places | ## v1.1 Formbricks v1.1 introduces new features and improvements but includes breaking changes with environment variables. This guide will help you upgrade your Formbricks instance to v1.1 without data loss. ### Renamed Environment Variables | till v1.0 | v1.1 | | - | - | | `NEXT_PUBLIC_EMAIL_VERIFICATION_DISABLED` | `EMAIL_VERIFICATION_DISABLED` | | `NEXT_PUBLIC_PASSWORD_RESET_DISABLED` | `PASSWORD_RESET_DISABLED` | | `NEXT_PUBLIC_SIGNUP_DISABLED` | `SIGNUP_DISABLED` | | `NEXT_PUBLIC_INVITE_DISABLED` | `INVITE_DISABLED` | | `NEXT_PUBLIC_PRIVACY_URL` | `PRIVACY_URL` | | `NEXT_PUBLIC_TERMS_URL` | `TERMS_URL` | | `NEXT_PUBLIC_IMPRINT_URL` | `IMPRINT_URL` | | `NEXT_PUBLIC_GITHUB_AUTH_ENABLED` | `GITHUB_AUTH_ENABLED` | | `NEXT_PUBLIC_GOOGLE_AUTH_ENABLED` | `GOOGLE_AUTH_ENABLED` | | `NEXT_PUBLIC_WEBAPP_URL` | `WEBAPP_URL` | | `NEXT_PUBLIC_IS_FORMBRICKS_CLOUD` | `IS_FORMBRICKS_CLOUD` | | `NEXT_PUBLIC_SURVEY_BASE_URL` | `SURVEY_BASE_URL` | Please note that their values and the logic remains exactly the same. Only the prefix has been deprecated. The other environment variables remain the same as well. ### Deprecated Environment Variables * **`NEXT_PUBLIC_VERCEL_URL`**: Was used as deployment URL fallback (used instead of `WEBAPP_URL`), but from v1.1, you can just set the `WEBAPP_URL` environment variable. * **`RAILWAY_STATIC_URL`**: Was used as Railway Static URL (used instead of `WEBAPP_URL`), but from v1.1, you can just set the `WEBAPP_URL` environment variable. * **`RENDER_EXTERNAL_URL`**: Was used as an external URL to Render (used instead of `WEBAPP_URL`), but from v1.1, you can just set the `WEBAPP_URL` environment variable. * **`HEROKU_APP_NAME`**: Was used to build the App name on a Heroku hosted webapp, but from v1.1, you can just set the `WEBAPP_URL` environment variable. * **`NEXT_PUBLIC_WEBAPP_URL`**: Was used for the same purpose as `WEBAPP_URL`, but from v1.1, you can just set the `WEBAPP_URL` environment variable. * **`PRISMA_GENERATE_DATAPROXY`**: Was used to tell Prisma that it should generate the runtime for Dataproxy usage. But its officially deprecated now. ### Helper Shell Script For a seamless migration, below is a shell script for your self-hosted instance that will automatically update your environment variables to be compliant with the new naming conventions. ### Docker & Single Script Setup Now that these variables can be defined at runtime, you can append them inside your `x-environment` in the `docker-compose.yml` itself. For a more detailed guide on these environment variables, please refer to the [Environment Variables](/docs/self-hosting/configuration/environment-variables) page. ```yaml docker-compose.yml theme={null} version: "3.3" x-environment: &environment environment: # The url of your Formbricks instance used in the admin panel WEBAPP_URL: # Required for next-auth. Should be the same as WEBAPP_URL NEXTAUTH_URL: # PostgreSQL DB for Formbricks to connect to DATABASE_URL: "postgresql://postgres:postgres@postgres:5432/formbricks?schema=public" # NextJS Auth # @see: https://next-auth.js.org/configuration/options#nextauth_secret # You can use: `openssl rand -hex 32` to generate one NEXTAUTH_SECRET: # PostgreSQL password POSTGRES_PASSWORD: postgres # Email Configuration MAIL_FROM: MAIL_FROM_NAME: SMTP_HOST: SMTP_PORT: SMTP_SECURE_ENABLED: SMTP_USER: SMTP_PASSWORD: # Uncomment the below and set it to 1 to disable Email Verification for new signups # EMAIL_VERIFICATION_DISABLED: # Uncomment the below and set it to 1 to disable Password Reset # PASSWORD_RESET_DISABLED: # Uncomment the below and set it to 1 to disable Signups # SIGNUP_DISABLED: # Uncomment the below and set it to 1 to disable loging in with email # EMAIL_AUTH_DISABLED: # Uncomment the below and set it to 1 to disable Invites # INVITE_DISABLED: # Uncomment the below and set a value to have your own Privacy Page URL on the signup & login page # PRIVACY_URL: # Uncomment the below and set a value to have your own Terms Page URL on the auth and the surveys page # TERMS_URL: # Uncomment the below and set a value to have your own Imprint Page URL on the auth and the surveys page # IMPRINT_URL: # Uncomment the below and set to 1 if you want to enable GitHub OAuth # GITHUB_AUTH_ENABLED: # GITHUB_ID: # GITHUB_SECRET: # Uncomment the below and set to 1 if you want to enable Google OAuth # GOOGLE_AUTH_ENABLED: # GOOGLE_CLIENT_ID: # GOOGLE_CLIENT_SECRET: ``` If you have any questions or require help, feel free to reach out to us on [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions). 😃[ ](https://formbricks.com/docs/developer-docs/rest-api) # Release and Maintenance Policy Source: https://formbricks.com/docs/self-hosting/advanced/release-maintenance-policy Which Formbricks releases receive security updates and bug fixes, and for how long This policy defines which Formbricks releases receive security updates and bug fixes. It applies to every self-hosted installation, Community and Enterprise alike. > [!NOTE] > > This page covers which releases get fixes. Response times, recovery targets and other support commitments > for Enterprise customers are defined in your contract, not here. ## Versioning Formbricks follows [Semantic Versioning](https://semver.org/): `Major.Minor.Patch`, for example `6.2.1`. | Release | Contains | Example | | - | - | - | | Major | Breaking changes that need migration steps | `5.x` → `6.0.0` | | Minor | New features and improvements | `6.1.0` → `6.2.0` | | Patch | Bug fixes and security fixes, no new features | `6.2.0` → `6.2.1` | Every release is published on [GitHub Releases](https://github.com/formbricks/formbricks/releases) with its release notes. ## Maintained Versions Each minor release is maintained for **three calendar months**, starting on the day its first stable version is published. Release candidates and the date you installed it do not count. If the ending month has no matching day, support ends on the last day of that month: a minor published on November 30 is maintained through the last day of February. * Patch releases do not restart the clock. `6.2.3` ends support on the same day as `6.2.0`. * A newer minor does not shorten the window of an older one. This is a time window, not a cap on the number of maintained versions. * The support-end date of each minor is published in its release notes. Support runs through the end of that day. What a release receives depends on where it sits in its window: | Release | Bug fixes | Security fixes | | - | - | - | | Latest minor | ✅ | ✅ | | Older minor, still within its window | ❌ | ✅ | | Older minor, past its support-end date | ❌ | ❌ | A maintained minor is not a frozen version. To stay covered, install its patch releases as they are published. ## Security Fixes * **High and Critical vulnerabilities** (validated CVSS v4.0 base score of 7.0 or higher) are fixed on every maintained minor. A public CVE is not required. * **Lower-severity vulnerabilities** are fixed in the latest minor only. Active exploitation, or a credible attack chain with serious impact on customers, gets an expedited review regardless of score. * **Dependency vulnerabilities** follow the same rules. A scanner match alone does not mean a release is affected; we verify whether the vulnerable code path is reachable in Formbricks. * If a fix cannot be safely backported to an older minor, we publish a mitigation or upgrade guidance for it instead. These rules define which releases are covered. They are not a promise about how fast a fix ships. ## Bug Fixes Non-security bug fixes ship in the **latest minor only**. Older minors receive security fixes only, even when a bug is blocking for you. To receive a bug fix, upgrade to the latest minor. ## End of Support After its support-end date, no new fixes are accepted for a minor. Upgrade to a maintained minor to stay covered. A security fix accepted for backport before the end date is still completed and published, even if the work finishes after it. ## Upgrade Recommendations * Run the latest stable release. It is the only version that receives every fix. * Pin a release tag in production instead of a moving tag such as `latest`. * Read the [migration guide](/docs/self-hosting/advanced/migration) before a major upgrade. Major versions can carry breaking changes that need steps before you switch images. * Plan to move to a newer minor before your current one reaches its support-end date. ## Exceptions Backports beyond this policy are rare. They require a documented risk assessment and approval from Formbricks security leadership. Enterprise customers can raise a request through their support channel. # Upgrade Formbricks Source: https://formbricks.com/docs/self-hosting/advanced/upgrade The steps to follow for every self-hosted upgrade, whatever the version. Every self-hosted upgrade follows the same steps. They take a short maintenance window: Formbricks is unavailable from the moment you stop it until the new version is running, usually a few minutes. Since v6, Formbricks keeps its permissions in SpiceDB. A new version can change how those permissions are stored, so each upgrade includes one **preparation** command that brings SpiceDB up to date before the new version starts. When a release leaves the SpiceDB schema unchanged, the command finds nothing to rewrite and finishes quickly. When the schema changes, as from 6.0 to 6.1, it also asks you to confirm the current schema first (see the preparation step below). > [!NOTE] > > Upgrading from v5? Follow the [v6 maintenance upgrade](/docs/self-hosting/advanced/v6-maintenance-upgrade) > instead. It covers setting up SpiceDB for the first time. ## Before you start 1. **Read what changed.** Check the [release notes](https://github.com/formbricks/formbricks/releases) and the [migration guide](/docs/self-hosting/advanced/migration) for every version between yours and the target. Most releases need nothing extra; the ones that do say so there. 2. **Use a supported path.** Upgrade one major version at a time (for example 6.x → 7.x, never 5.x → 7.x). Each release lists the upgrade pair it was tested with. 3. **Plan a short maintenance window** and let your users know. ## Docker and one-click Run these from the folder that holds your `docker-compose.yml` (for one-click installs, `formbricks`): **1. Download the new images** ```bash theme={null} docker compose pull ``` This only downloads. Formbricks keeps running. If your `docker-compose.yml` pins a version instead of `latest`, first set the same target image on all four services that use it: `formbricks`, `formbricks-migrate`, `authzed-ops` and `authzed-initialize`. Preparation runs in `authzed-ops`, so an old image there would prepare for the old release. **2. Stop Formbricks** Stop everything that writes to the database, and leave the databases running: ```bash theme={null} docker compose stop formbricks hub hub-worker ``` If you enabled the taxonomy service, add `taxonomy` to that command. **3. Back up both databases** ```bash theme={null} umask 077 # the dumps hold all your data: keep them readable only by you docker compose exec -T postgres pg_dump -Fc -U postgres -d formbricks > formbricks_$(date +%Y%m%d_%H%M%S).dump docker compose exec -T postgres pg_dump -Fc -U postgres -d spicedb > spicedb_$(date +%Y%m%d_%H%M%S).dump ``` Keep a copy of your `.env` file as well. If you use a managed database, take a snapshot there instead. **4. Prepare SpiceDB with the new version** ```bash theme={null} docker compose --profile authzed-ops run --rm --no-deps \ --entrypoint formbricks-authzed-prepare authzed-ops \ --backup-confirmed --writers-stopped ``` If the release changes the SpiceDB schema, this first run stops with `upgrade_graph_not_ready`: it never overwrites a schema you have not confirmed. Read the current schema's digest, check the release notes for the schema change, then rerun with that digest: ```bash theme={null} docker compose --profile authzed-ops run --rm --no-deps authzed-ops upgrade check # copy "remoteDigest" from the "schema" section of the output docker compose --profile authzed-ops run --rm --no-deps \ --entrypoint formbricks-authzed-prepare authzed-ops \ --backup-confirmed --writers-stopped --expected-current-digest sha256: ``` Wait until it exits without an error. If it fails, keep Formbricks stopped. The command may already have run database migrations, so don't simply start the old version again: fix the cause and rerun it, or restore both backups before going back. Each error code, including a SpiceDB schema that needs review, is explained in [results and recovery](/docs/self-hosting/advanced/v6-maintenance-upgrade#results-and-recovery). **5. Start the new version** One-click installs: go to the folder that **contains** your `formbricks` folder, download the current updater and run it: ```bash theme={null} cd .. curl -fsSL https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/formbricks.sh -o formbricks.sh chmod +x formbricks.sh ./formbricks.sh update ``` Other Docker installs: ```bash theme={null} docker compose up -d ``` Database migrations run automatically on start. ## Kubernetes (Helm) **1. Stop Formbricks** Pause anything that could restart it (Argo CD, Flux, autoscalers), suspend Formbricks CronJobs, then scale the Formbricks and Hub deployments to zero. Wait until no Formbricks or Hub pod or Job is still running, including Jobs that started before you suspended them. Leave PostgreSQL and SpiceDB running. **2. Back up** Back up the Formbricks database and the SpiceDB database, and keep your Helm values and Secrets. **3. Prepare SpiceDB with the new version** Run the preparation as a one-off Job, using the new image and your existing database and SpiceDB settings. A ready-to-adapt Job is in the [maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade#helm-and-gitops). Wait for it to complete successfully. If the release changes the SpiceDB schema, add `--expected-current-digest sha256:` to the Job's arguments, with the digest that `formbricks-authzed upgrade check` reports for the current schema. If it fails, keep everything stopped and follow [results and recovery](/docs/self-hosting/advanced/v6-maintenance-upgrade#results-and-recovery). **4. Upgrade** ```bash theme={null} helm upgrade -n -f values.yaml --wait ``` The chart refuses to upgrade unless `authzed.migrationAcknowledged: true` is in your values. Installs that came from v5 already have it; installs that started on v6 add it once, after a successful preparation. Put it in the values file Argo CD or Flux reconciles from, not only on the command line, so the next sync doesn't drop it. Then resume Argo CD, Flux or your autoscalers. > [!TIP] > > For the 6.0 → 6.1 upgrade on Kubernetes, an opt-in [online upgrade](/docs/self-hosting/configuration/online-upgrade) > mode exists. It is still being validated and is not yet a supported replacement for the maintenance window, > so keep using the steps above. ## After the upgrade Sign in, open a survey and submit a test response. If something is wrong, restore both database backups and start the previous version again. Downgrading in place, without restoring the backups, is not supported. # Upgrade to Formbricks v6 Source: https://formbricks.com/docs/self-hosting/advanced/v6-maintenance-upgrade Prepare a self-hosted v5 installation for SpiceDB authorization during a maintenance window. Formbricks v6 uses SpiceDB for authorization. Self-hosted installations can upgrade directly from a supported v5 version during a maintenance window; a bridge release is not required for this path. PostgreSQL remains the source of roles and grants. SpiceDB stores the derived authorization graph. > [!NOTE] > > **Self-hosted upgrades do not use the Formbricks Cloud bridge.** Stop all writers, run the > release-matched preparation once, verify the result, and start v6. The bridge is a temporary Cloud > rollout artifact, not a product dependency or a step hidden inside the Helm chart. > [!WARNING] > > Use only an upgrade pair listed as tested in the target release notes. The > `formbricks-authzed-prepare` executable is available only in images containing this change, not in > previously published release candidates. This page is not evidence that a particular v5/v6 pair > has passed upgrade and restore testing. ## What runs where Deployment tooling owns maintenance, workload shutdown, infrastructure, and restart. The release image owns database migrations and authorization preparation. Neither the application nor the chart maintains an activation receipt, a migration authority switch, or a second authorization engine for this process. `formbricks-authzed-prepare` is a preparation command, **not an unattended installer**. It does not discover or stop writers, suspend controllers, take backups, or restart workloads. Its confirmations are operator acknowledgements, not proof that maintenance is active. Complete and verify those steps first. The command reuses the image's existing migration runner and `formbricks-authzed upgrade prepare` and `upgrade check` implementations. It does not automatically prune unexplained relationships. ## Before the maintenance window * Rehearse with a restored copy of the installation. Measure migrations, backfill, verification, and restoration time; use those measurements to communicate the maintenance window. * Pin the target Formbricks image by digest and the matching chart/Compose files. Preserve the current images, chart, values, secrets, and volume names. Do not combine this change with a PostgreSQL major upgrade, a storage migration, or unrelated Hub/Cube changes. * Treat the Helm chart version and application image version as separate pins. A chart-only patch can keep the same Formbricks `appVersion`; verify both values and the rendered image before upgrading. * Prepare private SpiceDB connectivity, dedicated datastore credentials, its reviewed version, and completed datastore migrations. Retain existing operator ownership; never install a second operator over an existing cluster-wide operator. See [SpiceDB operations](/docs/self-hosting/configuration/authzed-operations). Identify **all writers**, including Formbricks replicas, Hub/Hub workers, workflow workers, scheduled jobs, import jobs, integrations, and administrative scripts. Include workloads outside the application namespace or Compose project that write to the same databases. Identify Argo CD/Flux, image updaters, autoscalers, and other controllers that can recreate those workloads. Record their original state for restoration. Do not print Secret contents or expanded Compose configuration into shared CI logs. Prepare and render the exact target manifests before maintenance. ## Perform the upgrade **1. Enter and verify maintenance** Serve a human-readable maintenance page at the ingress/reverse proxy and stop accepting new work. Do not use an application API's JSON maintenance response as the public landing page. Suspend the identified controllers and schedules, stop all writers, and wait for in-flight work and database transactions to finish. Suspending a CronJob does not stop an already-running Job. Scaling a Deployment to zero is insufficient if an autoscaler or GitOps controller can restore it. Verify there are no remaining writer pods, containers, Jobs, external scripts, or active writer transactions. Keep only required infrastructure and the dedicated preparation process running. Keep maintenance active through preparation, restart, and access verification. **2. Take a recoverable backup** Take consistent backups after writers stop, including the application database, existing SpiceDB datastore, and any other datastore changed by the selected release. Retain secrets, configuration, storage state, and exact source images. Confirm the restore procedure has been tested. Online backups taken earlier are useful but are not a substitute for a known recovery point that includes the final writes accepted before maintenance. **3. Prepare using the target image** Run the command below using the exact target image and the same application database and AuthZed configuration that v6 will use. It first validates configuration and authenticated SpiceDB health, then runs application migrations, schema preparation, outbox drain, relationship repair, and a separate full verification. Preparation reconciles the graph and requires a clean full dry-run audit; the wrapper then performs a second independent full dry-run audit through `upgrade check`. `AUTHZED_CONSISTENCY` must be `fully_consistent`. An existing `.env` that still sets `AUTHZED_CONSISTENCY=minimize_latency` must be changed first: preparation and server startup both reject it. ```bash theme={null} formbricks-authzed-prepare --backup-confirmed --writers-stopped ``` A non-empty, different SpiceDB schema is not overwritten automatically. Review `schema check` and the release's schema changes, then repeat with `--expected-current-digest sha256:`. Only one preparation/schema-writing process may run at a time. **4. Deploy and test v6 while maintenance remains active** Only after preparation exits `0`, deploy the same image digest. Retain `fully_consistent` and the same datastore bindings. With Helm, set `authzed.migrationAcknowledged=true`; this is an explicit operator acknowledgement, not a database activation record. The upgrade hook only verifies the prepared graph; it does not apply schemas or backfill while old workloads are running. Verify the actual pod/container image IDs. Through restricted access, test an allowed user, a denied user, a scoped API key, organization/workspace lists, and a grant revocation. Verify outbox delivery, rerun `formbricks-authzed upgrade check`, and check operational-error metrics. Test a new browser session, then hard-refresh an old tab: cached v5 assets or Server Action references are not a valid v6 readiness signal. `/health` alone does not establish authorization readiness. **5. Resume service** Restore controller and worker settings only after their desired manifests point to the tested v6 release. Remove maintenance after the checks pass. Monitor authorization errors, outbox age, revocation delays, and scheduled relationship audits. Keep backups until upgrade acceptance ends. ## Docker and one-click Keep the **same Compose project name, database images, and volumes**. Prepare a target Compose file that retains customized SMTP, storage, networking, and Traefik settings. Pin `formbricks`, `formbricks-migrate`, `authzed-ops`, and `authzed-initialize` to the same target image digest. Do not copy a fresh-install Compose file over an existing installation without reviewing those differences. After stopping the old project's writers and verifying external writers/controllers are stopped, start only the required infrastructure from the reviewed target configuration. Never use `down -v`. With infrastructure already healthy, run the existing operations service without starting dependencies: ```bash theme={null} docker compose --profile authzed-ops run --rm --no-deps \ --entrypoint formbricks-authzed-prepare authzed-ops \ --backup-confirmed --writers-stopped ``` Supply your normal `--project-name`, `--env-file`, and `-f` options when customized. The operator service must receive the application database URL, migration credentials when different, and the six AuthZed client variables. The distributed default uses the bundled PostgreSQL database; customize it when your installation uses a managed database. No database or SpiceDB port needs public exposure. After successful preparation, a one-click installation also sets `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true` before its explicit v6 update. Do not invoke an unattended update or move a floating image tag until the release-specific installation tests pass. ## Helm and GitOps Prepare SpiceDB before the application upgrade. Keep the current database/storage settings and existing Secrets. During maintenance, use an explicit, temporary Kubernetes Job with the target Formbricks image, the same database/AuthZed environment bindings, and this command: ```yaml theme={null} apiVersion: batch/v1 kind: Job metadata: name: formbricks-v6-prepare spec: backoffLimit: 0 activeDeadlineSeconds: 7200 template: spec: restartPolicy: Never automountServiceAccountToken: false securityContext: runAsNonRoot: true runAsUser: 1001 containers: - name: prepare image: ghcr.io/formbricks/formbricks@sha256: command: ["formbricks-authzed-prepare"] args: ["--backup-confirmed", "--writers-stopped"] securityContext: allowPrivilegeEscalation: false capabilities: drop: ["ALL"] envFrom: - secretRef: name: formbricks-maintenance-env # Inert placeholders for the shared environment check. Preparation never reads them, and they are # not application secrets: never reuse these values in a running installation. env: - { name: ENCRYPTION_KEY, value: maintenance-unused } - { name: CUBEJS_API_SECRET, value: maintenance-unused } - { name: CUBEJS_API_URL, value: "http://localhost" } - { name: HUB_API_KEY, value: maintenance-unused } - { name: HUB_API_URL, value: "http://localhost" } - { name: REDIS_URL, value: "redis://localhost" } ``` This is a template, not a ready-to-apply manifest: set the namespace, digest, resource requests/limits, image-pull credentials, network policy, and environment bindings for your installation. The `formbricks-maintenance-env` Secret holds what preparation uses, with the values your release already uses: * `DATABASE_URL` * `AUTHZED_ENABLED=true`, `AUTHZED_ENDPOINT`, `AUTHZED_TOKEN`, `AUTHZED_SYSTEM_KEY`, `AUTHZED_INSECURE`, and `AUTHZED_CONSISTENCY=fully_consistent` * `WEBAPP_URL`, in every case. Preparation runs the database migrations, and the OAuth resource-link data migration (`eng_2343_backfill_oauth_resource_links`, first released in 5.4.0) derives each MCP OAuth client's resource link from it. Whenever that migration runs on a database with MCP OAuth clients, as in any upgrade from before 5.4.0, preparation stops with `upgrade_database_migration_failed` without it. The chart's application Secret does not necessarily contain `DATABASE_URL` or the AuthZed values, which the chart injects separately. Prefer explicit `valueFrom.secretKeyRef` bindings to existing Secrets when possible. Never put secrets on a command line or commit their values. If migrations use a different database credential, bind `MIGRATE_DATABASE_URL` as well as `DATABASE_URL`; the target image's migration runner uses it when set. If the configuration is still incomplete, the Job reports `upgrade_configuration_invalid` with the names of the variables to fix. Wait for Job completion and inspect its sanitized result before running `helm upgrade` or resuming an Argo CD/Flux reconciliation. Preparation is not a Helm migration hook or a permanent chart component. Delete the Job and any temporary environment Secret after acceptance; retain only sanitized evidence. There is no activation table to clean up. ## Exit checklist Keep maintenance active until all of these are true: * `formbricks-authzed-prepare` exited `0`, including its two clean full audits, and the v6 migration acknowledgement is set only for this prepared upgrade. * The running image ID, chart values, schema, outbox, and a fresh `formbricks-authzed upgrade check` match the reviewed target. * Allowed and denied users, a scoped API key, organization/workspace lists, and a grant revocation work from a fresh browser session; an old tab recovers after a hard refresh. Only then resume controllers and writers and remove the ingress maintenance page. ## Results and recovery Success prints one JSON result and exits `0`: ```json theme={null} {"status":"prepared","code":"upgrade_prepared","restartRequired":true} ``` Blocked preparation exits `2`, without a `restartRequired` field. It never authorizes restarting workloads, including when arguments were rejected before any work ran. The code identifies the failed step: | Code | Operator action | | - | - | | `upgrade_maintenance_required` | Complete and acknowledge backup and writer shutdown. | | `upgrade_invalid_arguments` | Check options and the reviewed digest format. | | `upgrade_timeout_unavailable` | Use the supported release image containing `timeout`. | | `upgrade_configuration_invalid` | Correct the required runtime environment and fully consistent mode. The result's `variables` array, when present, names the variables to fix, never their values. | | `upgrade_spicedb_unhealthy` | Check datastore migrations, networking, TLS, and token configuration. | | `upgrade_database_migration_failed` | Diagnose the migration in a restricted operator session; do not restart v5 blindly. | | `upgrade_graph_not_ready` | Inspect `schema check`, outbox status, and aggregate `upgrade check`; investigate invalid/orphaned data. | | `upgrade_verification_failed` | Keep maintenance active and resolve remaining graph or outbox drift. | A blocked result can carry more fields, never values from your data: * `"reason":"timeout"` and `timeoutSeconds`: the step ran out its time limit. It did not report a failure, so the code names the step, not a problem in it. Raise the limit and run preparation again. * `cause` and `retryable`: the step's own error code, such as `authzed_unavailable`, and whether that error is transient. Retry a `"retryable":true` result once its cause, such as SpiceDB availability, has recovered. Each step has a 90-minute limit. Set `FORMBRICKS_AUTHZED_PREPARE_STEP_TIMEOUT_SECONDS` (60 to 86400) to change it. The graph step rewrites every organization's relationships and then audits them all, so its runtime grows with the number of organizations: an instance with about 50,000 organizations needed about 35 minutes. Time the rehearsal, and keep the Job's `activeDeadlineSeconds` above the sum of its steps: a Job deadline stops the container before the wrapper can print a result. Interrupted containers can exit with a signal code rather than JSON; any nonzero exit remains blocked. The command never restarts a workload on success, failure, or interruption. Retry preparation with the same image after correcting the cause, provided the interrupted migration is safe to rerun. Never mark a failed Prisma migration applied without investigating it. ### Diagnose migration failures privately The wrapper deliberately does not offer raw output in shared Job logs: migration errors can contain credentials, SQL, or customer identifiers. In a restricted PostgreSQL operator session, inspect failed Prisma migration records in `_prisma_migrations` (`migration_name`, `started_at`, `finished_at`, `rolled_back_at`, and `logs`). Treat `logs` as sensitive; do not paste it into CI, tickets, or Slack. For failures before Prisma records the attempt, check connectivity and permissions in that restricted session. If a migration must be retried, first establish whether partial changes need repair, then use the target image's `node /home/nextjs/packages/database/dist/scripts/apply-migrations.js` under maintenance. Capture any diagnostic output only in operator-controlled storage; never enable it on normal startup. [If a migration fails](/docs/self-hosting/advanced/migration#if-a-migration-fails) shows how to find the real error, check what the failed migration left behind, and clear its failed record before retrying. After database changes, **`helm rollback` or changing the image is not necessarily a safe rollback**. Remain in maintenance and either complete the v6 preparation or restore the coordinated backup and matching v5 images/configuration. Resuming writes before restoration risks losing those new writes. ## Later v6 upgrades The same read-only `upgrade check` gate also applies to v6.x updates. With an unchanged canonical SpiceDB schema and a clean graph/outbox, no additional authorization preparation is needed. One-click stops the stack before application migrations and starts it only after they succeed. Helm keeps its existing application-migration lifecycle; follow the target release's compatibility and maintenance notes. If a release changes the canonical SpiceDB schema, this flow deliberately blocks the upgrade until explicit maintenance preparation has completed with that target image and a reviewed current digest. Use the procedure above again; the persistent acknowledgement is not permission to skip preparation. An online, backward-compatible schema rollout would need its own reviewed and tested release procedure; neither the Helm hook nor the one-click updater infers that a schema change is safe while writers run. ### Survey visibility The release that introduces survey visibility changes the canonical SpiceDB schema (it adds survey ownership and visibility), so it goes through the maintenance preparation above. Surveys are then projected into SpiceDB as their own scope. Nothing about who can see a survey changes until you opt in: > [!NOTE] > > Once the marker is set, every survey a person creates starts **Restricted** to its author and the > organization's owners and managers. They can make it visible to the workspace from **Collaborate** or > when activating it. See [Survey visibility](/docs/surveys/general-features/visibility). 1. Once every container or pod runs the new version, check durable delivery and replay any dead-lettered survey events. The migration adds the survey trigger while the previous version may still be delivering outbox events, and that version dead-letters the `survey` event type it does not know. A dead-lettered survey revocation makes every enforced authorization check fail closed until it is replayed: ```bash theme={null} formbricks-authzed outbox status formbricks-authzed outbox replay formbricks-authzed outbox drain ``` `replay` resets every unresolved dead letter, so investigate any that are not survey events first. See [AuthZed operations](/docs/self-hosting/configuration/authzed-operations#audit-and-repair-surveys) for how to list them. 2. After the upgrade, repair the survey scope and mark it ready. This runs the repair, then two further dry runs, and sets the marker only if both come back clean: ```bash theme={null} formbricks-authzed backfill --scope=survey --apply --mark-ready ``` 3. Confirm `formbricks-authzed upgrade check` reports `scopes.survey` as ready. To go back to workspace permissions, run `formbricks-authzed backfill --scope=survey --clear-ready`. See [AuthZed operations](/docs/self-hosting/configuration/authzed-operations#audit-and-repair-surveys) for the audit and repair commands. # Authentication Behavior Source: https://formbricks.com/docs/self-hosting/auth-behavior Learn how authentication and user invitation work in self-hosted Formbricks deployments. ## Overview In self-hosted Formbricks, user management and authentication can be customized using environment variables. By default, self-hosted instances have user signup disabled, and only organization owners or admins can invite new users. The behavior of the authentication and invitation flow can be further controlled using the following environment variables: * `AUTH_SKIP_INVITE_FOR_SSO` * `AUTH_SSO_DEFAULT_TEAM_ID` ## License Requirement for Role Management and SSO Behavior > [!NOTE] > > To control advanced role management features and environment-based SSO behavior, your self-hosted Formbricks > instance must have a valid enterprise license. ## Environment Variables ### `AUTH_SKIP_INVITE_FOR_SSO` * **Type:** Boolean (0 or 1) * **Default:** 0 (invite required) * **Description:** * When set to `1`, users who sign up via SSO (Single Sign-On) providers (such as Google, Azure AD, SAML, or OIDC) can create an account without requiring an invitation. * When set to `0` (default), all users—including those signing up via SSO—must be invited by an organization owner or admin before they can create an account. * **Use case:** * Set this to `1` if you want to allow anyone with access to your SSO provider to join your Formbricks instance without a manual invite. * Keep it at `0` for stricter access control, where only invited users can join, regardless of SSO. ### `AUTH_SSO_DEFAULT_TEAM_ID` * **Type:** String (Team ID, a valid cuid) * **Default:** None (must be set if you want to use default team assignment) * **Description:** * When a new user is invited or signs up (if allowed), they will automatically be added to the team with the ID specified in this variable. * This is useful for onboarding users into a default team, ensuring they have access to relevant Workspaces and resources immediately after joining. * **Use case:** * Set this to the ID of your default team to streamline onboarding for new users. * If not set, users will not be automatically assigned to any team upon signup or invite acceptance. ## Example `.env` Configuration ```env theme={null} # Allow SSO users to join without invite AUTH_SKIP_INVITE_FOR_SSO=1 # Automatically assign new users to this team AUTH_SSO_DEFAULT_TEAM_ID=team-123 ``` Refer to the [Environment Variables documentation](./configuration/environment-variables) for a full list and details. *** For more information on SSO setup, see: * [Google OAuth](./configuration/auth-sso/google-oauth) * [Azure AD OAuth](./configuration/auth-sso/azure-ad-oauth) * [Open ID Connect](./configuration/auth-sso/open-id-connect) * [Keycloak OIDC](./configuration/auth-sso/keycloak-oidc) * [SAML SSO](./configuration/auth-sso/saml-sso) > [!NOTE] > > Formbricks does not support special characters, such as Cyrillic, in account email addresses to avoid technical, compatibility, and security issues. Additionally, universal support for such addresses is still limited. # Configuration Source: https://formbricks.com/docs/self-hosting/configuration Everything you can configure on a self-hosted Formbricks instance, and where each setting lives. A fresh instance runs with sensible defaults. Everything below is optional, and most of it is a matter of adding environment variables and restarting your containers. > [!NOTE] > > Almost every setting on this page is an environment variable. [Environment > Variables](/docs/self-hosting/configuration/environment-variables) is the full list, and the page to read > first. ## Getting mail out Formbricks sends verification mail, invitations, email follow-ups and email surveys. None of that works until you point the instance at an SMTP server. > [card] [SMTP](/docs/self-hosting/configuration/smtp) > > Point Formbricks at a mail server. > [card] [Job Runner](/docs/self-hosting/configuration/job-runner) > > Run the background worker that sends the mail and processes queued work. ## Reaching your instance Where Formbricks lives on the network, and how browsers get to it. > [card] [Domain Configuration](/docs/self-hosting/configuration/domain-configuration) > > Set the public-facing URL your instance answers on. > [card] [Custom SSL Certificate](/docs/self-hosting/configuration/custom-ssl) > > Bring your own certificate to the One-Click setup. > [card] [Custom Subpath](/docs/self-hosting/configuration/custom-subpath) > > Serve Formbricks under a path prefix instead of a domain root. > [card] [CDN](/docs/self-hosting/configuration/cdn) > > Cache public traffic without serving stale survey assets after an upgrade. ## Storing what people upload > [card] [File Uploads](/docs/self-hosting/configuration/file-uploads) > > Configure storage for survey images, file-upload answers and workspace assets. ## Connecting an LLM > [card] [AI Features](/docs/self-hosting/configuration/ai-features) > > Point the instance at Qwen/vLLM, Google Cloud, Azure or Bedrock, and turn AI on for your organization. ## Keeping the instance healthy > [card] [AuthZed Operations](/docs/self-hosting/configuration/authzed-operations) > > Configure, monitor, back up and repair the SpiceDB authorization dependency. > [card] [Rate Limiting](/docs/self-hosting/configuration/rate-limiting) > > The limits Envoy and the application server apply, and how to tune them. ## Signing in Out of the box people sign in with an email address and a password. Point the instance at your own identity provider instead and sign-in follows the rules you already enforce there. > [!NOTE] > > Single Sign-On is part of the [Enterprise Edition](/docs/self-hosting/advanced/license) — every provider > below, not only SAML. SAML additionally needs the `saml` entitlement on the licence. > [card] [Authentication Behavior](/docs/self-hosting/auth-behavior) > > Who may sign up, and whether an invitation is required. > [card] [Open ID Connect](/docs/self-hosting/configuration/auth-sso/open-id-connect) > > The generic OIDC setup. Start here if your provider is not listed separately. > [card] [Keycloak OIDC](/docs/self-hosting/configuration/auth-sso/keycloak-oidc) > > OIDC against a Keycloak realm. > [card] [Azure AD OAuth](/docs/self-hosting/configuration/auth-sso/azure-ad-oauth) > > Microsoft Entra ID, formerly Azure AD. > [card] [Google OAuth](/docs/self-hosting/configuration/auth-sso/google-oauth) > > Google Workspace accounts. > [card] [SAML SSO](/docs/self-hosting/configuration/auth-sso/saml-sso) > > SAML 2.0, for providers that do not speak OIDC. ## Connecting third-party tools [Airtable](/docs/self-hosting/configuration/integrations/airtable), [Google Sheets](/docs/self-hosting/configuration/integrations/google-sheets), [Notion](/docs/self-hosting/configuration/integrations/notion) and [Slack](/docs/self-hosting/configuration/integrations/slack) each need an OAuth app you register with the service, and its credentials as environment variables. [n8n](/docs/self-hosting/configuration/integrations/n8n), [Zapier](/docs/self-hosting/configuration/integrations/zapier) and [ActivePieces](/docs/self-hosting/configuration/integrations/activepieces) connect the other way round, through a Formbricks API key, and need no server configuration at all. Still struggling or something not working as expected? [Join our GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # AI Features Source: https://formbricks.com/docs/self-hosting/configuration/ai-features Connect an LLM to your instance and enable AI-powered helpers like survey translation and AI chart creation. A single organization toggle unlocks AI-assisted survey translation and AI chart creation across the app. Formbricks runs fine without AI — nothing is enabled until you connect a model. > [!NOTE] > > AI features are part of the [Enterprise Edition](/docs/self-hosting/advanced/license). See [AI > Features](/docs/platform/features/ai-features) for what the toggle unlocks and how your data is handled. Wiring up an LLM takes two steps: **1. Point the instance at a model** Set `AI_PROVIDER`, `AI_MODEL`, and the credentials for that provider as environment variables, then restart your containers. **2. Turn AI on for the organization** In the app, go to **Settings → Organization → General → Smart functionality (AI)** and enable the toggle. Only Owners and Managers can change it. ## Choosing a provider `AI_PROVIDER` accepts four values. Set only the variables for the provider you use — the rest can be omitted. | `AI_PROVIDER` | Runs on | | - | - | | `openai-compatible` | Any OpenAI-compatible `/v1` endpoint — Qwen/vLLM and friends. The self-hosted path. | | `google` | Google Cloud, for Gemini models. | | `azure` | Azure OpenAI / Foundry. | | `aws` | Amazon Bedrock. | ## OpenAI-compatible (self-hosted) The supported self-hosted path is Qwen served by vLLM behind an OpenAI-compatible `/v1` endpoint. Docker Compose and the Helm chart can both deploy that runtime for you — both paths are disabled by default and require GPU-capable hosts. ### Docker Compose The Docker stack deploys the Qwen/vLLM runtime through an opt-in Compose profile. It needs a GPU-capable Docker host with the NVIDIA Container Toolkit installed. ```bash theme={null} COMPOSE_PROFILES=qwen AI_PROVIDER=openai-compatible AI_MODEL=qwen3-14b-awq AI_OPENAI_COMPATIBLE_BASE_URL=http://vllm:8000/v1 AI_OPENAI_COMPATIBLE_PROVIDER_NAME=vllm AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS=1 ``` If you use the optional taxonomy service and want it to share the bundled Qwen runtime, start Docker Compose with `COMPOSE_PROFILES=qwen,taxonomy` and point `TAXONOMY_LLM_BASE_URL` at `http://vllm:8000/v1`. ### Kubernetes Helm The Formbricks Helm chart deploys the same runtime on GPU-capable Kubernetes nodes. ```yaml theme={null} llm: enabled: true ``` When `llm.enabled` is true, the chart deploys the vLLM router and Qwen serving engine. By default it also points the Formbricks app at the in-cluster OpenAI-compatible endpoint by injecting the required `AI_*` environment variables. Set `llm.autoConfigureApp=false` if you want the chart to deploy Qwen/vLLM but prefer to configure the app provider manually. ### Your own endpoint To use an endpoint you already run, do not enable the bundled runtime — keep the `qwen` Compose profile off, or `llm.enabled=false` in Helm. Point `AI_OPENAI_COMPATIBLE_BASE_URL` at your endpoint and add `AI_OPENAI_COMPATIBLE_API_KEY` if it requires one. `AI_PROVIDER` and `AI_MODEL` are always required. `AI_OPENAI_COMPATIBLE_BASE_URL` is the only variable specific to this provider that you must set, and it has to be a valid HTTP(S) URL. > [!WARNING] > > Use an `https://` endpoint whenever you set `AI_OPENAI_COMPATIBLE_API_KEY`. Formbricks accepts a plain `http://` > URL, so nothing stops you sending that key — and every prompt — in cleartext. Plain HTTP is only appropriate for > an endpoint that takes no credentials and is unreachable from outside your network, such as the bundled > `http://vllm:8000/v1` on the internal Compose network. ### Behind an OAuth2 gateway Some gateways in front of a model do not accept a static API key. They issue short-lived access tokens through the OAuth2 client-credentials flow instead: Formbricks exchanges a client ID and secret for a token at the gateway's token endpoint, and sends that token with every model request. Set `AI_OPENAI_COMPATIBLE_AUTH_MODE` and Formbricks fetches the token for you, refreshes it shortly before it expires, and requests a new one if the gateway rejects it — you never paste a token. ```bash theme={null} AI_PROVIDER=openai-compatible AI_MODEL=your-model AI_OPENAI_COMPATIBLE_BASE_URL=https://gateway.example.internal/v1 AI_OPENAI_COMPATIBLE_AUTH_MODE=oauth2-client-credentials AI_OPENAI_COMPATIBLE_OAUTH_TOKEN_URL=https://gateway.example.internal/oauth/token AI_OPENAI_COMPATIBLE_OAUTH_CLIENT_ID=formbricks AI_OPENAI_COMPATIBLE_OAUTH_CLIENT_SECRET=your-client-secret # Optional AI_OPENAI_COMPATIBLE_OAUTH_SCOPE="llm.invoke" AI_OPENAI_COMPATIBLE_OAUTH_AUTH_STYLE=basic AI_OPENAI_COMPATIBLE_OAUTH_EXTRA_PARAMS_JSON={"audience":"https://gateway.example.internal"} ``` * `AI_OPENAI_COMPATIBLE_OAUTH_AUTH_STYLE` decides where the client credentials go. `basic`, the default and the OAuth2 standard, sends them in the `Authorization` header of the token request. `post` sends them in the form body instead, which some gateways require. * `AI_OPENAI_COMPATIBLE_OAUTH_SCOPE` is a space-separated list of scopes, if your gateway asks for any. * `AI_OPENAI_COMPATIBLE_OAUTH_EXTRA_PARAMS_JSON` adds string parameters to the token request, such as the `audience` or `resource` some identity providers expect. * Leave `AI_OPENAI_COMPATIBLE_API_KEY` unset. Formbricks refuses to start when both are configured, so there is only ever one source of credentials. If the gateway rejects the credentials, survey generation tells the user to ask an administrator to check the AI provider configuration, and the server log records the failure without the secret or the token. > [!NOTE] > > If the token endpoint or the gateway uses a certificate from a private CA, set > `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` on the Formbricks container. No Formbricks setting is needed. Mutual TLS > (client certificates) is not supported. > [!NOTE] > > Structured outputs are a separate capability from authentication. Check that your gateway supports them before > setting `AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS=1`. > [!WARNING] > > In this mode both `AI_OPENAI_COMPATIBLE_OAUTH_TOKEN_URL` and `AI_OPENAI_COMPATIBLE_BASE_URL` must be > `https://` URLs: the client secret goes to the first on every token request and the access token to the > second on every model request, so Formbricks refuses to start with a plain `http://` endpoint for either. > The one exception is `localhost`, for local development against a mock gateway. ## Google Cloud ```bash theme={null} AI_PROVIDER=google AI_MODEL=gemini-3.5-flash AI_GOOGLE_CLOUD_PROJECT=your-project-id AI_GOOGLE_CLOUD_LOCATION=global ``` Formbricks passes `AI_GOOGLE_CLOUD_LOCATION` through as given and enforces no list of its own: `us` and `eu` are sent to their multi-region endpoints, and every other value — `global` and regional locations such as `europe-west3` — uses the SDK default endpoint. Which locations actually serve your model depends on Google's availability for that model and your serving mode, so check the [model page](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-5-flash) before picking one for data-residency reasons. `global` is the safe default. Credentials are optional. If the container already has Application Default Credentials, leave both credential variables unset. Otherwise pick one: * `AI_GOOGLE_CLOUD_APPLICATION_CREDENTIALS` — mount the service account key file into the container and set this to its path, for example `/run/secrets/google-cloud.json`. * `AI_GOOGLE_CLOUD_CREDENTIALS_JSON` — the entire contents of that key file, as a single-line JSON string. Formbricks parses this value, so paste the whole file: a truncated or hand-edited value fails as invalid JSON. > [!NOTE] > > Formbricks uses Google Cloud naming here, even though the underlying SDK still talks to Vertex AI endpoints for > Gemini model access. ## Azure ```bash theme={null} AI_PROVIDER=azure AI_MODEL=your-deployment-name AI_AZURE_API_KEY=your-api-key AI_AZURE_RESOURCE_NAME=your-resource ``` `AI_MODEL` is the deployment name, not the base model name. `AI_AZURE_API_VERSION` defaults to `v1`. Provide either `AI_AZURE_RESOURCE_NAME` or `AI_AZURE_BASE_URL` — the base URL wins when both are set. If you set the base URL, end it at `/openai` and do not append `/v1`: the Azure SDK adds the version segment itself, so `https://your-resource.openai.azure.com/openai/v1` produces requests against `/openai/v1/v1/…` and fails. ```bash theme={null} # Equivalent to the resource name above AI_AZURE_BASE_URL=https://your-resource.openai.azure.com/openai ``` ## AWS Bedrock ```bash theme={null} AI_PROVIDER=aws AI_MODEL=eu.anthropic.claude-sonnet-4-5-20250929-v1:0 AI_AWS_REGION=eu-central-1 AI_AWS_ACCESS_KEY_ID=your-access-key-id AI_AWS_SECRET_ACCESS_KEY=your-secret-access-key # Only for temporary credentials AI_AWS_SESSION_TOKEN=your-session-token ``` ## External providers on Kubernetes Keep `llm.enabled=false` when you use Google Cloud, Azure, AWS Bedrock, or your own OpenAI-compatible runtime. Configure those providers with `deployment.env` in your Helm values or with environment variables in your deployment platform. ## Verifying the setup Restart your containers after changing any of these variables, then open **Settings → Organization → General**. While the instance is not configured, the AI toggle stays disabled and the page says so — the setting cannot be turned on from the UI until the environment variables are in place. > [!WARNING] > > An enabled toggle only means the variables are present and well-formed. Formbricks does not call your provider > to check it: an unreachable base URL, a wrong API key, or a deployment name that does not exist all pass this > check and fail on the first real request. So finish by exercising the model once — translate a survey into a second language, or ask the AI chart builder for a chart. If that request fails while the toggle is on, the credentials or the endpoint are wrong, not the configuration shape. If the toggle stays disabled after a restart, check the app logs: ```bash theme={null} docker compose logs formbricks | grep -i "ai" ``` The usual causes are `AI_MODEL` left unset, credentials that do not match the chosen `AI_PROVIDER`, or an `AI_GOOGLE_CLOUD_CREDENTIALS_JSON` value that is not valid JSON. The full list of `AI_*` variables, including the optional ones, is in the [environment variables reference](/docs/self-hosting/configuration/environment-variables). # Azure AD OAuth Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/azure-ad-oauth Configure Microsoft Entra ID (Azure AD) OAuth for secure Single Sign-On with your Formbricks instance. Use enterprise-grade authentication for your survey platform. > [!NOTE] > > AzureAD OAuth is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) ### Microsoft Entra ID Do you have a Microsoft Entra ID Tenant? Integrate it with your Formbricks instance to allow users to log in using their existing Microsoft credentials. This guide will walk you through the process of setting up an Application Registration for your Formbricks instance. ### Requirements * A Microsoft Entra ID Tenant populated with users. [Create a tenant as per Microsoft's documentation](https://learn.microsoft.com/en-us/entra/fundamentals/create-new-tenant). * A Formbricks instance running and accessible. * The callback URI for your Formbricks instance: `{WEBAPP_URL}/api/auth/oauth2/callback/azuread` > [!WARNING] > > **Upgrading from v5.1 or earlier?** This path changed once, at v5.2: > > * v5.1 and earlier: `{WEBAPP_URL}/api/auth/callback/azure-ad` > * v5.2 and later (current): `{WEBAPP_URL}/api/auth/oauth2/callback/azuread` > > The two are distinct URIs, because the provider id itself also changed (`azure-ad` → `azuread`). Add > the current one under **Redirect URIs** in your app registration, or Azure AD sign-in fails with a > redirect-URI mismatch. Upgrading from v5.2 or later needs no change — the callback URL is pinned and > does not move with Formbricks' authentication library. See the > [migration guide](/docs/self-hosting/advanced/migration). ## How to connect your Formbricks instance to Microsoft Entra **1. Access the Microsoft Entra admin center** * Login to the [Microsoft Entra admin center](https://entra.microsoft.com/). * Go to **Applications** > **App registrations** in the left menu. ![first](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250153/image_tobdth.jpg) **2. Create a new app registration** * Click the **New registration** button at the top. ![second](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250228/image_dmz75t.jpg) **3. Configure the application** * Name your application something descriptive, such as `Formbricks SSO`. ![third](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250292/image_rooa3w.jpg) * If you have multiple tenants/organizations, choose the appropriate **Supported account types** option. Otherwise, leave the default option for *Single Tenant*. ![fourth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250542/image_nyndzo.jpg) * Under **Redirect URI**, select **Web** for the platform and paste your Formbricks callback URI (see Requirements above). ![fifth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250776/image_s3pgb6.jpg) * Click **Register** to create the App registration. You will be redirected to your new app's *Overview* page after it is created. **4. Collect application credentials** * On the *Overview* page, under **Essentials**: * Copy the entry for **Application (client) ID** to populate the `AZUREAD_CLIENT_ID` variable. * Copy the entry for **Directory (tenant) ID** to populate the `AZUREAD_TENANT_ID` variable. > [!NOTE] > > Use the **Directory (tenant) ID** GUID (or a verified domain) — with it set, Formbricks fully > verifies Microsoft id\_tokens against your tenant's issuer. > > For a multi-tenant app registration, either leave `AZUREAD_TENANT_ID` unset, which is equivalent > to `common` and accepts both work/school and personal accounts, or set it to `organizations` to > accept work/school accounts only. Those two authorities advertise a placeholder issuer rather > than a real one, so Formbricks skips id\_token verification for them and takes the signed-in > identity from Microsoft's userinfo endpoint — the authority you configure still applies at > sign-in, so `organizations` keeps restricting which accounts Microsoft will accept. `consumers` > is unaffected: personal Microsoft accounts share one well-known tenant, so its id\_tokens are > verified normally. ![sixth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250876/image_dj2vi5.jpg) **5. Create a client secret** * From your App registration's *Overview* page, go to **Manage** > **Certificates & secrets**. ![seventh](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250913/image_p4zknw.jpg) * Make sure you have the **Client secrets** tab active, and click **New client secret**. ![eighth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738250973/image_kyjray.jpg) * Enter a **Description**, set an **Expires** period, then click **Add**. > [!NOTE] > > You will need to create a new client secret using these steps whenever your chosen expiry period ends. ![ninth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251467/image_bkirq4.jpg) * Copy the entry under **Value** to populate the `AZUREAD_CLIENT_SECRET` variable. > [!NOTE] > > Microsoft will only show this value to you immediately after creation, and you will not be able to access it again. If you lose it, simply create a new secret. ![tenth](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251234/image_jen6tp.jpg) **6. Update environment variables** * Update these environment variables in your `docker-compose.yml` or pass it like your other environment variables to the Formbricks container. > [!NOTE] > > You must wrap the `AZUREAD_CLIENT_SECRET` value in double quotes (e.g., "THis\~iS4faKe.53CreTvALu3"\`) to prevent issues with special characters. An example `.env` for Microsoft Entra ID in Formbricks would look like this: ```yml Formbricks Env for Microsoft Entra ID SSO theme={null} AZUREAD_CLIENT_ID=a25cadbd-f049-4690-ada3-56a163a72f4c AZUREAD_TENANT_ID=2746c29a-a3a6-4ea1-8762-37816d4b7885 AZUREAD_CLIENT_SECRET="THis~iS4faKe.53CreTvALu3" ``` **7. Restart and test** * Restart your Formbricks instance. * You're all set! Users can now sign up & log in using their Microsoft credentials associated with your Entra ID Tenant. ## Keeping display names in step with your directory > [!NOTE] > > SSO name synchronization is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) A user's name in Formbricks comes from the OIDC `name` claim, which is their Entra ID `displayName`. That attribute is free text, so its format is whatever your directory holds — accounts synced from on-premises Active Directory often read `Surname, Givenname`, while accounts created in the Entra admin center usually read `Givenname Surname`. Formbricks keeps whatever order your directory uses — it never reorders a name into `First Last`. It does normalize the value before storing it: characters outside the allowed set (letters, marks, spaces, and `' , . & ( ) -` plus digits) collapse to a single space, so `Doe, Jane` is stored unchanged while stray markup or line separators are replaced with a single space. Formbricks re-reads that name from Entra ID on every sign-in, so a rename in your directory — a marriage, a legal rename, a corrected import — reaches Formbricks the next time that person logs in. > [!NOTE] > > Because Entra ID is authoritative for the name, the **Full name** field under **Account → Profile** > is read-only for users who signed in through SSO, exactly as the email field already is. Change the > name in your directory instead. # Google OAuth Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/google-oauth Configure Google OAuth for secure Single Sign-On with your Formbricks instance. Implement enterprise-grade authentication for your survey platform with Google credentials. > [!NOTE] > > Google OAuth is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) ### Google OAuth Integrating Google OAuth with your Formbricks instance allows users to log in using their Google credentials, ensuring a secure and streamlined user experience. This guide will walk you through the process of setting up Google OAuth for your Formbricks instance. ### Requirements * A Google Cloud Platform (GCP) account * A Formbricks instance running ### How to connect your Formbricks instance to Google **1. Create a GCP Project** * Navigate to the [GCP Console](https://console.cloud.google.com/). * From the projects list, select a project or create a new one. **2. Setting up OAuth 2.0** * If the **APIs & services** page isn't already open, open the console left side menu and select **APIs & services**. * On the left, click **Credentials**. * Click **Create Credentials**, then select **OAuth client ID**. **3. Configure OAuth Consent Screen** * If this is your first time creating a client ID, configure your consent screen by clicking **Consent Screen**. * Fill in the necessary details and under **Authorized domains**, add the domain where your Formbricks instance is hosted. **4. Create OAuth 2.0 Client IDs** * Select the application type **Web application** for your project and enter any additional information required. * Ensure to specify authorized JavaScript origins and authorized redirect URIs. ``` Authorized JavaScript origins: {WEBAPP_URL} Authorized redirect URIs: {WEBAPP_URL}/api/auth/callback/google ``` **5. Update Environment Variables in Docker** * To integrate the Google OAuth, you have two options: either update the environment variables in the docker-compose file or directly add them to the running container. * In your Docker setup directory, open the `.env` file, and add or update the following lines with the `Client ID` and `Client Secret` obtained from Google Cloud Platform: ```sh theme={null} GOOGLE_CLIENT_ID=your-client-id-here GOOGLE_CLIENT_SECRET=your-client-secret-here ``` * Alternatively, you can add the environment variables directly to the running container using the following commands (replace `container_id` with your actual Docker container ID): ```sh theme={null} docker exec -it container_id /bin/bash export GOOGLE_CLIENT_ID=your-client-id-here export GOOGLE_CLIENT_SECRET=your-client-secret-here exit ``` **6. Restart Your Formbricks Instance** > [!NOTE] > > Restarting your Docker containers may cause a brief period of downtime. Plan accordingly. * Once the environment variables have been updated, it's crucial to restart your Docker containers to apply the changes. This ensures that your Formbricks instance can utilize the new Google OAuth configuration for user authentication. * Navigate to your Docker setup directory where your `docker-compose.yml` file is located. * Run the following command to bring down your current Docker containers and then bring them back up with the updated environment configuration. # Keycloak OIDC Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/keycloak-oidc Configure Keycloak as an OpenID Connect (OIDC) provider for secure Single Sign-On with your self-hosted Formbricks instance. > [!NOTE] > > Keycloak OIDC is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) Integrating Keycloak with your Formbricks instance allows users to log in using their existing Keycloak credentials via OpenID Connect. This guide walks you through setting up a Keycloak OIDC client and configuring Formbricks to use it, including automatic user provisioning into a default team. ### Requirements * A running Keycloak instance with a configured realm and users. * A self-hosted Formbricks instance with a valid [Enterprise license](/docs/self-hosting/advanced/license). * The Formbricks callback URI: `{WEBAPP_URL}/api/auth/oauth2/callback/openid` > [!WARNING] > > **Upgrading from v5.1 or earlier?** This path changed once, at v5.2: > > * v5.1 and earlier: `{WEBAPP_URL}/api/auth/callback/openid` > * v5.2 and later (current): `{WEBAPP_URL}/api/auth/oauth2/callback/openid` > > Upgrading from v5.2 or later needs no change — the callback URL is pinned and does not move with > Formbricks' authentication library. See the [migration guide](/docs/self-hosting/advanced/migration). ## Setting up Keycloak OIDC **1. Create a new client in Keycloak** * Log in to your Keycloak admin console. * Select the realm you want to use (e.g., `production`). * Navigate to **Clients** in the left menu and click **Create client**. * Set **Client type** to `OpenID Connect`. * Choose a **Client ID** (e.g., `formbricks`) and click **Next**. **2. Configure client authentication** * Enable **Client authentication** (this makes the client "confidential" and generates a client secret). * Under **Authentication flow**, ensure **Standard flow** is enabled. * Click **Next**. > [!NOTE] > > Formbricks uses PKCE (Proof Key for Code Exchange) for added security. Modern Keycloak versions (21+) support PKCE automatically for confidential clients. No additional PKCE configuration is needed. **3. Set the redirect URI** * Under **Valid redirect URIs**, add your Formbricks callback URI: ``` https://your-formbricks-domain.com/api/auth/oauth2/callback/openid ``` Replace `your-formbricks-domain.com` with your actual Formbricks URL. * Click **Save**. **4. Copy the client secret** * After saving, go to the **Credentials** tab of your newly created client. * Copy the **Client secret** value — you will need this for the Formbricks configuration. **5. Determine the issuer URL** The OIDC issuer URL follows this pattern: ``` https://your-keycloak-domain.com/realms/your-realm-name ``` For example, if your Keycloak runs at `login.example.com` and your realm is called `production`: ``` https://login.example.com/realms/production ``` > [!NOTE] > > You can verify the issuer URL by navigating to `https://your-keycloak-domain.com/realms/your-realm-name/.well-known/openid-configuration` in your browser. It should return a JSON document with the OIDC discovery endpoints. **6. Configure Formbricks environment variables** Add the following environment variables to your Formbricks `.env` file or `docker-compose.yml`: ```yml Formbricks Env for Keycloak OIDC theme={null} OIDC_CLIENT_ID=formbricks OIDC_CLIENT_SECRET=your-client-secret-here OIDC_ISSUER=https://your-keycloak-domain.com/realms/your-realm-name OIDC_DISPLAY_NAME="Keycloak Login" OIDC_SIGNING_ALGORITHM=RS256 ``` | Variable | Description | | - | - | | `OIDC_CLIENT_ID` | The Client ID you chose in Keycloak (e.g., `formbricks`). | | `OIDC_CLIENT_SECRET` | The client secret from the **Credentials** tab. | | `OIDC_ISSUER` | Your Keycloak realm URL (see step above). | | `OIDC_DISPLAY_NAME` | The label shown on the Formbricks login button. | | `OIDC_SIGNING_ALGORITHM` | Optional. Keycloak and Formbricks both default to `RS256`. Only set this if your realm uses a different algorithm. | **7. Restart and test** * Restart your Formbricks instance. * The login page should now display a button with your chosen `OIDC_DISPLAY_NAME`. * Click it to authenticate through Keycloak. > [!NOTE] > > To disable email/password login entirely and force all users through Keycloak, set `EMAIL_AUTH_DISABLED=1`. This hides the email/password form on the login page. ## Automatic User Provisioning By default, new SSO users must be invited by an organization admin before they can access Formbricks. To allow Keycloak users to join automatically and be assigned to a team, configure the following additional environment variables: ```yml Automatic User Provisioning theme={null} AUTH_SKIP_INVITE_FOR_SSO=1 AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here ``` | Variable | Description | | - | - | | `AUTH_SKIP_INVITE_FOR_SSO` | Set to `1` to let SSO users create an account without a manual invite. | | `AUTH_SSO_DEFAULT_TEAM_ID` | The ID of the team that new SSO users are automatically added to. The organization is determined from this team. | ### Finding Your Team ID 1. Log in to Formbricks as an admin. 2. Go to **Settings → Organization → Teams**. 3. Click **Manage Team** on the team you want to use as the default. 4. The Team ID is displayed in the modal. > [!NOTE] > > The Teams feature requires the **Role-Based Access Control (RBAC)** add-on on your Enterprise license. If you don't see the Teams section under **Settings → Organization**, contact [Formbricks support](mailto:support@formbricks.com) to enable it. ### How It Works When `AUTH_SKIP_INVITE_FOR_SSO=1` and `AUTH_SSO_DEFAULT_TEAM_ID` are both set: 1. A user authenticates through Keycloak for the first time. 2. Formbricks creates a new user account. 3. The user is automatically added as a **member** of the organization that owns the specified team. 4. The user is assigned to the default team, granting them access to all Workspaces associated with that team. No manual invitation or admin action is required. ## Full Configuration Example A complete `.env` configuration for Keycloak OIDC with automatic user provisioning: ```yml Complete Keycloak OIDC Configuration theme={null} OIDC_CLIENT_ID=formbricks OIDC_CLIENT_SECRET=your-client-secret-here OIDC_ISSUER=https://login.example.com/realms/production OIDC_DISPLAY_NAME="Company Login" OIDC_SIGNING_ALGORITHM=RS256 AUTH_SKIP_INVITE_FOR_SSO=1 AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here # Optional: disable email/password login to force Keycloak-only authentication # EMAIL_AUTH_DISABLED=1 ``` ## Troubleshooting > [accordion] Users see 'No access to Workspaces' after login > > This means the user was added to the organization but not assigned to a team. Verify that: > > * `AUTH_SSO_DEFAULT_TEAM_ID` is set correctly (the env variable name is `AUTH_SSO_DEFAULT_TEAM_ID`, not `DEFAULT_TEAM_ID`). > * The Team ID is a valid cuid that exists in your database. > * The team is linked to a Workspace via **Workspace Teams** settings. > > You can verify the team exists by checking your database: > > ```sql theme={null} > SELECT id, name, "organizationId" FROM "Team" WHERE id = 'your-team-id'; > ``` > [accordion] Users see 'No membership found' after login > > Formbricks determines the organization automatically from the `AUTH_SSO_DEFAULT_TEAM_ID` — you do not need to set a separate organization ID. If this error appears: > > * Verify the team specified in `AUTH_SSO_DEFAULT_TEAM_ID` exists and belongs to the correct organization. > * Confirm your Enterprise license includes the RBAC feature (required for Teams). > * Ensure the organization has an active billing plan that supports access control. > [accordion] OIDC login button does not appear > > * Confirm that `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, and `OIDC_ISSUER` are all set. > * Ensure your Formbricks instance has a valid Enterprise license. > * Restart the Formbricks container after adding the environment variables. > [accordion] Authentication fails with a redirect error > > * Verify the **Valid redirect URI** in your Keycloak client matches exactly: `{WEBAPP_URL}/api/auth/oauth2/callback/openid` > * If you're on v5.1 or earlier, the path is `{WEBAPP_URL}/api/auth/callback/openid` (without `/oauth2`) instead. > * Check that the OIDC issuer URL is reachable from your Formbricks server. You can test with: > > ```bash theme={null} > curl https://your-keycloak-domain.com/realms/your-realm-name/.well-known/openid-configuration > ``` # Okta OIDC Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/okta-oidc Configure Okta as an OpenID Connect (OIDC) provider for secure Single Sign-On with your self-hosted Formbricks instance. > [!NOTE] > > Okta OIDC is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) Integrating Okta with your Formbricks instance lets your users sign in with their existing Okta accounts over OpenID Connect. This guide walks you through creating an Okta app integration, finding the right issuer URL, and configuring Formbricks — including automatic user provisioning into a default team. > [!NOTE] > > Prefer SAML? Okta works either way — follow [SAML with Identity Providers](/docs/self-hosting/configuration/auth-sso/setup-saml-with-identity-providers#saml-with-okta) instead. OIDC is the simpler of the two: it needs no XML metadata file on the Formbricks side. ### Requirements * An Okta org with administrator access to the Admin Console. * A self-hosted Formbricks instance with a valid [Enterprise license](/docs/self-hosting/advanced/license). * The Formbricks callback URI: `{WEBAPP_URL}/api/auth/oauth2/callback/openid` > [!WARNING] > > **Upgrading from v5.1 or earlier?** This path changed once, at v5.2: > > * v5.1 and earlier: `{WEBAPP_URL}/api/auth/callback/openid` > * v5.2 and later (current): `{WEBAPP_URL}/api/auth/oauth2/callback/openid` > > Upgrading from v5.2 or later needs no change — the callback URL is pinned and does not move with > Formbricks' authentication library. See the [migration guide](/docs/self-hosting/advanced/migration). ## Setting up Okta OIDC **1. Create a new app integration in Okta** * Sign in to the Okta Admin Console. * Go to **Applications → Applications** in the sidebar. * Click **Create App Integration**. ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/create-app-integration.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=7fb1ad7cad43a945f1914a67370d61e5) **2. Choose OIDC and Web Application** In the **Create a new app integration** dialog: * **Sign-in method**: `OIDC - OpenID Connect` * **Application type**: `Web Application` Click **Next**. > [!NOTE] > > **Web Application**, not Single-Page Application. Formbricks completes the authorization code exchange on the server with a client secret, so it needs a confidential client. A SPA integration issues no secret and sign-in will fail. **3. Configure the app integration** | Field | Value | | - | - | | **App integration name** | Anything recognisable, e.g. `Formbricks`. | | **Grant type** | Leave **Authorization Code** selected (the default). Nothing else is required. | | **Sign-in redirect URIs** | `https://your-formbricks-domain.com/api/auth/oauth2/callback/openid` | | **Sign-out redirect URIs** | Leave empty — Formbricks does not use RP-initiated logout. | | **Assignments** | Choose who may sign in: a specific group, or *Allow everyone in your organization to access*. | Replace `your-formbricks-domain.com` with your actual Formbricks URL, then click **Save**. > [!WARNING] > > The redirect URI must match **exactly**, including the scheme and with no trailing slash. A mismatch surfaces in Okta as *"The 'redirect\_uri' parameter must be a Login redirect URI in the client app settings"*. > [!NOTE] > > Formbricks sends PKCE on every authorization request. Okta accepts PKCE on confidential web apps, so the **Require PKCE as additional verification** checkbox can be left either way. **4. Copy the client credentials** On the app's **General** tab, find the **Client Credentials** section and copy: * **Client ID** * **Client secret** (under *Client Secrets*) > [!NOTE] > > If **Client authentication** shows `Public client / PKCE only` rather than `Client secret`, the app was created as a SPA or native integration. Create a **Web Application** integration instead — Formbricks needs the secret. **5. Assign users or groups** * Open the app's **Assignments** tab. * Click **Assign → Assign to People** or **Assign to Groups**, and assign everyone who should be able to sign in to Formbricks. Okta rejects sign-in for anyone not assigned to the app, so skipping this step makes every login fail with *"User is not assigned to the client application"*. **6. Determine the issuer URL** Okta can mint tokens from two kinds of authorization server, and the issuer URL differs: | Authorization server | Issuer URL | | - | - | | **Org** | `https://your-org.okta.com` | | **Custom** | `https://your-org.okta.com/oauth2/your-auth-server-id` | The **org** authorization server works on every Okta plan and is the simpler choice. **Custom** authorization servers require API Access Management (integrator and developer orgs ship a `default` one); find their exact issuer under **Security → API → Authorization Servers**, in the **Issuer URI** column. > [!WARNING] > > Use your Okta **org** domain (`your-org.okta.com`, or your custom domain such as `login.example.com`) — never the Admin Console domain `your-org-admin.okta.com`. The latter hosts no OIDC discovery document. > [!NOTE] > > Verify the issuer by opening `{OIDC_ISSUER}/.well-known/openid-configuration` in your browser. It returns a JSON document with the OIDC endpoints. Formbricks builds that URL by appending to `OIDC_ISSUER`, so do not add a trailing slash. **7. Configure Formbricks environment variables** Add the following to your Formbricks `.env` file or `docker-compose.yml`: ```yml Formbricks Env for Okta OIDC theme={null} OIDC_CLIENT_ID=0oa1b2c3d4EXAMPLE5 OIDC_CLIENT_SECRET=your-client-secret-here OIDC_ISSUER=https://your-org.okta.com OIDC_DISPLAY_NAME="Okta" OIDC_SIGNING_ALGORITHM=RS256 ``` | Variable | Description | | - | - | | `OIDC_CLIENT_ID` | The **Client ID** from the app's General tab. | | `OIDC_CLIENT_SECRET` | The **Client secret** from the app's General tab. | | `OIDC_ISSUER` | Your Okta issuer URL (see the step above). | | `OIDC_DISPLAY_NAME` | The label shown on the Formbricks login button. | | `OIDC_SIGNING_ALGORITHM` | Optional. Okta signs with `RS256`, which is also the Formbricks default. | **8. Restart and test** * Restart your Formbricks instance. * The login page now shows a button labelled with your `OIDC_DISPLAY_NAME`. * Click it to authenticate through Okta. > [!NOTE] > > To disable email/password login entirely and force all users through Okta, set `EMAIL_AUTH_DISABLED=1`. This hides the email/password form on the login page. ## Automatic user provisioning By default, new SSO users must be invited by an organization admin before they can access Formbricks. To let Okta users join automatically and land in a team, add: ```yml Automatic User Provisioning theme={null} AUTH_SKIP_INVITE_FOR_SSO=1 AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here ``` | Variable | Description | | - | - | | `AUTH_SKIP_INVITE_FOR_SSO` | Set to `1` to let SSO users create an account without a manual invite. | | `AUTH_SSO_DEFAULT_TEAM_ID` | The ID of the team new SSO users are added to. The organization is derived from this team. | > [!WARNING] > > With `AUTH_SKIP_INVITE_FOR_SSO=1`, anyone Okta lets through the app integration gets a Formbricks account. Keep the app's **Assignments** scoped to the group that should have access. ### Finding your team ID 1. Log in to Formbricks as an admin. 2. Go to **Settings → Organization → Teams**. 3. Click **Manage Team** on the team you want to use as the default. 4. The Team ID is displayed in the modal. > [!NOTE] > > The Teams feature requires the **Role-Based Access Control (RBAC)** add-on on your Enterprise license. If you don't see the Teams section under **Settings → Organization**, contact [Formbricks support](mailto:support@formbricks.com) to enable it. ## Full configuration example ```yml Complete Okta OIDC Configuration theme={null} OIDC_CLIENT_ID=0oa1b2c3d4EXAMPLE5 OIDC_CLIENT_SECRET=your-client-secret-here OIDC_ISSUER=https://your-org.okta.com OIDC_DISPLAY_NAME="Okta" OIDC_SIGNING_ALGORITHM=RS256 AUTH_SKIP_INVITE_FOR_SSO=1 AUTH_SSO_DEFAULT_TEAM_ID=your-team-id-here # Optional: disable email/password login to force Okta-only authentication # EMAIL_AUTH_DISABLED=1 ``` ## Troubleshooting > [accordion] Okta shows 'The redirect\_uri parameter must be a Login redirect URI' > > The **Sign-in redirect URIs** entry on the Okta app does not match what Formbricks sends. It must be exactly `{WEBAPP_URL}/api/auth/oauth2/callback/openid` — same scheme and host, no trailing slash. > > If you're on v5.1 or earlier, the path is `{WEBAPP_URL}/api/auth/callback/openid` (without `/oauth2`) instead. > [accordion] Okta shows 'User is not assigned to the client application' > > The signed-in Okta user is not assigned to the app integration. Open the app's **Assignments** tab and assign the user, or the group they belong to. > [accordion] Sign-in fails and the logs mention discovery or the issuer > > Formbricks reads `{OIDC_ISSUER}/.well-known/openid-configuration`, so that URL must be reachable from the Formbricks server: > > ```bash theme={null} > curl https://your-org.okta.com/.well-known/openid-configuration > ``` > > * Check that `OIDC_ISSUER` has no trailing slash. > * Check that you used the org domain, not `your-org-admin.okta.com`. > * On a custom authorization server, the issuer includes the `/oauth2/...` path. > [accordion] Sign-in fails only on a custom authorization server > > A custom authorization server applies its own access policies and scopes; the org authorization server does not. > > * Under **Security → API → your server → Access Policies**, make sure a policy and rule cover the Formbricks app (or all clients). > * Under the **Scopes** tab, make sure `openid`, `profile` and `email` are present — Formbricks requests all three. > > If you don't need custom claims, pointing `OIDC_ISSUER` at the org authorization server (`https://your-org.okta.com`) avoids both. > [accordion] OIDC login button does not appear > > * Confirm that `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` and `OIDC_ISSUER` are all set. > * Ensure your Formbricks instance has a valid Enterprise license. > * Restart the Formbricks container after adding the environment variables. > [accordion] Users see 'No access to Workspaces' after login > > The user was added to the organization but not assigned to a team. Verify that: > > * `AUTH_SSO_DEFAULT_TEAM_ID` is set correctly (the env variable name is `AUTH_SSO_DEFAULT_TEAM_ID`, not `DEFAULT_TEAM_ID`). > * The Team ID is a valid cuid that exists in your database. > * The team is linked to a Workspace via **Workspace Teams** settings. # Open ID Connect Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/open-id-connect Configure Open ID Connect for secure Single Sign-On with your Formbricks instance. Implement enterprise-grade authentication for your survey platform with Open ID Connect. > [!NOTE] > > OpenID Connect is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) Integrating your own OIDC (OpenID Connect) instance with your Formbricks instance allows users to log in using their OIDC credentials, ensuring a secure and streamlined user experience. Please follow the steps below to set up OIDC for your Formbricks instance. * Configure your OIDC provider & get the following variables: * `OIDC_CLIENT_ID` * `OIDC_CLIENT_SECRET` * `OIDC_ISSUER` * `OIDC_SIGNING_ALGORITHM` > [!NOTE] > > Make sure the Redirect URI for your OIDC Client is set to > `{WEBAPP_URL}/api/auth/oauth2/callback/openid`. > [!NOTE] > > **Using Microsoft Entra ID?** Configure it through the dedicated [Azure AD > provider](/docs/self-hosting/configuration/auth-sso/azure-ad-oauth) rather than here — it maps Entra's > profile correctly. If you do point `OIDC_ISSUER` at a multi-tenant authority > (`login.microsoftonline.com/common` or `/organizations`), Formbricks skips OpenID discovery for it > and logs a warning at startup: those authorities advertise a placeholder issuer instead of a real > one, so id\_tokens cannot be verified against it and sign-in would otherwise fail. > [!NOTE] > > **Using Okta or Keycloak?** Both have step-by-step guides: > [Okta OIDC](/docs/self-hosting/configuration/auth-sso/okta-oidc) and > [Keycloak OIDC](/docs/self-hosting/configuration/auth-sso/keycloak-oidc). > [!WARNING] > > **Upgrading from v5.1 or earlier?** This path changed once, at v5.2: > > * v5.1 and earlier: `{WEBAPP_URL}/api/auth/callback/openid` > * v5.2 and later (current): `{WEBAPP_URL}/api/auth/oauth2/callback/openid` > > Upgrading from v5.2 or later needs no change — the callback URL is pinned and does not move with > Formbricks' authentication library. See the [migration guide](/docs/self-hosting/advanced/migration). * Update these environment variables in your `docker-compose.yml` or pass it directly to the running container. An example configuration for a FusionAuth OpenID Connect in Formbricks would look like: ```yml Formbricks Env for FusionAuth OIDC theme={null} OIDC_CLIENT_ID=59cada54-56d4-4aa8-a5e7-5823bbe0e5b7 OIDC_CLIENT_SECRET=4f4dwP0ZoOAqMW8fM9290A7uIS3E8Xg29xe1umhlB_s OIDC_ISSUER=http://localhost:9011 OIDC_DISPLAY_NAME=FusionAuth OIDC_SIGNING_ALGORITHM=HS256 ``` * Set an environment variable `OIDC_DISPLAY_NAME` to the display name of your OIDC provider. * Restart your Formbricks instance. * You're all set! Users can now sign up & log in using their OIDC credentials. # SAML SSO Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/saml-sso Configure SAML Single Sign-On (SSO) for secure enterprise authentication with your Formbricks instance. > [!NOTE] > > SAML SSO is part of the Formbricks [Enterprise Edition](/docs/self-hosting/advanced/license) ## Overview Formbricks supports SAML Single Sign-On (SSO) to enable secure, centralized authentication. With SAML, organizations can integrate their existing Identity Provider (IdP) infrastructure for streamlined access management. Formbricks internally uses BoxyHQ's SAML Jackson to manage SAML connections. SAML Jackson is a service provided by BoxyHQ that manages SAML connection details and validates assertions. It is part of the Formbricks server. To learn more about SAML Jackson, please refer to the [BoxyHQ SAML Jackson documentation](https://boxyhq.com/docs/jackson/deploy). ## How SAML works in Formbricks SAML (Security Assertion Markup Language) is an XML-based standard for exchanging authentication and authorization data between an Identity Provider (IdP) and Formbricks. Here's how the integration works with BoxyHQ Jackson embedded into the flow: 1. **Login Initiation:**\ The user clicks `Continue with SAML SSO` on Formbricks. 2. **Configuration Retrieval via BoxyHQ:**\ Formbricks requests the SAML connection details from BoxyHQ Jackson. BoxyHQ securely stores and manages the IdP configuration, including endpoints, certificates, and other metadata. 3. **Redirection:**\ With the configuration details from BoxyHQ, Formbricks redirects the user to the IdP’s login page (e.g., Okta). 4. **Authentication:**\ The user authenticates directly with the IdP. 5. **SAML Response:**\ Upon successful authentication, the IdP sends a signed SAML response back to Formbricks via the user’s browser. 6. **Validation via BoxyHQ:**\ BoxyHQ Jackson validates the SAML assertion—verifying the signature and extracting user details—before sending the validated data back to Formbricks. 7. **Access Granted:**\ Formbricks logs the user in using the verified information. ## SAML Auth Flow Sequence Diagram Below is a sequence diagram illustrating the complete SAML authentication flow with BoxyHQ Jackson integrated: ```mermaid theme={null} sequenceDiagram participant U as User participant FB as Formbricks (SP) participant BHQ as BoxyHQ Jackson participant OK as Okta (IdP) Note over FB,BHQ: (Setup phase, done beforehand)
1. Admin configures SAML metadata in Formbricks
2. BoxyHQ stores & manages SAML connection details U->>FB: Clicks “Continue with SAML SSO" FB->>BHQ: Request SAML connection details BHQ->>FB: Returns SAML configuration (IdP info) FB->>OK: Redirect user to Okta (SAML Auth Request) OK->>U: Prompts user for credentials U->>OK: Submits credentials OK->>FB: Sends SAML Assertion (Callback URL) FB->>BHQ: Validates assertion & extracts user info BHQ->>FB: Returns validated user data FB->>U: Logs user into Formbricks ``` ## Setting Up SAML SSO To configure SAML SSO in Formbricks, follow these steps: **1. Database Setup** Configure a dedicated database for SAML by setting the `SAML_DATABASE_URL` environment variable in your `docker-compose.yml` file (e.g., `postgres://postgres:postgres@postgres:5432/formbricks-saml`). If you're using a self-signed certificate for Postgres, include the `sslmode=disable` parameter. **2. IdP Application** Create a SAML application in your IdP by following your provider's instructions. See [SAML with Identity Providers](/docs/self-hosting/configuration/auth-sso/setup-saml-with-identity-providers) for the values Formbricks expects. **3. User Provisioning** Provision users in your IdP and configure access to the IdP SAML app for all your users (who need access to Formbricks). **4. Metadata** Keep the XML metadata from your IdP handy for the next step. **5. Metadata Setup** Create a file called `connection.xml` in your self-hosted Formbricks instance's `formbricks/saml-connection` (use `formbricks/apps/web/saml-connection` for development) directory and paste the XML metadata from your IdP into it. Please create the directory if it doesn't exist. Your metadata file should start with a tag like this: `<...>` or ``. Please remove any extra text from the metadata. **6. Restart Formbricks** Restart Formbricks to apply the changes. You can do this by running `docker compose down` and then `docker compose up -d`. > [!NOTE] > > We don't support multiple SAML connections yet. You can only have one SAML connection at a time. If you > change the `connection.xml` file, your existing SAML connection will be overwritten. # SAML with Identity Providers Source: https://formbricks.com/docs/self-hosting/configuration/auth-sso/setup-saml-with-identity-providers This guide explains the settings you need to use to configure SAML with your Identity Provider. Once configured, obtain an XML metadata file and use it to configure SAML in Formbricks. ## SAML registration with identity providers This guide explains the settings you need to use to configure SAML with your Identity Provider. Once configured, obtain an XML metadata file and use it to configure SAML in Formbricks. > **Note:** Please do not add a trailing slash at the end of the URLs. Create them exactly as shown below. **Assertion consumer service URL / Single Sign-On URL / Destination URL:** [https://app.formbricks.com/api/auth/saml/callback](https://app.formbricks.com/api/auth/saml/callback) **Entity ID / Identifier / Audience URI / Audience Restriction:** [https://saml.formbricks.com](https://saml.formbricks.com) > **Note:** [https://saml.formbricks.com](https://saml.formbricks.com) is hardcoded in Formbricks — do not replace it with your instance URL. It is the fixed SP Entity ID and must match exactly as shown in SAML assertions. **Response:** Signed **Assertion Signature:** Signed **Signature Algorithm:** RSA-SHA256 **Assertion Encryption:** Unencrypted **NameID Format:** EmailAddress **Application username:** email **Mapping Attributes / Attribute Statements:** * Name claim: If your IdP has a `name` claim, set the following claims to populate the name field: | Name | Name Format | Value | | - | - | - | | name | Basic | user.name | Many IdPs do not have a `name` claim. If not, you can use different claims to populate the name field. The order of precedence is `name` -> **other options** -> `email`. **Other options:** | Name | Name Format | Value | | - | - | - | | firstName | Basic | **FIRST\_NAME\_EQUIVALENT** | | lastName | Basic | **LAST\_NAME\_EQUIVALENT** | Refer to the table below for the different claims you can use for each IdP. | IdP | FIRST\_NAME\_EQUIVALENT | LAST\_NAME\_EQUIVALENT | | - | - | - | | Okta | user.firstName | user.lastName | | Microsoft Entra ID (Azure AD) | user.givenName | user.surname | | Google Workspace | user.given\_name / user.firstName | user.family\_name / user.lastName | | OneLogin | user.FirstName / user.first\_name | user.LastName / user.last\_name | | Auth0 | user.given\_name | user.family\_name | | JumpCloud | user.firstname | user.lastname | Above provided claims may differ based on your configuration and the IdP you are using. Please refer to the documentation of your IdP for the correct claims. ## SAML with Okta > [!NOTE] > > Okta also supports OpenID Connect, which needs no XML metadata file on the Formbricks side. See > [Okta OIDC](/docs/self-hosting/configuration/auth-sso/okta-oidc). **1. Create an application with your SAML provider** For example, in Okta, once you create an account, you can click on Applications on the sidebar menu: ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/okta-applications.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=b819ea31ace6ee96d0b69b329cf5c533) **2. Click on Create App Integration** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/create-app-integration.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=7fb1ad7cad43a945f1914a67370d61e5) **3. Select SAML 2.0 in the modal form, and click Next** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/select-saml-2.0.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=6872c92105e78444e22b5abd17232a62) **4. Fill the general settings as shown and click Next** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/general-settings.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=fd24382ae1668ba2920a7d343f4d837c) **5. Enter the SAML Integration Settings as shown and click Next** * **Single Sign-On URL**: `https:///api/auth/saml/callback` or `http://localhost:3000/api/auth/saml/callback` (if you are running Formbricks locally) * **Audience URI (SP Entity ID)**: `https://saml.formbricks.com` (hardcoded; do not replace with your instance URL) ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/saml-integration-settings.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=f14a3d8a1c85fdc7f1457f5df10c9c6e) **6. Fill the fields mapping as shown and click Next** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/fields-mapping.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=7a2932e37d4db6b660e8eb8d7463396a) **7. Check the internal app checkbox and click Finish** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/internal-app.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=859716e58c391c65f7a5518c10816f39) **8. Check that the app is created successfully** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/app-created.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=f4e607c5ff977413ef9581681f332bd3) **9. Click on the app and head over to the Assignments tab** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/assignments-tab.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=d2f9bd8223b1760719996154ad5b7f3d) **10. Click on Assign button and select Assign to People** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/assign-to-people.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=9e85ba2a6fcdad77f90931f67f141d3e) **11. Select the users you want to assign the app to and click Assign** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/select-users.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=a9e011d2a91055368f9af04078239855) **12. Head over to the Sign On tab and click on the 'view SAML setup instructions' button** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/view-saml-instructions.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=8fb0116b85f57d808fdb66965588211d) **13. Scroll to the bottom and copy the IDP metadata** ![](https://mintcdn.com/formbricks/AluoV1JcINmbRAK1/images/self-hosting/configuration/auth-sso/okta/idp-metadata.webp?fit=max\&auto=format\&n=AluoV1JcINmbRAK1\&q=85\&s=31f731c7f6ca8a317123ffd506f20079) **14. Copy the IDP metadata and paste it in the `connection.xml` file in the `formbricks/saml-connection` (use `formbricks/apps/web/saml-connection` for development) directory** That's it. Now when you try to login with SSO, your application on Okta will handle the authentication. # SpiceDB Authorization Operations Source: https://formbricks.com/docs/self-hosting/configuration/authzed-operations Configure, monitor, back up, and repair the SpiceDB authorization dependency used by Formbricks. Formbricks uses [SpiceDB](https://authzed.com/docs/spicedb), maintained by AuthZed, to store a relationship graph for authorization. PostgreSQL remains the source of truth. Formbricks projects membership, team, workspace, and API-key changes into SpiceDB after their PostgreSQL transaction commits. Existing environment variables and operator commands keep the `AUTHZED_` prefix for compatibility. > [!NOTE] > > Formbricks v6 makes SpiceDB the sole authorization decision engine and has no runtime legacy fallback. > PostgreSQL remains the relationship source of truth, with durable outbox delivery into SpiceDB. Existing > installations must complete the release-matched preparation and read-only gate before upgrading; a healthy > connection alone is not sufficient. > [!WARNING] > > Treat SpiceDB as a private infrastructure dependency. Do not publish its gRPC port through an Ingress, > reverse proxy, load balancer, or public Docker port. ## Understand the dependency | Component | Responsibility | | - | - | | Formbricks PostgreSQL | Authoritative organizations, memberships, teams, workspaces, and API-key scopes | | SpiceDB PostgreSQL datastore | Persistent SpiceDB schema, relationships, and revisions | | SpiceDB | Evaluates the relationship graph | | Formbricks projection layer | Copies committed PostgreSQL authorization changes into SpiceDB | | Formbricks operator commands | Check health and schema state, then audit or repair relationship drift | Formbricks writes projection intent in the same PostgreSQL transaction as the source mutation. BullMQ wakes the delivery worker, but PostgreSQL is the durable queue. A failed delivery is retried idempotently and a stale or dead-lettered revocation makes protected operations fail closed. A six-hour audit repairs attributable missing or mismatched edges; operators must investigate state that cannot be repaired safely. The v6 server validates required AuthZed configuration before accepting requests, without making an RPC. The general Formbricks `/health` endpoint, application startup, and Kubernetes readiness and liveness probes do not depend on SpiceDB connectivity. This prevents a SpiceDB outage from restarting unrelated Formbricks workloads. It also means `/health` alone cannot prove that authorization data is healthy. There is no browser health or administration page. Use the release-matched operator commands below. ## Configure SpiceDB | Variable | Purpose | Default | | - | - | - | | `AUTHZED_ENABLED` | Enables the required AuthZed authorization engine | `true` in bundled Docker and Helm | | `AUTHZED_ENDPOINT` | Bare gRPC `host:port` endpoint | `spicedb:50051` in Docker | | `AUTHZED_TOKEN` | SpiceDB preshared authentication token | No default | | `AUTHZED_SYSTEM_KEY` | Stable Formbricks authorization namespace identifier | `formbricks` | | `AUTHZED_INSECURE` | Uses plaintext gRPC when enabled | `true` for bundled Docker and chart-managed SpiceDB | | `AUTHZED_CONSISTENCY` | Authorization read consistency | `fully_consistent` | | `AUTHZED_DATABASE_PASSWORD` | Password for Docker's dedicated `spicedb` PostgreSQL role | No default | | `SPICEDB_IMAGE_REF` | Reviewed override used by both Docker migration and server services | `authzed/spicedb:v1.52.0` | `AUTHZED_ENABLED` and `AUTHZED_INSECURE` accept `true`, `false`, `1`, and `0`. The endpoint must contain an explicit port and no scheme, path, query, credentials, or whitespace. Examples include `spicedb:50051`, `grpc.authzed.com:443`, and `[::1]:50051`. Use `AUTHZED_INSECURE=false` for AuthZed Cloud or any endpoint outside a trusted private network. Plaintext gRPC transmits the preshared token without TLS protection. Changing AuthZed configuration requires restarting the Formbricks process. Generate independent credentials with: ```bash theme={null} openssl rand -hex 32 # AUTHZED_TOKEN openssl rand -hex 32 # AUTHZED_DATABASE_PASSWORD for bundled Docker ``` Store them in a mode-`0600` `.env`, Docker secret, Kubernetes Secret, or external secret manager. Never put the token in a `NEXT_PUBLIC_*` variable, command output, documentation, or source control. See [Environment Variables](/docs/self-hosting/configuration/environment-variables#authzed--spicedb-authorization) for the complete validation contract. ## Operate Docker and one-click installations The released Compose stack runs one SpiceDB instance using a dedicated `spicedb` database and login in the bundled PostgreSQL container. Startup is ordered as follows: ```text theme={null} postgres → authzed-db-bootstrap → spicedb-migrate → spicedb postgres → formbricks-migrate spicedb + formbricks-migrate → authzed-initialize ``` Database bootstrap and datastore migration are idempotent. Migration and serving always use the same `SPICEDB_IMAGE_REF`. SpiceDB is reachable only as `spicedb:50051` inside the Compose network. `authzed-initialize` is an idempotent, one-shot service that prepares fresh installations. Formbricks does not depend on it, so application startup and `/health` remain independent from SpiceDB. The `authzed-ops` profile is a short-lived operator container using the same release image and never starts during a normal Compose run. ```bash theme={null} docker compose --profile authzed-ops run --rm authzed-ops health docker compose --profile authzed-ops run --rm authzed-ops schema check docker compose --profile authzed-ops run --rm authzed-ops backfill docker compose --profile authzed-ops run --rm authzed-ops upgrade check ``` Fresh one-click installations generate `AUTHZED_TOKEN` and `AUTHZED_DATABASE_PASSWORD`, prepare the graph, and run the read-only gate before reporting success. The update command preserves customized Compose files. An older installation must merge the released AuthZed services and environment manually, then explicitly acknowledge the v6 migration. The updater runs only the read-only `upgrade check` before stopping the existing application. A blocked check leaves it running. After a successful check, the updater stops the stack, waits for PostgreSQL, runs application migrations, and starts the new stack only if they succeed. Preparation is a separate [maintenance operation](/docs/self-hosting/advanced/v6-maintenance-upgrade), including for later schema-changing releases. > [!WARNING] > > `docker compose down` preserves PostgreSQL data. `docker compose down -v` deletes the volume containing both > the Formbricks and SpiceDB databases. Do not use `-v` during an upgrade or incident response. The bundled PostgreSQL service leaves `track_commit_timestamp=off`, so the SpiceDB Watch API is disabled. This does not affect schema operations, relationship projection, permission checks, or the repair workflow. ## Operate Kubernetes and Helm installations The Formbricks chart supports two modes: * `authzed.mode=selfHosted` creates a `SpiceDBCluster` and points Formbricks at its private Kubernetes Service. * `authzed.mode=external` configures the Formbricks client for AuthZed Cloud or another external SpiceDB. For a chart-managed cluster: ```yaml theme={null} authzed: mode: selfHosted operator: install: true ``` Install only one SpiceDB operator per Kubernetes cluster. If a platform operator already watches the Formbricks namespace, set `authzed.operator.install=false`. Apply the matching SpiceDB CRDs before upgrading the operator because Helm does not upgrade CRDs during a normal release upgrade. Production deployments should use a dedicated PostgreSQL database and role. Provide a Secret containing `datastore_uri` and `preshared_key`, then reference it through `authzed.datastore.existingSecret` and `authzed.auth.existingSecret`. Require `sslmode=require`, `verify-ca`, or `verify-full` for managed PostgreSQL. ### Bootstrap the SpiceDB role and database A short-lived Job creates the dedicated `spicedb` role and database before SpiceDB starts. It creates each only when it is absent, so re-running it against an already initialised database is safe — but not inert: the role's password is reconciled to the chart's Secret on every run. Rotate that password outside Helm and the next upgrade will set it back, so update the Secret alongside it. By default it connects as the `postgres` superuser the bundled PostgreSQL subchart creates. **An existing PostgreSQL installed with `postgresql.auth.enablePostgresUser=false` has no such role**, and the upgrade fails until the Job is told which role to use instead: ```yaml theme={null} authzed: bundledPostgresqlBootstrap: adminUsername: fbadmin adminDatabase: formbricks # maintenance database to attach to adminPasswordSecretName: existing-pg-admin adminPasswordKey: password ``` The role needs `CREATEROLE` and `CREATEDB`; it does not need to be a superuser. `adminPasswordSecretName` is required whenever `adminUsername` is overridden, and `adminPasswordKey` whenever that Secret is configured explicitly. **Both are checked while the chart renders**, so omitting one fails the render with the missing value named — no Job is created. Without those guards the first would silently fall back to the bundled admin password and the second would look up the subchart's key name inside your own Secret, and neither shows up until the Pod fails to start in the cluster. > [!NOTE] > > `CREATEROLE` and `CREATEDB` are sufficient on their own only when the administrator also creates the > `spicedb` role — which is the normal case, including on re-runs. `CREATE DATABASE ... OWNER spicedb` > additionally requires the administrator to be able to `SET ROLE` to that owner, so the Job grants itself the > `spicedb` role before creating the database. From PostgreSQL 16 that grant is only possible for a role the > administrator holds `ADMIN OPTION` on, which it gets automatically by creating it. > > The one case this cannot repair is a `spicedb` role that already exists and was created by *someone else*, > on PostgreSQL 16 or newer: the administrator then holds no `ADMIN OPTION` on it and the Job fails rather than > silently skipping work. Grant it explicitly — `GRANT spicedb TO fbadmin WITH ADMIN OPTION` as a superuser or > as the role's owner — or run the bootstrap as a superuser once. PostgreSQL 15 and older are unaffected: > `CREATEROLE` there carries authority over every non-superuser role. Rendering fails fast with the three available remedies named — configure an administrative role, enable `postgresql.auth.enablePostgresUser`, or set `authzed.bundledPostgresqlBootstrap.enabled=false` — rather than letting the Job fail inside the cluster. Disabling bootstrap remains the correct choice when the role and database are provisioned by hand or by a platform team; the SpiceDB `datastore_uri` must then already point at them. For an externally managed PostgreSQL server, use `authzed.externalPostgresqlBootstrap` instead, which takes a full administrator URL from a Secret and enforces TLS on it. For an external AuthZed endpoint: ```yaml theme={null} authzed: mode: external operator: install: false endpoint: grpc.authzed.com:443 insecure: false auth: existingSecret: formbricks-authzed ``` AuthZed and `fully_consistent` authorization are enabled by default. The operator runs SpiceDB datastore migrations. A fresh Helm installation runs a release-matched, aggregate-only initialization Job after the datastore and Formbricks migrations become available. Application startup and probes do not depend on this Job. For existing releases, the pre-upgrade hook is read-only. Prepare schema and relationship changes explicitly before the upgrade; the hook only runs `upgrade check`. The release notes print the exact deployment command. With the default release: ```bash theme={null} kubectl exec -n formbricks deployment/formbricks -- formbricks-authzed health kubectl exec -n formbricks deployment/formbricks -- formbricks-authzed schema check kubectl exec -n formbricks deployment/formbricks -- formbricks-authzed backfill kubectl exec -n formbricks deployment/formbricks -- formbricks-authzed upgrade check ``` Replace the namespace and deployment name if you override them. These commands execute inside the existing application pod and do not require exposing PostgreSQL or SpiceDB. ## Upgrade an existing installation to v6 Formbricks v6 has no legacy authorization fallback. Follow the [maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade): stop all writers and controllers, take recoverable backups, and run the target release's database migrations before preparing its graph. A bridge release is not required for the self-hosted maintenance path. The release-matched preparation command coordinates migrations and these existing operations; advanced operators can also run them explicitly while maintenance remains active: ```bash theme={null} formbricks-authzed upgrade prepare formbricks-authzed upgrade check ``` `prepare` verifies configuration and datastore readiness, applies an empty or already-matching canonical schema, drains the outbox, reconciles attributable relationships, and runs a final audit. If the remote schema is non-empty and differs, first run `schema check`, review the diff and backup, then pass its exact `remoteDigest`: ```bash theme={null} formbricks-authzed upgrade prepare \ --expected-current-digest sha256: ``` `check` is read-only. It exits `0` only when AuthZed is enabled with `fully_consistent`, authenticated health is good, the canonical schema matches, the outbox has no pending or dead-lettered work, no revocation has crossed a warning threshold, and a complete dry-run relationship audit is clean. Exit `2` means the release remains blocked; exit `1` means configuration or an operation failed. Output contains only aggregate counters and stable error codes. For one-click, set `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true` in `.env` only after those commands pass. For Helm, set `authzed.migrationAcknowledged=true` only in the v6 upgrade values. The chart refuses an upgrade without it and refuses `authzed.enabled=false` or consistency weaker than `fully_consistent`. ## Activate or upgrade SpiceDB Use the following sequence for a new deployment, schema change, SpiceDB version change, or datastore restore. **1. Back up both datastores** Create a PostgreSQL-consistent backup of the Formbricks database and the dedicated `spicedb` database. Record the deployed Formbricks and SpiceDB versions, configuration, and schema digest. **2. Complete datastore migrations** Deploy the reviewed SpiceDB version and wait for `spicedb datastore migrate head` to complete before the new SpiceDB server starts. Never run migration and serving from different image references. **3. Check connectivity** ```bash theme={null} formbricks-authzed health ``` A healthy command exits `0`. Disabled or unhealthy results exit `1`. **4. Check and apply the schema** ```bash theme={null} formbricks-authzed schema check ``` A match exits `0`, drift exits `2`, and an operational failure exits `1`. Initialize an empty SpiceDB with: ```bash theme={null} formbricks-authzed schema apply ``` Replacing a non-empty schema requires the `remoteDigest` returned by the immediately preceding check: ```bash theme={null} formbricks-authzed schema apply \ --expected-current-digest sha256: ``` Ensure no other schema writer runs between check and apply. SpiceDB does not provide an atomic schema compare-and-swap operation. **5. Audit and reconcile relationships** ```bash theme={null} formbricks-authzed backfill formbricks-authzed backfill --apply ``` Require a clean result before relying on SpiceDB authorization decisions. **6. Run the release gate** ```bash theme={null} formbricks-authzed upgrade check ``` Do not start a direct-authority release unless this exits `0`. **7. Restart and observe** Restart Formbricks after environment changes. Recheck AuthZed health, schema status, projection metrics, retry metrics, and SpiceDB logs. The Docker examples use the `docker compose --profile authzed-ops run --rm authzed-ops` prefix. Kubernetes examples use `kubectl exec ... --`. The command names and arguments after those prefixes are identical. ### Roll back a v6 upgrade Keep the original v5 images, configuration, coordinated backups, and schema digest until acceptance is complete. After database migrations, restoring an old image or running `helm rollback` alone may be incompatible with the database. Keep maintenance active and either fix forward or restore the matching backups and v5 configuration. Do not disable AuthZed inside v6. See the [recovery steps](/docs/self-hosting/advanced/v6-maintenance-upgrade#results-and-recovery). Use explicit release versions and image digests for this upgrade. Do not rely on a moving `latest` or `stable` tag to perform the migration or to provide a tested rollback artifact. ## Back up and restore Back up the following together: * the authoritative Formbricks PostgreSQL database; * the dedicated `spicedb` PostgreSQL database; * AuthZed and datastore credentials in your secret manager; * the deployed Formbricks and SpiceDB image versions; * Compose or Helm configuration; and * the schema digest reported by `schema check`. For bundled Docker PostgreSQL: ```bash theme={null} umask 077 docker compose exec -T postgres pg_dump -U postgres -d formbricks > formbricks.sql docker compose exec -T postgres pg_dump -U postgres -d spicedb > spicedb.sql ``` Use your managed PostgreSQL provider's consistent snapshot mechanism for external databases. Define retention, restore testing, RPO, and RTO according to your operating requirements. There are two supported recovery approaches: 1. Restore coordinated Formbricks and SpiceDB database backups from the same recovery point. 2. Restore Formbricks PostgreSQL, initialize an empty compatible SpiceDB datastore, apply the release-matched schema, and rebuild the relationship graph with a full applying backfill. After either restore, complete datastore migrations, check health, check the schema, and run a full relationship audit. Do not rely on SpiceDB-backed authorization until the audit is clean. An older SpiceDB backup can be repaired from PostgreSQL; a SpiceDB database restored without its matching Formbricks source must never be assumed current. AuthZed Cloud owns datastore backup and restore guarantees. You still need Formbricks PostgreSQL backups, recoverable client credentials, release configuration, schema verification, and the relationship repair procedure. ## Inspect and drain durable delivery The v6 projection layer writes projection intent in the same PostgreSQL transaction as an authorization source change. BullMQ wakes the delivery worker, but PostgreSQL remains the durable queue. Deletes, and updates that are not provably grants, are treated as revocations; direct authority fails closed when a revocation remains unresolved for 60 seconds or enters dead letter. ```bash theme={null} formbricks-authzed outbox status formbricks-authzed outbox drain formbricks-authzed outbox drain --max-batches=500 formbricks-authzed outbox replay ``` `status` prints aggregate queue counts and ages only. It exits `0` when healthy, `2` at the 15-second warning or 45-second critical thresholds (and for any dead letter), and `1` for an operational failure. `drain` processes revocations first and stops at the first batch that delivers nothing; a partially delivered batch is normal, because a failure is charged only to the events it is attributable to. `replay` resets unresolved dead letters so the normal idempotent reconcilers can retry them; investigate the cause before replaying. Dead-lettering requires ten solitary failures carrying a code an event can actually cause, so no SpiceDB outage — unreachable, rejected credential or internal error — produces one, and a dead letter always means PostgreSQL and SpiceDB genuinely disagree. The six-hour audit replays dead letters on its own after a clean run, which bounds a fail-closed denial at six hours. These results contain no source IDs, relationship strings, credentials, or raw errors. This is different from the detailed backfill report below, which intentionally contains operational identifiers. ### Recovery after a Redis outage Delivery does not depend on Redis staying up. Every web process that runs jobs also checks PostgreSQL every 10 seconds for events that have been ready to deliver for 15 seconds without being picked up. Healthy delivery never leaves an event that long. When it finds one, it drains the outbox the same way `outbox drain` does and logs a warning (`operation: "projection_outbox_safety_net"`). A stalled BullMQ worker, such as one left idle after a Redis or DNS outage, therefore no longer needs an operator: an undelivered revocation is delivered within about 25 seconds, before the 60-second guard trips. Replicas can run this check at the same time, because delivery claims events with leases, so nothing is delivered twice or lost. The safety net does not hide a real problem: * It never touches dead letters, so a dead-lettered revocation keeps the guard armed until you fix its cause and replay it. * An event that failed waits out its retry backoff first, so a SpiceDB outage is not retried any faster. * It only drains when there is overdue work, so it adds one indexed query every 10 seconds and nothing more. Treat repeated `projection_outbox_safety_net` warnings as a sign that the BullMQ delivery job is not running. Check the worker logs and Redis connectivity, and restart the web pods if needed. When the guard arms, each process logs one `authzed_projection_stale` error with a `hint` that names the commands above, and one warning when it clears. If the guard stays armed: 1. Run `formbricks-authzed outbox status`. Pending overdue revocations with no dead letters mean delivery is not running. Dead letters mean specific events could not be delivered. 2. Run `formbricks-authzed health` to confirm SpiceDB is reachable. 3. For dead letters, read each one's `lastErrorCode` first, with the query under [Audit and repair surveys](#audit-and-repair-surveys). SpiceDB may have rejected the event, or Formbricks may not recognise its target type (`authzed_projection_invalid_event`). Fix the cause, then run `formbricks-authzed outbox replay`; replaying without a fix only dead-letters the event again. `drain` never claims a dead letter. 4. Run `formbricks-authzed outbox drain`, then `formbricks-authzed upgrade check`, and expect `status: ready`. Every six hours Formbricks also runs a full applying audit without prune. It automatically repairs attributable missing and mismatched-permission relationships. It never deletes orphaned or unmanaged data and never repairs a mismatched parent automatically. ## Audit and repair relationships The command prints one JSON result. It never prints credentials, database passwords, raw SDK errors, schema text, or raw relationship strings. It does print identifiers, deliberately: naming the affected records is what makes a drift report actionable. Most are Formbricks record IDs, but not all — `unmanaged` can surface object IDs belonging to no Formbricks record at all. Treat the result as sensitive operational data. * `orphans`, `mismatchedParents` and `mismatchedPermissions` name the records that disagree, carrying organization, user, workspace, team, API-key, feedback-directory and feedback-directory-assignment IDs. `mismatchedPermissions` adds the expected and observed relation names alongside the record it names. * `unmanaged` reports relationships outside the managed vocabulary as an object type, an object ID and a relation name. Those object IDs are not limited to the kinds above — anything else sharing the SpiceDB instance appears here. * `failures` carries an organization ID for each failed unit that has one, so even a failed run emits identifiers. It is empty when the read that would have identified the organization is what failed. * `lastOrganizationId` is the resume cursor: the last organization the sweep reached, or `null` if it reached none. The cursor is an intentional operational identifier, not an oversight. An interrupted sweep resumes with `--after-organization-id=` taken straight from it, so an opaque token would have to be stored and mapped back somewhere to stay useful. It is also the one field that can name an organization with nothing wrong: every other identifier here comes from a record or relationship that drifted or failed, while the cursor is simply wherever the sweep stopped. Redact it on the same terms as the rest. > [!WARNING] > > Handle the result like a database export, not like a log line. Store it in the same place you keep other > sensitive operational output, restrict access to operators, and delete it once the drift it describes is > resolved — retain it no longer than your incident records. Do not paste it into shared chat, ticket > descriptions, or support bundles without redacting the identifier fields above. Redirecting to a file keeps the result out of terminal scrollback and out of CI logs that capture stdout. Set `umask 077` and remove any earlier export first. The umask governs file *creation* only, so under a typical `umask 022` a new `backfill.json` lands world-readable — and redirecting over one that already exists truncates it while leaving its existing mode untouched: ```bash theme={null} umask 077 rm -f backfill.json formbricks-authzed backfill > backfill.json ``` Redirection does not keep identifiers out of your shell history, which records the command rather than its output — and the resume invocation is the one to watch there, because the cursor is an argument: `--after-organization-id=` is recorded verbatim. On a shared or session-recorded host, read the cursor from the saved result instead of retyping it. ### Interpret exit codes | Exit code | Meaning | | - | - | | `0` | Every observed drift category is clean or was reconciled | | `1` | Invalid command, configuration failure, or operational failure | | `2` | Drift remains and operator action is required | ### Start with a dry run ```bash theme={null} formbricks-authzed backfill formbricks-authzed backfill --organization-id= formbricks-authzed backfill --workspace-id= ``` An organization or workspace run limits the repair blast radius, but reports `orphanScope: "known_resources"`. Only a complete deployment sweep can find relationships for resources that no longer exist in PostgreSQL or parent edges pointing from another tenant's resource. ### Reconcile PostgreSQL state ```bash theme={null} formbricks-authzed backfill --apply formbricks-authzed backfill --apply --organization-id= formbricks-authzed backfill --apply --workspace-id= ``` Applying fixes missing and incorrect current-state relationships. It does not remove relationships with no remaining PostgreSQL source record. If a sweep is interrupted, resume after the reported `lastOrganizationId`. A `null` cursor means the run reached no organization, so there is nothing to resume after — rerun the sweep from the start instead: ```bash theme={null} formbricks-authzed backfill --apply --after-organization-id= ``` The cursor advances past every organization the sweep reached, and an organization-specific failure does not stop the sweep — so each failure carrying a non-empty `organizationId` sits behind the cursor, and a resume will not retry it. Rerun those explicitly, in addition to resuming from the cursor: ```bash theme={null} formbricks-authzed backfill --apply --organization-id= ``` A failure with an **empty** `organizationId` is not one of those: the read that would have identified the organization is itself what failed, so there is nothing to target. Within a sweep those also set `truncated` — rerun the sweep rather than a single organization. ### Prune orphans Pruning is the only mode that removes relationships observed only in SpiceDB. It requires every safeguard: ```bash theme={null} formbricks-authzed backfill --apply --prune --confirm-prune \ --scope=all \ --expected-endpoint= ``` Use `--organization-id` or `--workspace-id` instead of `--scope=all` when the known problem permits a narrower repair. A complete prune requires a SpiceDB datastore dedicated to one Formbricks deployment because object IDs are not currently namespaced by `AUTHZED_SYSTEM_KEY`. The default destructive cap is 500 orphaned resources. `--max-prune=` may lower but never raise it. If the run observes more than the cap, it deletes nothing. Investigate a wrong endpoint, wrong database, partial restore, or shared SpiceDB before proceeding. ### Audit and repair surveys Surveys are audited and repaired as their own scope, never as part of `--scope=all`, so the six-hourly audit stays proportional to your number of grants rather than your number of surveys. A daily job audits them as a dry run and reports drift through metrics. ```bash theme={null} formbricks-authzed backfill --scope=survey formbricks-authzed backfill --scope=survey --apply formbricks-authzed backfill --scope=survey --apply --after-survey-id= ``` > [!NOTE] > > Once the marker is set, every survey a person creates starts **Restricted** to its author and the > organization's owners and managers. They can make it visible to the workspace from **Collaborate** or > when activating it. See [Survey visibility](/docs/surveys/general-features/visibility). Stored survey visibility is always enforced. Marking the survey scope ready runs the repair, then two further dry runs, and sets the marker only if both come back clean: ```bash theme={null} formbricks-authzed backfill --scope=survey --apply --mark-ready ``` To pause visibility mutations and use PostgreSQL policy plus workspace authorization while repairing the graph, clear the marker. Stored restrictions remain enforced: ```bash theme={null} formbricks-authzed backfill --scope=survey --clear-ready ``` `formbricks-authzed upgrade check` reports the marker as `scopes.survey`. After upgrading to the release that adds survey visibility, and once every Formbricks container or pod runs the new version, check durable delivery and replay any dead letters: ```bash theme={null} formbricks-authzed outbox status formbricks-authzed outbox replay formbricks-authzed outbox drain ``` The database migration adds the survey trigger while containers of the previous version may still be delivering outbox events. Those do not know survey events yet and dead-letter them on the spot instead of retrying. A dead-lettered survey revocation makes every enforced authorization check fail closed until it is replayed, so do not wait for the scheduled audit. Run `replay` only after the rollout has finished, since an old container would dead-letter the event again. `replay` resets every unresolved dead letter, and `status` only counts them, so check what they are first: ```sql theme={null} SELECT "targetType", "lastErrorCode", COUNT(*) FROM "AuthzedProjectionOutbox" WHERE "deadLetteredAt" IS NOT NULL AND "processedAt" IS NULL GROUP BY 1, 2; ``` Expect `survey` rows with `authzed_projection_invalid_event`; investigate anything else before replaying. > [!WARNING] > > `SURVEY_VISIBILITY_FORCE_DISABLED=1` suppresses visibility mutations. It never releases stored > restrictions or bypasses PostgreSQL or SpiceDB failures. Clearing survey readiness selects > PostgreSQL visibility policy plus workspace authorization until the graph is ready again. ### Interpret drift categories | Category | Meaning and response | | - | - | | `missing` | PostgreSQL contains a source record without the expected SpiceDB relationship. An applying run repairs it. | | `mismatchedPermissions` | An existing source record's projected role or grant relation differs from PostgreSQL. An applying run repairs it deterministically. | | `orphaned` | SpiceDB contains a managed relationship whose source record is gone. A confirmed prune removes it. | | `invalid` | PostgreSQL contains a cross-organization source row. Investigate and correct PostgreSQL manually. | | `unmanaged` | A relationship outside Formbricks' managed vocabulary exists. Investigate its writer; the tool never deletes it. | | `mismatchedParents` | A resource points to an organization PostgreSQL does not identify as its owner. Treat this as a possible cross-tenant privilege escalation. | | `failures` | One or more units failed. Use the stable code and attempt count, correct the cause, and rerun. | | `truncated` | Observation did not produce a complete, exact result. Do not prune or declare the graph clean; rerun. | > [!WARNING] > > Never automatically repair `mismatchedParents`. Confirm the authoritative owner and inspect the reported > relation direction before deleting an edge. A wrong parent edge can grant another tenant's owners and > managers access to the resource. ## Diagnose failures | Result or symptom | Meaning | Operator response | | - | - | - | | Missing AuthZed configuration at startup | Required v6 settings are absent, disabled, or use weaker consistency | Set the five required client settings, retain the appropriate TLS mode, and restart; there is no legacy fallback | | `authzed_disabled` in a diagnostic CLI | That command loaded disabled client configuration | Configure the required v6 client settings before starting the server | | `authzed_unauthenticated` or `authzed_permission_denied` during health/schema operations | Token rejected or lacks the required API capability | Verify the secret reference and coordinated token configuration without printing the token | | `authzed_timeout` | An attempt exceeded its deadline | Check network latency, datastore saturation, and SpiceDB load | | `authzed_overloaded` | SpiceDB reported resource exhaustion | Inspect datastore connections, dispatch, cache, CPU, and memory | | `authzed_unavailable` | SpiceDB or its network path is unavailable | Restore the service, verify health, then run a full relationship audit | | `authzed_internal` | Unexpected client or runtime failure | Check sanitized Formbricks and SpiceDB logs and the deployed version | | Schema status `drifted` | Connected schema differs from this Formbricks release | Back up first, review the diff counts and digest, then perform a guarded schema apply | | Projection status `failed` | A fast-path or outbox reconciliation attempt failed | Restore connectivity, inspect outbox status, and drain or replay durable delivery | | `authzed_projection_stale` | A revocation exceeded 60 seconds or entered dead letter | Investigate immediately, restore delivery, replay, drain, and require a clean audit | Formbricks AuthZed logs use `component="authzed"`, stable `errorCode` values, and bounded fields such as `operation`, `projection`, `status`, `retryable`, `attemptCount`, `grpcStatus`, and `durationMs`. They must not contain tokens, database credentials, schema text, raw SDK errors, relationship strings, or actor/resource IDs. ## Monitor AuthZed Enable the existing Formbricks Prometheus or OTLP metrics exporter. The release-matched direct-authority signals are: | Metric | What it measures | | - | - | | `formbricks_authzed_projection_total` | Projected, failed, and disabled projection outcomes | | `formbricks_authzed_projection_duration_seconds` | Request-path projection latency | | `formbricks_authzed_request_failures_total` | AuthZed requests that exhausted their retry budget | | `formbricks_authzed_request_retries_total` | Retry attempts caused by transient failures | | `formbricks_authzed_authorization_decisions_total` | Authoritative allow, deny, and operational-error outcomes | | `formbricks_authzed_authorization_decision_duration_seconds` | End-to-end authoritative authorization latency | | `formbricks_authzed_authorization_checks_per_request` | Central authorization operations per authenticated request | | `formbricks_authzed_projection_outbox_delivery_total` | Durable outbox events delivered or failed | | `formbricks_authzed_projection_outbox_delivery_duration_seconds` | Durable delivery batch latency | | `formbricks_authzed_projection_revocation_delivery_duration_seconds` | Commit-to-SpiceDB revocation propagation time | | `formbricks_authzed_projection_outbox_status` | Point-in-time pending, dead-letter, warning, and critical counts | | `formbricks_authzed_projection_outbox_oldest_pending_age_seconds` | Age of the oldest pending event | | `formbricks_authzed_reconciliation_audit_total` | Scheduled audit outcomes | | `formbricks_authzed_reconciliation_drift_total` | Attributable drift and failures observed by scheduled audits | | `formbricks_authzed_reconciliation_repair_total` | Repaired and failed attributable relationship repair results | Starting PromQL checks: ```promql theme={null} # Projection failures introduce possible drift. sum(rate(formbricks_authzed_projection_total{status="failed"}[5m])) # Terminal unavailability errors. sum(rate(formbricks_authzed_request_failures_total{code="authzed_unavailable"}[5m])) # Projection latency p95. histogram_quantile( 0.95, sum by (le) (rate(formbricks_authzed_projection_duration_seconds_bucket[5m])) ) # Direct-authority operational-error rate. Product denials remain a separate outcome. sum(rate(formbricks_authzed_authorization_decisions_total{outcome="operational_error"}[5m])) / sum(rate(formbricks_authzed_authorization_decisions_total[5m])) # Direct-authority latency p95 by surface. histogram_quantile( 0.95, sum by (le, surface) (rate(formbricks_authzed_authorization_decision_duration_seconds_bucket[5m])) ) # Revocations that missed the warning or critical delivery thresholds. formbricks_authzed_projection_outbox_status{state=~"revocation_warning|revocation_critical"} # Dead letters and failed scheduled repairs both block cutover. formbricks_authzed_projection_outbox_status{state="dead_lettered"} or sum(rate(formbricks_authzed_reconciliation_repair_total{status="failed"}[5m])) ``` Starting gates are: operational-error rate at or below 0.1%, p95 below 250 ms, p99 below one second, no dead-letter revocations, no normal-operation 60-second freshness guard, and clean scheduled audits. Alert on revocation delivery at 15 seconds (warning) and 45 seconds (critical). The application on-call owns decision, delivery, and repair alerts; the infrastructure on-call owns SpiceDB/datastore availability and capacity, with joint escalation whenever either side cannot restore a clean graph. On the SpiceDB side, monitor pod restarts, failed datastore migrations, PostgreSQL connection saturation such as `pgxpool_empty_acquire`, dispatch load, cache behavior, and datastore latency. Divide the datastore connection budget across replicas and their read/write pools. ## Use the incident checklist 1. Confirm Formbricks `/health` independently. 2. Run `formbricks-authzed health`. 3. Check SpiceDB pods or containers and the last datastore migration. 4. Check Formbricks projection failures, AuthZed terminal errors, retries, and latency. 5. Restore SpiceDB or its datastore without changing authorization data manually. 6. Run `schema check`. 7. Run a full dry-run backfill. 8. Apply repair and, only when justified, a guarded prune. 9. Require a clean result before relying on SpiceDB authorization decisions. 10. Preserve the sanitized command result, timeline, versions, and root cause for follow-up. # CDN Source: https://formbricks.com/docs/self-hosting/configuration/cdn Use a CDN in front of public Formbricks traffic without serving stale survey assets after upgrades. ### Why a CDN is recommended A CDN is recommended for production self-hosting when you expose Formbricks surveys publicly. It helps you: * reduce latency for survey respondents in different regions * absorb traffic spikes on public survey links and embedded surveys * terminate TLS and use provider features such as DDoS protection, WAF rules, and bot filtering * serve static assets such as `/_next/*`, `/css/*`, and `/js/surveys.umd.cjs` closer to end users You can run Formbricks without a CDN, but it is usually the better production setup once surveys are reachable from the public internet. ## Recommended topology The cleanest setup is to put the **public survey domain** behind the CDN and keep the **admin domain** separate: ```bash theme={null} # Private admin domain WEBAPP_URL=https://admin.formbricks.example.com BETTER_AUTH_URL=https://admin.formbricks.example.com # Public survey domain PUBLIC_URL=https://surveys.example.com ``` In this setup: * `PUBLIC_URL` handles survey traffic, embed traffic, and public assets * `WEBAPP_URL` handles the admin UI, authentication, and other private routes Please refer to the [Domain Configuration](/docs/self-hosting/configuration/domain-configuration) guide first if you have not set up a dedicated public domain yet. ## What the CDN should do Configure your CDN to proxy requests to your Formbricks origin while preserving the original `Host` header and HTTPS scheme. As a baseline, the CDN should: * cache static assets and respect origin cache headers * forward query strings * bypass cache when cookies or authorization headers are present * avoid rewriting paths or stripping prefixes > [!WARNING] > > Do not enable a blanket "cache everything" rule for all Formbricks routes. That can cause stale survey pages, > stale client state, broken authentication flows, or outdated JavaScript bundles after an upgrade. ## What is safe to cache In most setups, you should only cache static public assets aggressively: * `/_next/*` * `/js/*` * `/css/*` * `/images/*` * `/fonts/*` * `/icons/*` * `/favicon.ico` * `/storage/{workspaceId}/public/*` If you place the full public domain behind a CDN, keep HTML and API traffic proxied but not force-cached unless you have a very deliberate invalidation strategy. ## What should bypass cache These routes should generally not be cached: * admin routes served from `WEBAPP_URL` * authentication routes such as `/api/auth/*` * public client API routes such as `/api/v1/client/*` and `/api/v2/client/*` * survey HTML routes such as `/s/*`, `/c/*`, and `/p/*` unless your CDN strictly honors short origin cache headers This is especially important if your CDN vendor offers features like "Cache Everything", "Edge Cache TTL", or "Ignore origin headers". Those features can easily keep old Formbricks responses alive longer than intended. ## Important detail for upgrades Formbricks serves the survey runtime bundle from a stable public path: ```text theme={null} /js/surveys.umd.cjs ``` That bundle is used by the website/app survey SDK. If your CDN keeps serving an older copy after you deploy a new Formbricks version, respondents may receive outdated survey code even though the rest of the app has already been updated. This is the most common CDN-related upgrade issue for self-hosters: the application is updated, but the CDN still serves cached JavaScript from the previous release. ## Upgrade checklist Every time you update Formbricks, include CDN cache handling in your rollout: **1. Deploy the new Formbricks version** Update Formbricks as usual by following the [Migration Guide](/docs/self-hosting/advanced/migration) or your normal deployment process. **2. Purge or revalidate public assets** Purge the CDN cache for at least `/js/*`, `/_next/*`, and `/css/*`. If your CDN supports targeted purges, make sure `/js/surveys.umd.cjs` is included every time. **3. Check the public domain after the purge** Open a survey or embedded survey through the public domain and verify in the browser network tab that the JavaScript assets are fetched fresh from the updated release. **4. Hard refresh during validation** Browser caches can hide CDN issues. During verification, use a hard refresh or disable the browser cache in DevTools to confirm the new assets are really being served. ## Practical setup guidance Most CDN providers can be configured safely with the following approach: 1. Put only the public Formbricks domain behind the CDN. 2. Forward all requests to your reverse proxy or load balancer. 3. Cache static asset paths only. 4. Bypass cache for authenticated traffic, API traffic, and survey HTML. 5. Add a purge step to every Formbricks deployment or upgrade. If you use a single-domain deployment, the same advice still applies, but you need more careful cache rules because admin and public traffic share the same hostname. ## Troubleshooting stale content If users still see outdated surveys or broken embeds after an upgrade, check the following: * the CDN is not overriding origin cache headers with a long fixed TTL * `/js/surveys.umd.cjs` has been purged or revalidated * the public domain in your SDK configuration points to `PUBLIC_URL`, not the admin domain * the browser cache is cleared during verification * your reverse proxy is forwarding the correct `Host` and `X-Forwarded-Proto` headers If problems remain, temporarily bypass the CDN for the public domain. If the issue disappears immediately, the CDN cache policy is the first place to investigate. # Custom SSL Certificate Source: https://formbricks.com/docs/self-hosting/configuration/custom-ssl Using Formbricks One-Click Setup with a Custom SSL Certificate. > [!NOTE] > > Formbricks One-Click setup already comes with a valid SSL certificate using **Let's Encrypt**. This guide is only if you already have a valid SSL certificate that you need to use due to company policy or other requirements. Formbricks' One-Click setup automatically creates an SSL certificate using **Let's Encrypt**. However, some setups need a custom SSL certificate. This is common for intranets or systems with special certificate rules that use an internal or custom certificate authority (CA). ### Step 1: Navigate to the Formbricks Folder Move into the `formbricks/` directory: ```bash theme={null} cd formbricks ``` ### Step 2: Create a Folder for SSL Certificates Create a folder called `certs` and place your SSL certificate files inside: ```bash theme={null} mkdir certs # Move your SSL certificate files to the certs folder mv /path/to/your/fullchain.crt certs/ mv /path/to/your/cert.key certs/ ``` ### Step 3: Understand SSL Certificate Files * **fullchain.crt** – Your SSL certificate, including the full certificate chain. * **cert.key** – The private key used to encrypt data. ### Step 4: Set Correct File Permissions Ensure the certificate files have the right permissions: ```bash theme={null} sudo chown root:root certs/* sudo chmod 600 certs/* ``` ### Step 5: Update `traefik.yaml` Modify the file to define HTTP and HTTPS settings: ```yaml traefik.yaml theme={null} entryPoints: web: address: ":80" http: redirections: entryPoint: to: websecure scheme: https permanent: true websecure: address: ":443" providers: docker: watch: true exposedByDefault: false file: directory: /etc/traefik/dynamic ``` ### Step 6: Create `certs-traefik.yaml` Create a `certs-traefik.yaml` file that specifies the path to your custom SSL certificate and key. ```yaml certs-traefik.yaml theme={null} tls: certificates: - certFile: /certs/fullchain.crt keyFile: /certs/cert.key ``` ### Step 7: Update `docker-compose.yml` Modify the configuration to enforce SSL. The rest of the configuration should remain the same as the One-Click setup: ```yaml docker-compose.yml theme={null} services: formbricks: restart: always image: ghcr.io/formbricks/formbricks:latest depends_on: - postgres labels: - "traefik.enable=true" # Enable Traefik for this service - "traefik.http.routers.formbricks.rule=Host(`my-domain.com`)" # Use your actual domain or IP - "traefik.http.routers.formbricks.entrypoints=websecure" # Use the websecure entrypoint (port 443 with TLS) - "traefik.http.routers.formbricks.tls=true" # Enable TLS - "traefik.http.services.formbricks.loadbalancer.server.port=3000" # Forward traffic to Formbricks on port 3000 ports: - 127.0.0.1:3000:3000 # Host-only: outside traffic goes through Traefik volumes: - uploads:/home/nextjs/apps/web/uploads/ <<: *environment traefik: image: "traefik:v3.6.4" restart: always container_name: "traefik" depends_on: - formbricks ports: - "80:80" - "443:443" - "8080:8080" volumes: - ./traefik.yaml:/traefik.yaml - ./acme.json:/acme.json - /var/run/docker.sock:/var/run/docker.sock:ro - ./certs:/certs - ./certs-traefik.yaml:/etc/traefik/dynamic/certs-traefik.yaml ``` ## Summary * **Navigate to the Formbricks folder** * **Create a `certs/` folder** and move your certificate files inside. * **Ensure you have the correct certificate files** (`fullchain.crt` and `cert.key`). * **Update file permissions** for security. * **Modify `traefik.yaml`** to handle HTTPS. * **Create `certs-traefik.yaml`** to point to your certificate files. * **Update `docker-compose.yml`** to use your custom SSL certificate. This setup ensures that Formbricks securely communicates using your own SSL certificate. 🚀 If you have any questions or require help, feel free to reach out to us on [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions). 😃 # Custom Subpath Source: https://formbricks.com/docs/self-hosting/configuration/custom-subpath Serve Formbricks from a custom URL prefix when you cannot expose it on the root domain. > [!NOTE] > > Custom subpath deployments are currently under internal review. If you need early access, please reach out via > [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). ### When to use a custom subpath Use a custom subpath (also called a Next.js base path) when your reverse proxy reserves the root domain for another service, but you still want Formbricks to live under the same hostname—for example `https://example.com/feedback`. Support for a build-time `BASE_PATH` variable is available in the Formbricks web app so that Next.js-managed routes, assets, and navigation honor the prefix. ### Requirements and limitations * `BASE_PATH` must be present during `pnpm build`; changing it afterward requires a rebuild. * Next.js inlines the base path into the client bundles, so setting `BASE_PATH` on an already-built official Formbricks image has no effect. You must build your own Formbricks web image with the required value. * Formbricks-owned public URLs need the prefix, but the two variables expect a different path: `WEBAPP_URL` uses the app root, while `BETTER_AUTH_URL` uses the full auth endpoint under `/custom-path/api/auth`. External webhook target URLs do not need the prefix unless they point to a Formbricks endpoint. * Known limitation: the browser auth client currently sends login and sign-up requests to `/api/auth` at the domain root instead of `/custom-path/api/auth`. Authentication therefore does not work for a true subpath-only deployment, and changing the URL environment variables does not correct the browser request path. * Your proxy must rewrite `/custom-path/*` to the Formbricks container while keeping the prefix visible to clients. ### Configure object storage separately `BASE_PATH` applies only to the Formbricks web application. It does not add the same prefix to RustFS, MinIO, or another S3-compatible storage service, and the custom image described below is a Formbricks image—not a custom storage image. Keep the S3 API at the root of a dedicated endpoint such as `https://files.example.com` and set `S3_ENDPOINT_URL` to that endpoint. Do not route it through an arbitrary prefix such as `https://example.com/custom-path/storage`: the request path is part of the AWS Signature Version 4 signature, so proxy path rewriting can invalidate signed and presigned requests. Provider settings that expose a management console under a subpath do not change the S3 API base path. For the complete storage and CORS setup, see [File Uploads Configuration](/docs/self-hosting/configuration/file-uploads). ### Configure environment variables Add the following variables to the environment you use for builds (local, CI, or Docker build args): ```bash theme={null} BASE_PATH="/custom-path" WEBAPP_URL="https://yourdomain.com/custom-path" BETTER_AUTH_URL="https://yourdomain.com/custom-path/api/auth" ``` If you use third-party OAuth providers, ensure every Formbricks callback URL you register includes the prefix. MCP clients must use `https://yourdomain.com/custom-path/api/mcp`, and OAuth discovery is served from `https://yourdomain.com/custom-path/.well-known/oauth-authorization-server/api/auth`. ### Build a Docker image with a custom subpath **1. Clone Formbricks and prepare secrets** Make sure you have the repository checked out and create temporary files (or use `--secret`) for the required build-time secrets such as `DATABASE_URL`, `ENCRYPTION_KEY`, `REDIS_URL`, and optional telemetry tokens. **2. Pass BASE\_PATH as a build argument** Use the Formbricks web Dockerfile and supply the custom subpath via `--build-arg`. Example: ```bash theme={null} docker build \ --progress=plain \ --no-cache \ --build-arg BASE_PATH=/custom-path \ --secret id=database_url,src=<(printf "postgresql://user:password@localhost:5432/formbricks?schema=public") \ --secret id=encryption_key,src=<(printf "your-32-character-encryption-key-here") \ --secret id=redis_url,src=<(printf "redis://localhost:6379") \ --secret id=sentry_auth_token,src=<(printf "") \ -f apps/web/Dockerfile \ -t formbricks-web \ . ``` During the build logs you should see `BASE PATH /custom-path`, confirming that Next.js picked up the prefix. **3. Run the container behind your proxy** Start the resulting image with the same runtime environment variables you normally use (database credentials, mailing provider, etc.). Point your reverse proxy so that `/custom-path` requests forward to `http://formbricks-web:3000/custom-path` without stripping the prefix. ### Verify the deployment 1. Open `https://yourdomain.com/custom-path/auth/login` and confirm the page loads under the prefix. 2. In your browser's network panel, confirm Next.js assets and navigation requests include `/custom-path`. 3. Do not use login or onboarding as a successful deployment check until the browser auth-client limitation above is fixed. ### Troubleshooting checklist * Confirm your build pipeline actually passes `BASE_PATH` (and, if needed, `WEBAPP_URL`/`BETTER_AUTH_URL`) into the build stage—check CI logs for the `BASE PATH /your-prefix` line and make sure custom Dockerfiles or wrappers forward `--build-arg BASE_PATH=...` correctly. * Keep `WEBAPP_URL` and `BETTER_AUTH_URL` configured as shown above for server-side callbacks and discovery, but note that they do not fix the browser auth-client request path. * Re-run the Docker build when changing `BASE_PATH`; simply editing the container environment is not sufficient. * Inspect your proxy configuration to ensure it does not rewrite paths internally (e.g., `strip_prefix` needs to stay disabled). * When in doubt, rebuild locally with `--progress=plain` and verify that the `BASE PATH` line reflects your prefix. # Domain Configuration Source: https://formbricks.com/docs/self-hosting/configuration/domain-configuration Configuring your domain for Formbricks. Formbricks supports both single domain and dual domain configurations with Public/Private Domain Split feature. This guide will help you set up your domains correctly for enhanced security and organization. ## Single Domain Setup For a single domain setup, you need to configure two essential environment variables: 1. `WEBAPP_URL`: The base URL of your Formbricks instance (serves both admin and public content) 2. `BETTER_AUTH_URL`: The authentication URL (should be the same as WEBAPP\_URL) ### Example Configuration ```bash theme={null} WEBAPP_URL=https://formbricks.example.com BETTER_AUTH_URL=https://formbricks.example.com ``` ### Important Notes * Both URLs must be the same for authentication to work properly * The URLs should be the full URL including the protocol (http\:// or https\://) * Make sure your domain is properly configured in your DNS settings * If you're using HTTPS (recommended), ensure you have valid SSL certificates installed ## Public / Private Domain Split Formbricks supports a powerful domain separation feature that allows you to serve public content (surveys, public APIs) from a different domain than your private admin interface. This provides enhanced security and better organization. It enables you to: * Serve public content (surveys, public APIs) from a different domain than your private admin interface * Restrict admin functionality to the private domain * Ensure authentication and sensitive operations only occur on the private domain > [!WARNING] > > Publicly available images uploaded before the domain split (logos, images in Picture Select questions, etc.) will continue to be served from the Private Domain. **To protect your Private Domain, please reupload public images after the successful setup of the domain split.** ### Why Use Domain Split? * **Enhanced Security**: Separate public-facing surveys from your admin interface * **Better Organization**: Use dedicated domains for different purposes (e.g., `admin.company.com` for management, `surveys.company.com` for public surveys) ### Configuration To set up Public/Private Domain Split: 1. **Private Domain (WEBAPP\_URL)**: Your admin/management interface 2. **Public Domain (PUBLIC\_URL)**: For surveys and public-facing content **Important Security Note**: Formbricks handles application-level domain restrictions to ensure each domain can only access specific resources within the application. However, all domain configuration (DNS, SSL certificates, reverse proxy setup) and firewall configuration that comes with this feature to enhance security must be configured by you. Formbricks does not manage your infrastructure-level security settings. ### Example Configuration ```bash theme={null} # Private admin domain WEBAPP_URL=https://admin.formbricks.example.com BETTER_AUTH_URL=https://admin.formbricks.example.com # Public domain for surveys PUBLIC_URL=https://surveys.example.com ``` ### How It Works When PUBLIC\_URL is configured: * **Admin Interface**: All admin/management functions are served from `WEBAPP_URL` * **MCP and OAuth**: MCP (`/api/mcp`) and Better Auth OAuth/OIDC discovery and token endpoints are served from `WEBAPP_URL` * **Public Surveys**: All survey links and public APIs use `PUBLIC_URL` * **SDK Integration**: The public domain is used for all client-side SDK connections * **Email Links**: Survey invitation emails use the public domain * **Sharing Features**: Survey sharing uses the public domain ### Routes Available on the Public Domain When PUBLIC\_URL is configured, the following routes are automatically served from the public domain: #### Survey Routes * `/s/{surveyId}` - Individual survey access * `/c/{jwt}` - Personalized link survey access (JWT-based access) * `/p/{survey-slug}` - Pretty URL survey access * Embedded survey endpoints #### API Routes * `/api/v1/client/{workspaceId}/*` - Client API endpoints (v1) * `/api/v2/client/{workspaceId}/*` - Client API endpoints (v2) #### Static Assets & Next.js Routes * `/favicon.ico` - Favicon * `/_next/*` - Next.js static assets and build files * `/js/*` - JavaScript files * `/css/*` - CSS stylesheets * `/images/*` - Image assets * `/fonts/*` - Font files * `/icons/*` - Icon assets * `/public/*` - Public static files * `/animated-bgs/*` - Animated Background assets #### Storage Routes * `/storage/{workspaceId}/{accessType}/{fileName}` - Public file storage access #### Health & Monitoring * `/health` - Health check endpoint #### Sharing & Embed Routes * Survey sharing endpoints * Embed widget routes * Social sharing endpoints All other routes are restricted to the private domain (`WEBAPP_URL`) for security purposes. The admin domain can access the health endpoint (/health) and public file storage (`/storage/{workspaceId}/{accessType}/{fileName}`), while all other public routes are exclusively accessible on the public domain (`PUBLIC_URL`) and will return a 404 error if accessed from the admin domain. ### App URL SDK Configuration #### Multi-Domain Setup SDK Configuration When using PUBLIC\_URL (multi-domain setup), all SDK configurations must use the **public domain**: ```js theme={null} Formbricks.setup({ workspaceId: "your-workspace-id", appUrl: "https://surveys.example.com", // Use PUBLIC_URL domain }); ``` Please refer to the [Framework Guides](/docs/surveys/website-app-surveys/framework-guides) for step-by-step instructions specific to your platform. ### DNS and SSL Configuration 1. **Set up DNS records** for both domains 2. **Configure SSL certificates** for both domains 3. **Update your reverse proxy** (nginx, Apache, Cloudflare, etc.) to route both domains to your Formbricks instance 4. **Firewall rules**: Ensure both domains can reach your Formbricks instance ### Fallback Behavior If `PUBLIC_URL` is not set: * All content (admin and public) is served from `WEBAPP_URL` * The system behaves as a single domain setup * No domain separation occurs ### Reverting to a Single Domain While it's possible to revert to a Single Domain setup, please take into account the following: 1. All image links and uploaded files are stored in the database, so they will continue to link to the Public Domain **hence the links will break.** You'll need to reupload the images, like you did when you set up the domain split. 2. Any survey link shared to with the Public Domain **will break.** 3. API calls to the Public Domain **will break**, unless updated. As of now, Formbricks does not provide an automated migration between domain setups. If you have any questions or require help, feel free to reach out to us on [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Environment Variables Source: https://formbricks.com/docs/self-hosting/configuration/environment-variables Environment variables for Formbricks #### Custom Configurations These variables are present inside your machine's docker-compose file. Restart the docker containers if you change any variables for them to take effect. > [!NOTE] > > Upgrading from Formbricks 4.x to 5.0? Read the [migration guide](/docs/self-hosting/advanced/migration#v5) first. > Formbricks v5 makes Hub part of the standard self-hosted runtime and changes how rate limiting is enforced. For the `AI_*` variables, see [AI Features](/docs/self-hosting/configuration/ai-features) — it walks through each provider and the credentials it needs. Set only the variables for the provider you use; unused provider variables can be omitted. | Variable | Description | Required | Default | | - | - | - | - | | WEBAPP\_URL | Base URL of the private/admin Formbricks app. OAuth and MCP protected-resource URLs are derived from this value. | required | [http://localhost:3000](http://localhost:3000) | | PUBLIC\_URL | Base URL for the public domain where surveys and public-facing content are served. If not set, uses WEBAPP\_URL. OAuth and MCP do not use PUBLIC\_URL. | optional | WEBAPP\_URL | | BETTER\_AUTH\_URL | Auth base URL; Formbricks derives the Better Auth issuer under `/api/auth`. Normally the same as WEBAPP\_URL, but it is not inferred from it — leave it unset and Better Auth has no base URL or trusted origin, and every sign-in is rejected. Preserve any custom subpath. | required | [http://localhost:3000](http://localhost:3000) | | MCP\_OAUTH\_JWKS\_URL | Optional server-only URL used to fetch Better Auth signing keys for MCP OAuth. It does not change the public issuer, redirects, cookies, or token audience. Docker Compose and Helm leave it unset unless explicitly configured. Use an internal HTTP URL only on a trusted application network and include any custom application subpath. | optional | `{BETTER_AUTH_URL}/jwks` | | MCP\_DCR\_ALLOWED\_REDIRECT\_URIS | Optional comma-separated list of extra exact `https` redirect URIs that MCP clients may claim when they register themselves anonymously. Local (`http://localhost`, `127.0.0.1`, `[::1]`) callbacks and the claude.ai and ChatGPT callbacks are always allowed; this only adds to them. Entries match by exact string — no wildcards, no fragments, no credentials, no loopback hosts (local callbacks are already allowed), and a URI containing a comma is not supported. Anyone can register a client with these URIs, so only add a callback owned by the client's vendor, never a page that shows user content or forwards to another URL. | optional | | | DATABASE\_URL | Database URL with credentials. | required | | | BETTER\_AUTH\_SECRET | Signs session cookies and every invite, email-verification and email-change token. At least 32 characters; Formbricks refuses to start below that on a new install. | required | (Generated by the user, `openssl rand -hex 32`) | | ENCRYPTION\_KEY | Secret used by Formbricks for data encryption and audit log hashing. | required | (Generated by the user, must not exceed 32 bytes, `openssl rand -hex 32`) | | CRON\_SECRET | API Secret for running cron jobs. | required | (Generated by the user, must not exceed 32 bytes, `openssl rand -hex 32`) | | LOG\_LEVEL | Minimum log level (debug, info, warn, error, fatal) | optional | info | | S3\_ACCESS\_KEY | Access key for S3. | optional | (resolved by the AWS SDK) | | S3\_SECRET\_KEY | Secret key for S3. | optional | (resolved by the AWS SDK) | | S3\_REGION | Region for S3. | optional | (resolved by the AWS SDK) | | S3\_BUCKET\_NAME | S3 bucket name for data storage. Formbricks enables S3 storage when this is set. | optional (required if S3 is enabled) | | | S3\_ENDPOINT\_URL | Endpoint for S3. | optional | (resolved by the AWS SDK) | | S3\_FORCE\_PATH\_STYLE | Set to `1` to force path-style S3 URLs. Required for S3-compatible storage (MinIO, RustFS, LocalStack). Leave unset or `0` for standard AWS S3. | optional | 0 | | SAML\_DATABASE\_URL | Database URL for SAML. | optional | postgres\://postgres:@localhost:5432/formbricks-saml | | PRIVACY\_URL | URL for privacy policy. | optional | | | TERMS\_URL | URL for terms of service. | optional | | | IMPRINT\_URL | URL for imprint. | optional | | | IMPRINT\_ADDRESS | Address for imprint. | optional | | | EMAIL\_AUTH\_DISABLED | Disables the ability for users to signup or login via email and password if set to 1. | optional | | | PASSWORD\_RESET\_DISABLED | Disables password reset functionality if set to 1. | optional | | | PASSWORD\_HIBP\_CHECK\_DISABLED | Disables the Have-I-Been-Pwned breach check on password set (signup / reset) if set to 1. The check calls api.pwnedpasswords.com and fails open on network errors; set this on air-gapped / closed-network deployments to skip the outbound call. | optional | | | PASSWORD\_RESET\_TOKEN\_LIFETIME\_MINUTES | Configures how long password reset links remain valid in minutes. Accepted values are integers from 5 to 120. | optional | 30 | | EMAIL\_VERIFICATION\_DISABLED | Disables email verification if set to 1. | optional | | | RATE\_LIMITING\_DISABLED | Disables only the application-level rate limiter if set to 1. It does not disable Envoy or an equivalent edge rate limiter. | optional | | | INVITE\_RATE\_LIMIT\_PER\_24\_HOURS | Maximum invite recipients one organization, and separately one inviting user across all of their organizations, may target across single, bulk, onboarding, and resend flows within 24 hours. | optional | 50 | | ENTERPRISE\_LICENSE\_KEY | License key for the Formbricks Enterprise Edition. Unlocks Enterprise-only features; the instance validates it against the Formbricks license server, so it needs outbound network access (or `HTTP_PROXY`/`HTTPS_PROXY`). See [License Activation](/docs/self-hosting/advanced/license-activation). | optional (required for Enterprise Edition features) | | | TELEMETRY\_DISABLED | Disables telemetry reporting if set to 1. Ignored when an Enterprise License is active. | optional | | | DANGEROUSLY\_ALLOW\_WEBHOOK\_INTERNAL\_URLS | Allows webhook URLs to point to internal/private network addresses (e.g. localhost, 192.168.x.x) if set to 1. Useful for self-hosted instances that need to send webhooks to internal services. | optional | | | WEBHOOK\_DELIVERY\_TIMEOUT\_MS | Milliseconds a webhook delivery (and the "test endpoint" button) waits for the receiver to respond before failing the attempt. Between 1000 and 30000. A longer timeout holds a Job Runner slot longer. | optional | 5000 | | INVITE\_DISABLED | Disables the ability for invited users to create an account if set to 1. | optional | | | MAIL\_FROM | Email address to send emails from. | optional (required if email services are to be enabled) | | | MAIL\_FROM\_NAME | Email name/title to send emails from. | optional (required if email services are to be enabled) | | | SES\_CONFIGURATION\_SET | Amazon SES configuration set for event publishing. Set only with SES SMTP and SES\_EMAIL\_ENVIRONMENT; omitted by default. | optional | | | SES\_EMAIL\_ENVIRONMENT | Deployment label for SES metrics, such as staging. Requires SES\_CONFIGURATION\_SET. Both values accept ASCII letters, digits, hyphens and underscores (up to 64 characters). | optional | | | SMTP\_HOST | Host URL of your SMTP server. | optional (required if email services are to be enabled) | | | SMTP\_PORT | Host Port of your SMTP server. | optional (required if email services are to be enabled) | | | SMTP\_USER | Username for your SMTP Server. | optional (required if email services are to be enabled) | | | SMTP\_PASSWORD | Password for your SMTP Server. | optional (required if email services are to be enabled) | | | SMTP\_AUTHENTICATED | If set to 0, the server will not require SMTP\_USER and SMTP\_PASSWORD(default is 1) | optional | | | SMTP\_SECURE\_ENABLED | Set to `1` for implicit TLS (typically port 465); set to `0` for STARTTLS or a local relay. | optional (required if email services are to be enabled) | 0 | | SMTP\_REQUIRE\_TLS | Set to `1` to require STARTTLS when implicit TLS is disabled (typically port 587). Sending fails if the server does not offer STARTTLS. Leave at `0` for plaintext local relays. | optional | 0 | | SMTP\_REJECT\_UNAUTHORIZED\_TLS | Keep at `1` to verify the SMTP server certificate. Setting `0` disables certificate verification and is unsafe for production; mount a private CA and configure `NODE_EXTRA_CA_CERTS` instead. | optional | 1 | | TURNSTILE\_SITE\_KEY | Site key for Turnstile. | optional | | | TURNSTILE\_SECRET\_KEY | Secret key for Turnstile. | optional | | | RECAPTCHA\_SITE\_KEY | Site key for survey responses recaptcha bot protection | optional | | | RECAPTCHA\_SECRET\_KEY | Secret key for recaptcha bot protection. | optional | | | GITHUB\_ID | Client ID for GitHub. | optional (required if GitHub auth is enabled) | | | GITHUB\_SECRET | Secret for GitHub. | optional (required if GitHub auth is enabled) | | | GOOGLE\_CLIENT\_ID | Client ID for Google. | optional (required if Google auth is enabled) | | | GOOGLE\_CLIENT\_SECRET | Secret for Google. | optional (required if Google auth is enabled) | | | AI\_PROVIDER | Instance-level AI provider used in the background. Supported values: `aws`, `google`, `azure`, `openai-compatible`. | optional (required if AI is enabled) | | | AI\_MODEL | Instance-level AI model or deployment name used by the active provider. | optional (required if `AI_PROVIDER` is set) | | | AI\_GOOGLE\_CLOUD\_PROJECT | Google Cloud project ID for the `google` AI provider. | optional (required if `AI_PROVIDER=google`) | | | AI\_GOOGLE\_CLOUD\_LOCATION | Google Cloud location for `google` AI requests. Passed through as given; `us` and `eu` use multi-region endpoints. `global` is the safe default. | optional (required if `AI_PROVIDER=google`) | | | AI\_GOOGLE\_CLOUD\_CREDENTIALS\_JSON | Optional service account credentials JSON override for the `google` AI provider. Omit when Application Default Credentials are available. | optional | | | AI\_GOOGLE\_CLOUD\_APPLICATION\_CREDENTIALS | Optional path to Google Application Default Credentials used by the `google` AI provider. | optional | | | AI\_AWS\_REGION | AWS region for Amazon Bedrock. | optional (required if `AI_PROVIDER=aws`) | | | AI\_AWS\_ACCESS\_KEY\_ID | AWS access key ID for Amazon Bedrock. | optional (required if `AI_PROVIDER=aws`) | | | AI\_AWS\_SECRET\_ACCESS\_KEY | AWS secret access key for Amazon Bedrock. | optional (required if `AI_PROVIDER=aws`) | | | AI\_AWS\_SESSION\_TOKEN | AWS session token for Amazon Bedrock temporary credentials. | optional | | | AI\_AZURE\_BASE\_URL | Azure OpenAI / Foundry base URL, ending at `/openai` — the SDK appends `/v1` itself. When set, this is preferred over `AI_AZURE_RESOURCE_NAME`. | optional (one of this or `AI_AZURE_RESOURCE_NAME` required if `AI_PROVIDER=azure`) | | | AI\_AZURE\_RESOURCE\_NAME | Azure resource name used to assemble the Azure OpenAI URL. | optional (one of this or `AI_AZURE_BASE_URL` required if `AI_PROVIDER=azure`) | | | AI\_AZURE\_API\_KEY | API key for Azure OpenAI / Foundry. | optional (required if `AI_PROVIDER=azure`) | | | AI\_AZURE\_API\_VERSION | Azure API version for OpenAI-compatible calls. | optional | v1 | | AI\_OPENAI\_COMPATIBLE\_BASE\_URL | Base URL for a Qwen/vLLM OpenAI-compatible `/v1` endpoint, e.g. `http://vllm:8000/v1`. | optional (required if `AI_PROVIDER=openai-compatible`) | | | AI\_OPENAI\_COMPATIBLE\_API\_KEY | Optional API key for the OpenAI-compatible endpoint. | optional | | | AI\_OPENAI\_COMPATIBLE\_PROVIDER\_NAME | Provider name passed to the OpenAI-compatible adapter. Use `vllm` for the supported Qwen/vLLM self-hosted path. | optional | openai-compatible | | AI\_OPENAI\_COMPATIBLE\_SUPPORTS\_STRUCTURED\_OUTPUTS | Set to `1` when the Qwen/vLLM endpoint supports structured outputs. | optional | 0 | | AI\_OPENAI\_COMPATIBLE\_HEADERS\_JSON | Optional JSON object of string-valued headers to send with OpenAI-compatible requests. | optional | | | AI\_OPENAI\_COMPATIBLE\_QUERY\_PARAMS\_JSON | Optional JSON object of string-valued query parameters to send with OpenAI-compatible requests. | optional | | | AI\_OPENAI\_COMPATIBLE\_AUTH\_MODE | How Formbricks authenticates to the OpenAI-compatible endpoint: `api-key` or `oauth2-client-credentials`. See [Behind an OAuth2 gateway](/docs/self-hosting/configuration/ai-features#behind-an-oauth2-gateway). | optional | api-key | | AI\_OPENAI\_COMPATIBLE\_OAUTH\_TOKEN\_URL | OAuth2 token endpoint, e.g. `https://gateway.example.internal/oauth/token`. Must be `https` (plain `http` only on localhost). | optional (required if `AI_OPENAI_COMPATIBLE_AUTH_MODE=oauth2-client-credentials`) | | | AI\_OPENAI\_COMPATIBLE\_OAUTH\_CLIENT\_ID | OAuth2 client ID. | optional (required if `AI_OPENAI_COMPATIBLE_AUTH_MODE=oauth2-client-credentials`) | | | AI\_OPENAI\_COMPATIBLE\_OAUTH\_CLIENT\_SECRET | OAuth2 client secret. | optional (required if `AI_OPENAI_COMPATIBLE_AUTH_MODE=oauth2-client-credentials`) | | | AI\_OPENAI\_COMPATIBLE\_OAUTH\_SCOPE | Space-separated scopes to request with the token. | optional | | | AI\_OPENAI\_COMPATIBLE\_OAUTH\_AUTH\_STYLE | Where the client credentials go in the token request: `basic` (Authorization header) or `post` (form body). | optional | basic | | AI\_OPENAI\_COMPATIBLE\_OAUTH\_EXTRA\_PARAMS\_JSON | Optional JSON object of string-valued parameters to add to the token request, e.g. `audience`. | optional | | | STRIPE\_SECRET\_KEY | Secret key for Stripe integration. | optional | | | STRIPE\_WEBHOOK\_SECRET | Webhook secret for Stripe integration. | optional | | | DEFAULT\_BRAND\_COLOR | Default brand color for your app (Can be overwritten from the UI as well). | optional | #64748b | | UNSPLASH\_ACCESS\_KEY | Unsplash access key used to search Unsplash for survey background images. Without it, the image tab is hidden in the survey editor's background picker and in the Look & Feel settings. | optional (required for Unsplash background images) | | | AUTH\_SSO\_DEFAULT\_ORGANIZATION\_ID | Requires an [Enterprise Edition](/docs/self-hosting/advanced/license) licence with SSO. Automatically assigns new SSO users to this organization, without requiring an invitation. Must be a valid CUID; the organization is created with this ID on the first sign-up if it does not exist yet. Renamed from `DEFAULT_ORGANIZATION_ID` in v6. | optional (Enterprise Edition, SSO) | | | AUTH\_SSO\_DEFAULT\_ORGANIZATION\_ROLE | Role given to users auto-assigned by `AUTH_SSO_DEFAULT_ORGANIZATION_ID`. The sign-up that creates the organization is always `owner`. One of `owner`, `manager`, `member`, `billing`. Renamed from `DEFAULT_ORGANIZATION_ROLE` in v6. | optional (Enterprise Edition, SSO) | manager | | OIDC\_DISPLAY\_NAME | Display name for Custom OpenID Connect Provider | optional | | | OIDC\_CLIENT\_ID | Client ID for Custom OpenID Connect Provider | optional (required if OIDC auth is enabled) | | | OIDC\_CLIENT\_SECRET | Secret for Custom OpenID Connect Provider | optional (required if OIDC auth is enabled) | | | OIDC\_ISSUER | Issuer URL for Custom OpenID Connect Provider (should have .well-known configured at this) | optional (required if OIDC auth is enabled) | | | OIDC\_SIGNING\_ALGORITHM | Signing Algorithm for Custom OpenID Connect Provider | optional | RS256 | | OTEL\_EXPORTER\_OTLP\_ENDPOINT | Base OTLP HTTP endpoint for traces and metrics export (e.g. [http://collector:4318](http://collector:4318)). | optional | | | OTEL\_EXPORTER\_OTLP\_PROTOCOL | OTLP protocol to use for export. | optional | http/protobuf | | OTEL\_SERVICE\_NAME | Service name reported in OpenTelemetry resource attributes. | optional | formbricks | | OTEL\_RESOURCE\_ATTRIBUTES | Comma-separated resource attributes in OTel format (`key=value,key2=value2`). | optional | | | OTEL\_TRACES\_SAMPLER | Trace sampler strategy (`always_on`, `always_off`, `traceidratio`, `parentbased_traceidratio`). | optional | always\_on | | OTEL\_TRACES\_SAMPLER\_ARG | Sampling argument used by ratio-based samplers (`0` to `1`). | optional | | | PROMETHEUS\_ENABLED | Enables Prometheus metrics if set to 1. | optional | | | PROMETHEUS\_EXPORTER\_PORT | Port for Prometheus metrics. | optional | 9090 | | AUTH\_SSO\_DEFAULT\_TEAM\_ID | ID of the team that new SSO users are automatically added to. The owning organization is derived from this team. Must be set together with `AUTH_SKIP_INVITE_FOR_SSO=1` for auto-provisioning to work. | optional | | | AUTH\_SKIP\_INVITE\_FOR\_SSO | Set to `1` to allow SSO users to create an account without a manual invite. Keep unset (or `0`) for stricter access control where only invited users can join. | optional | 0 | | HTTP\_PROXY | HTTP proxy URL used for outbound requests (e.g., license checks). When both are set, `HTTPS_PROXY` takes precedence. | optional | | | HTTPS\_PROXY | HTTPS proxy URL used for outbound requests. Takes precedence over `HTTP_PROXY`. | optional | | | SENTRY\_DSN | Set this to track errors and monitor performance in Sentry. | optional | | | SENTRY\_ENVIRONMENT | Set this to identify the environment in Sentry | optional | | | SENTRY\_AUTH\_TOKEN | Set this if you want to make errors more readable in Sentry. | optional | | | SESSION\_MAX\_AGE | Configure the maximum age for the session in seconds. | optional | 86400 (24 hours) | | SINGLE\_USE\_LEGACY\_UNSIGNED\_UNTIL | Grace window for single-use links issued before v6, which carry no `suToken` signature. An ISO 8601 date (`YYYY-MM-DD`); unsigned **encrypted** links are accepted until 00:00 UTC on it. While set, the instance accepts a single-use link that is bound to no survey, so one issued for one survey opens any other on the same instance — on a multi-tenant deployment that is cross-organisation. Leave unset unless you are re-issuing outstanding links, and see the [migration guide](/docs/self-hosting/advanced/migration). | optional | | | USER\_MANAGEMENT\_MINIMUM\_ROLE | Set this to control which roles can access user management features. Accepted values: "owner", "manager", "disabled" | optional | manager | | REDIS\_URL | Redis URL for caching, rate limiting, audit logging, and the shared BullMQ background-job queue. All web and worker replicas must share this Redis instance. Application will not start without this. | required | redis\://localhost:6379 | | REDIS\_TLS\_CA | Optional PEM CA bundle for private-CA `rediss://` connections. Applies only to Redis; include all active CAs during rotation and restart all consumers after changes. Certificate and hostname/IP verification remain enabled. | optional | | | BULLMQ\_WORKER\_ENABLED | Set to `1` to start BullMQ workers inside each Formbricks web process. Set to `0` only in a custom deployment that already runs an external consumer with the complete Formbricks application job handlers. | optional | 1 outside test environments | | BULLMQ\_EXTERNAL\_WORKER\_ENABLED | Custom integrations only: set to `1` on web/API processes that only enqueue jobs while an external consumer with the complete Formbricks application job handlers processes them. This flag only keeps queueing enabled; it does not provide or start a worker. | optional | 0 | | BULLMQ\_WORKER\_COUNT | Number of BullMQ worker instances to start in each Formbricks web process. Must be a positive integer. | optional | 1 | | BULLMQ\_WORKER\_CONCURRENCY | Number of jobs each in-process BullMQ worker can process concurrently. Must be a positive integer. | optional | 1 | | AUDIT\_LOG\_ENABLED | Set this to 1 to enable audit logging. Requires Redis to be configured with the REDIS\_URL env variable. | optional | 0 | | AUDIT\_LOG\_GET\_USER\_IP | Set to 1 to include user IP addresses in audit logs from request headers | optional | 0 | | See [Job Runner](/docs/self-hosting/configuration/job-runner) for BullMQ architecture, scaling, and | | | | | troubleshooting guidance. | | | | #### OAuth and MCP URLs The MCP server is available on the private/admin app at `/api/mcp`. OAuth discovery and token issuance are also private/admin app surfaces: ```text theme={null} {WEBAPP_URL}/api/mcp {WEBAPP_URL}/.well-known/oauth-protected-resource/api/mcp {WEBAPP_URL}/.well-known/oauth-authorization-server/api/auth ``` If you use a custom subpath, include that subpath in both `WEBAPP_URL` and `BETTER_AUTH_URL`. Do not point MCP or OAuth clients at `PUBLIC_URL`; that domain is reserved for public survey delivery and SDK traffic. #### Formbricks Hub Starting with Formbricks v5, Hub is part of the standard self-hosted runtime. When you run Formbricks with the bundled Docker Compose or Helm assets, the following variables apply: | Variable | Description | Required | Default | | - | - | - | - | | HUB\_API\_KEY | API key used by the Formbricks Hub API. Generate a strong secret and use the same value wherever your deployment supplies Hub auth configuration. | required | (e.g. `openssl rand -hex 32`) | | HUB\_API\_URL | Base URL the Formbricks app uses to call Hub. With the bundled Docker stack, keep this at `http://hub:8080` unless Hub runs elsewhere. | required | `http://hub:8080` (bundled Docker), `http://localhost:8080` (local dev) | | HUB\_DATABASE\_URL | PostgreSQL connection URL for Hub. Omit to use the same database as Formbricks. | optional | Same as Formbricks `DATABASE_URL` (shared database) | #### SpiceDB Authorization These variables define the supported SpiceDB client contract. Formbricks v6 requires SpiceDB by default for fresh Docker, one-click, and Helm installations. Existing installations must pass the release-matched upgrade gate before enabling the v6 application image. | Variable | Description | Required at server startup | Default | | - | - | - | - | | AUTHZED\_ENABLED | Enables the required SpiceDB authorization engine. | required | `true` in bundled Docker, Helm, and dev | | AUTHZED\_ENDPOINT | SpiceDB gRPC endpoint as `host:port`. The default Helm-managed service is `formbricks-spicedb:50051`. | required | `spicedb:50051` in Docker; `localhost:50051` in dev | | AUTHZED\_TOKEN | Preshared API token. Always load this from a secret. | required | | | AUTHZED\_SYSTEM\_KEY | Stable namespace for Formbricks authorization objects and relationships. | required | `formbricks` | | AUTHZED\_INSECURE | Allows plaintext gRPC for an in-cluster service. Keep disabled for endpoints outside the trusted cluster network. | optional | `true` in Helm and bundled Docker/dev | | AUTHZED\_CONSISTENCY | Must be `fully_consistent` for v6 authorization. | required | `fully_consistent` in released Docker and Helm | Stored survey visibility restrictions are always enforced. Projection readiness gates visibility mutations and survey graph checks; before readiness, the PostgreSQL policy and workspace authorization apply (see [AuthZed operations](/docs/self-hosting/configuration/authzed-operations)). The following variables control visibility mutations and workspace survey limits: | Variable | Description | Required | Default | | - | - | - | - | | SURVEY\_VISIBILITY\_FORCE\_DISABLED | `1` disables visibility mutations. Stored survey restrictions remain enforced, including before projection readiness. Takes effect on restart. | optional | unset | | SURVEY\_WORKSPACE\_LIMIT | Most surveys one workspace may hold, archived surveys included. Creating one past it answers `422 workspace_survey_limit_reached`. | optional | `10000` | Docker Compose additionally requires `AUTHZED_DATABASE_PASSWORD` for its dedicated `spicedb` PostgreSQL login. Generate both it and `AUTHZED_TOKEN` with `openssl rand -hex 32`. `SPICEDB_IMAGE_REF` can override the bundled `authzed/spicedb:v1.52.0` image for an explicitly reviewed upgrade; the migration and server services always use the same reference. The v6 server requires `AUTHZED_ENABLED=true` or `1`; unset, `false`, and `0` are rejected before it accepts requests. `AUTHZED_INSECURE` accepts `true`, `false`, `1`, or `0`; when unset, it uses TLS. A configured endpoint must be a bare `host:port` with an explicit port from 1 through 65535, for example `spicedb:50051`, `grpc.authzed.com:443`, or `[::1]:50051`. Do not include a URL scheme, path, query, credentials, or whitespace. `AUTHZED_SYSTEM_KEY` must be a 3–64 character lowercase SpiceDB identifier made from letters, digits, and underscores; it must start with a letter or underscore and end with a letter or digit. The supported consistency values accepted by diagnostic clients are `minimize_latency` and `fully_consistent`. Every v6 server requires an explicit `fully_consistent`; both server startup and the upgrade gate reject weaker consistency. Builds and diagnostic CLI commands may parse disabled configuration without credentials. That does not make disabled authorization a supported server mode: there is no PostgreSQL permission fallback. Startup reports missing field names and setup guidance, never tokens. Retired shadow/cohort variables are not required. Changing any AuthZed setting requires restarting the Formbricks process. In a released Docker installation, validate the configured connection without installing a schema or changing data: ```bash theme={null} docker compose --profile authzed-ops run --rm authzed-ops health docker compose --profile authzed-ops run --rm authzed-ops upgrade check ``` For Helm, run `formbricks-authzed health` inside a Formbricks application pod. Repository development can keep using `pnpm authzed:health`. See [AuthZed Operations](/docs/self-hosting/configuration/authzed-operations) for the complete Docker and Kubernetes command set, schema lifecycle, backups, and relationship repair. Only the repository-development `pnpm authzed:health` command reads the repository `.env`. Docker Compose uses the `authzed-ops` container environment, while Helm and Kubernetes use the Formbricks Pod environment. Each invocation performs an authenticated read-only schema request, prints exactly one JSON result, and exits `0` only for `{"status":"healthy","latencyMs":12}` (the latency varies). Disabled or failed checks exit `1`. Failures use stable codes: `authzed_unauthenticated` or `authzed_permission_denied` for rejected credentials or schema-read access (the bundled SpiceDB preshared-key check reports a wrong token as permission denied), `authzed_timeout` when an attempt exceeds its deadline, `authzed_overloaded` when SpiceDB is resource constrained, `authzed_unavailable` when the service cannot be reached, and `authzed_internal` for an unexpected client failure. Schema text, tokens, raw SDK errors, and stack traces are never included. This check is intentionally a CLI rather than a browser page or HTTP endpoint. Startup validates configuration without contacting SpiceDB. Connectivity is not part of the general `/health` response or Kubernetes readiness, so a transient SpiceDB outage does not restart or mark the rest of Formbricks unhealthy. Failed or unavailable permission checks fail the protected operation closed; there is no runtime fallback to legacy authorization. Existing installations must complete `formbricks-authzed upgrade prepare` followed by `upgrade check` before upgrading. The general application readiness probe remains independent from AuthZed so a transient authorization outage does not restart unrelated Formbricks workloads. #### Cube Analytics Cube is part of the baseline Formbricks v5 stack and is required. Formbricks generates the backend Cube JWT from `CUBEJS_API_SECRET`, so `CUBEJS_API_TOKEN` is not part of the supported setup contract. | Variable | Description | Required | Default | | - | - | - | - | | CUBEJS\_API\_URL | Base URL the Formbricks app uses to call Cube. Local dev (app on host): `http://localhost:4000`. Docker/container: `http://cube:4000` (service name). | required | | | CUBEJS\_API\_SECRET | Shared secret Formbricks uses to sign Cube API JWTs. Generate with `openssl rand -hex 32`. | required | | | CUBEJS\_JWT\_ISSUER | JWT issuer expected by Cube and used by Formbricks when signing per-request Cube tokens. | optional | `formbricks-web` | | CUBEJS\_JWT\_AUDIENCE | JWT audience expected by Cube and used by Formbricks when signing per-request Cube tokens. | optional | `formbricks-cube` | | CUBEJS\_DB\_HOST | Database host for the Cube service. Only needed when you run Cube yourself and override defaults. | optional | Depends on your Cube deployment | | CUBEJS\_DB\_PORT | Database port for the Cube service. Only needed when you run Cube yourself and override defaults. | optional | Depends on your Cube deployment | | CUBEJS\_DB\_NAME | Database name for the Cube service. Only needed when you run Cube yourself and override defaults. | optional | Depends on your Cube deployment | | CUBEJS\_DB\_USER | Database user for the Cube service. Only needed when you run Cube yourself and override defaults. | optional | Depends on your Cube deployment | | CUBEJS\_DB\_PASS | Database password for the Cube service. Only needed when you run Cube yourself and override defaults. | optional | Depends on your Cube deployment | The bundled Docker Compose Cube service sets `CUBEJS_DEFAULT_API_SCOPES=meta,data` directly on the Cube container. If you run Cube outside the bundled Compose stack, configure the equivalent Cube service environment there rather than adding it to the Formbricks app environment. For Helm deployments, the chart deploys Cube by default (`cube.enabled: true`). To use an external Cube cluster instead, set `cube.enabled: false`, point `CUBEJS_API_URL` at your endpoint, and supply `CUBEJS_API_SECRET` through your existing secret management setup. Note: If you want to configure something that is not possible via above, please open an issue on our GitHub repo here or reach out to us on Github Discussions and we'll try our best to work out a solution with you. # File Uploads Configuration Source: https://formbricks.com/docs/self-hosting/configuration/file-uploads Configure file storage for survey images, file uploads, and Workspace assets in your self-hosted Formbricks instance Formbricks requires S3-compatible storage for file uploads. You can use external cloud storage services or the bundled RustFS option for a self-hosted solution. ## Why Configure File Uploads? Setting up file storage enables important features in Formbricks, including: * Adding images to surveys (questions, backgrounds, logos) * 'File Upload' and 'Picture Selection' question types * Workspace logos and branding * Custom organization logos in emails * Survey background images from uploads > [!WARNING] > > If file uploads are not configured, the above features will be disabled and users won't be able to upload > files or images. ## Storage Options Formbricks supports S3-compatible storage with two main configurations: ### 1. External S3-Compatible Storage Use cloud storage services for production deployments: * **AWS S3** (Amazon Web Services) * **DigitalOcean Spaces** * **Wasabi** * **StorJ** * Any S3-compatible storage service ### 2. Bundled RustFS Storage (Self-Hosted) > [!WARNING] > > **Important**: Bundled RustFS requires a dedicated subdomain. You must configure a subdomain like > `files.yourdomain.com` that points to your server so browser uploads can reach the object storage endpoint. > [!WARNING] > > Bundled RustFS is a convenience-oriented single-server option. It fits small-scale or lower-complexity > self-hosted deployments, but it is not the ideal RustFS architecture for high-availability or larger-scale > production storage. For stricter production requirements, prefer external object storage or a dedicated > RustFS deployment. RustFS provides a self-hosted S3-compatible storage solution that runs alongside Formbricks. This option: * Runs in a Docker container alongside Formbricks * Provides full S3 API compatibility * Uses the same `S3_*` environment variables as any other S3-compatible provider ## Configuration Methods ### Option 1: One-Click Setup Script When using the Formbricks installation script, you'll be prompted to configure file uploads: ```bash theme={null} 📁 Do you want to configure file uploads? If you skip this, the following features will be disabled: - Adding images to surveys (e.g., in questions or as background) - 'File Upload' and 'Picture Selection' question types - Workspace logos - Custom organization logo in emails Configure file uploads now? [Y/n] y ``` #### External S3-Compatible Storage Choose this option for AWS S3, DigitalOcean Spaces, or other cloud providers: ```bash theme={null} 🗄️ Do you want to use an external S3-compatible storage (AWS S3/DO Spaces/etc.)? [y/N] y 🔧 Enter S3 configuration (leave Endpoint empty for AWS S3): S3 Access Key: your_access_key S3 Secret Key: your_secret_key S3 Region (e.g., us-east-1): us-east-1 S3 Bucket Name: your-bucket-name S3 Endpoint URL (leave empty if you are using AWS S3): https://your-endpoint.com ``` #### Bundled RustFS Storage Choose this option for a self-hosted S3-compatible storage that runs alongside Formbricks: > [!NOTE] > > **Critical Requirement**: Before proceeding, ensure you have configured a subdomain (e.g., > `files.yourdomain.com`) that points to your server's IP address. This is required so browser-direct uploads > can reach RustFS. ```bash theme={null} 🗄️ Do you want to use an external S3-compatible storage (AWS S3/DO Spaces/etc.)? [y/N] n 🔗 Enter the files subdomain for object storage (e.g., files.yourdomain.com): files.yourdomain.com ``` The script will automatically: * Generate separate RustFS admin and Formbricks service credentials * Create the storage bucket * Configure SSL certificates for the files subdomain * Configure Traefik routing for the subdomain * Store the generated RustFS credentials in `./formbricks/.env` with restricted permissions ### Option 2: Manual Environment Variables Add the following environment variables to your `docker-compose.yml` or `.env` file: #### For S3-Compatible Storage ```bash theme={null} # S3 Storage Configuration S3_ACCESS_KEY=your_access_key S3_SECRET_KEY=your_secret_key S3_REGION=us-east-1 S3_BUCKET_NAME=your-bucket-name # Optional: For third-party S3-compatible services (leave empty for AWS S3) S3_ENDPOINT_URL=https://your-endpoint.com # Enable path-style URLs for third-party services (1 for enabled, 0 for disabled) S3_FORCE_PATH_STYLE=1 ``` > [!NOTE] > > **AWS S3 vs. third‑party S3:** When using AWS S3 directly, leave `S3_ENDPOINT_URL` unset and > set `S3_FORCE_PATH_STYLE=0` (or omit). For most third‑party S3‑compatible providers (e.g., RustFS, > DigitalOcean Spaces, Wasabi, Storj), you typically must set `S3_ENDPOINT_URL` to the provider's endpoint and > set `S3_FORCE_PATH_STYLE=1`. ## Provider-Specific Examples ### AWS S3 ```bash theme={null} S3_ACCESS_KEY=AKIA1234567890EXAMPLE S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY S3_REGION=us-east-1 S3_BUCKET_NAME=my-formbricks-uploads # S3_ENDPOINT_URL is not needed for AWS S3 # S3_FORCE_PATH_STYLE=0 ``` ### DigitalOcean Spaces ```bash theme={null} S3_ACCESS_KEY=your_spaces_key S3_SECRET_KEY=your_spaces_secret S3_REGION=nyc3 S3_BUCKET_NAME=my-formbricks-space S3_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com S3_FORCE_PATH_STYLE=1 ``` ### RustFS (Self-Hosted) ```bash theme={null} S3_ACCESS_KEY=rustfs_service_access_key S3_SECRET_KEY=rustfs_service_secret_key S3_REGION=us-east-1 S3_BUCKET_NAME=formbricks-uploads S3_ENDPOINT_URL=https://files.yourdomain.com S3_FORCE_PATH_STYLE=1 ``` ### Compatibility requirement: S3 POST Object support Formbricks uses the S3 [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) operation (presigned POST) for uploads. Your object storage provider must support this operation. Providers that do not implement POST Object are not compatible with Formbricks uploads. For example, Backblaze B2's S3‑compatible API currently does not support POST Object and therefore will not work with Formbricks file uploads. ## Bundled RustFS Setup When using the bundled RustFS option through the setup script, you get: ### Automatic Configuration * **Storage Service**: RustFS running in a Docker container * **Credentials**: Auto-generated admin and least-privilege service credentials * **Bucket**: Automatically created `formbricks-uploads` bucket * **SSL**: Automatic certificate generation for the files subdomain ### Access Information After setup, you'll see: ```bash theme={null} 🗄️ RustFS Storage Setup Complete: • Access Key: formbricks-service-a1b2c3d4 • Bucket: formbricks-uploads (✅ automatically created) ``` ### DNS Requirements > [!WARNING] > > **Critical for bundled RustFS**: The files subdomain is mandatory. Without proper DNS and reverse-proxy > routing, browser uploads will fail. For the bundled RustFS setup, ensure: 1. **Main domain**: `yourdomain.com` points to your server IP 2. **Files subdomain**: `files.yourdomain.com` points to your server IP 3. **Firewall**: Ports 80 and 443 are open in your server's firewall 4. **DNS propagation**: Allow time for DNS changes to propagate globally ## Docker Compose Configuration For manual setup, update your `docker-compose.yml`: ```yaml theme={null} services: formbricks: image: ghcr.io/formbricks/formbricks:latest environment: # ... other environment variables ... # S3 Storage Configuration S3_ACCESS_KEY: your_access_key S3_SECRET_KEY: your_secret_key S3_REGION: us-east-1 S3_BUCKET_NAME: your-bucket-name S3_ENDPOINT_URL: https://your-endpoint.com # Optional S3_FORCE_PATH_STYLE: 1 # For third-party services volumes: - uploads:/home/nextjs/apps/web/uploads/ # Still needed for temporary files ``` ## Security Considerations ### IAM User Permissions When using AWS S3 or S3-compatible storage providers, ensure that the IAM user associated with your `S3_ACCESS_KEY` and `S3_SECRET_KEY` credentials has the necessary permissions to interact with your bucket. Without proper permissions, file uploads and retrievals will fail. The following IAM policy grants the minimum required permissions for Formbricks to function correctly. This policy is also used in the bundled RustFS integration: ```json theme={null} { "Statement": [ { "Action": ["s3:DeleteObject", "s3:GetObject", "s3:PutObject"], "Effect": "Allow", "Resource": ["arn:aws:s3:::your-bucket-name/*"] }, { "Action": ["s3:ListBucket"], "Effect": "Allow", "Resource": ["arn:aws:s3:::your-bucket-name"] } ], "Version": "2012-10-17" } ``` > [!NOTE] > > Replace `your-bucket-name` with your actual S3 bucket name. The first statement grants object-level > operations (upload, retrieve, and delete files), while the second statement allows listing bucket contents. ### S3 Bucket Policy In addition to IAM user permissions, configure your S3 bucket with a least-privileged bucket policy to ensure security: 1. **Scoped Public Read Access**: Only allow public read access to specific prefixes where needed 2. **Restricted Write Access**: Only your Formbricks instance should be able to upload files 3. **CORS Configuration**: Allow requests from your Formbricks domain Example least-privileged S3 bucket policy: ```json theme={null} { "Statement": [ { "Action": "s3:GetObject", "Effect": "Allow", "Principal": "*", "Resource": "arn:aws:s3:::your-bucket-name/uploads/public/*", "Sid": "PublicReadForPublicUploads" }, { "Action": ["s3:PutObject", "s3:PutObjectAcl"], "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/formbricks-service" }, "Resource": "arn:aws:s3:::your-bucket-name/*", "Sid": "AllowFormbricksWrite" } ], "Version": "2012-10-17" } ``` > [!NOTE] > > Replace `your-bucket-name` with your actual bucket name and > `arn:aws:iam::123456789012:user/formbricks-service` with the ARN of your IAM user. This policy allows public > read access only to specific paths while restricting write access to your Formbricks service user. ### S3 CORS Configuration CORS (Cross-Origin Resource Sharing) must be configured on your S3 bucket to allow Formbricks to upload files using presigned POST URLs. Without proper CORS configuration, file uploads from the browser will fail. Configure CORS on your S3 bucket with the following settings: ```json theme={null} [ { "AllowedHeaders": ["*"], "AllowedMethods": ["POST", "GET", "HEAD", "DELETE", "PUT"], "AllowedOrigins": ["*"], "ExposeHeaders": ["ETag", "x-amz-meta-custom-header"], "MaxAgeSeconds": 3000 } ] ``` > [!NOTE] > > For production environments, consider restricting `AllowedOrigins` to your specific Formbricks domain(s) > instead of using `"*"` for better security. For example: `["https://app.yourdomain.com", > "https://yourdomain.com"]`. **How to configure CORS:** * **AWS S3**: Navigate to your bucket → Permissions → Cross-origin resource sharing (CORS) → Edit → Paste the JSON configuration * **DigitalOcean Spaces**: Navigate to your Space → Settings → CORS Configurations → Add CORS configuration → Paste the JSON * **RustFS (self-hosted)**: configured automatically by the bundled setup, or via a server-level env var for standalone deployments — see [RustFS CORS Configuration](#rustfs-cors-configuration) below. * **Other S3-compatible providers**: Refer to your provider's documentation for CORS configuration ### RustFS CORS Configuration RustFS supports CORS two ways: a **server-level** allow-list set via the `RUSTFS_CORS_ALLOWED_ORIGINS` environment variable on the RustFS server, and **per-bucket** CORS via the S3 `PutBucketCors` API (e.g. `rc bucket cors set`). **Bundled Formbricks setup** (the [one-click script](/docs/self-hosting/setup/one-click), driven by `docker/rustfs-init.sh`): CORS is configured for you. The bootstrap applies a per-bucket policy via `rc bucket cors set`, scoped to your Formbricks domain — nothing else to do. **Standalone RustFS** (managed separately from Formbricks): set `RUSTFS_CORS_ALLOWED_ORIGINS` on the RustFS server to the origin(s) you serve Formbricks from — your `WEBAPP_URL` — comma-separated for multiple values: ```env theme={null} # Set on the RustFS server, then restart RustFS RUSTFS_CORS_ALLOWED_ORIGINS=https://app.yourdomain.com ``` > [!NOTE] > > When `RUSTFS_CORS_ALLOWED_ORIGINS` is unset, the RustFS server emits **no** CORS headers at all, so browsers > block cross-origin uploads; a non-empty value is treated as an allow-list. So if browser uploads fail with a > CORS error while the file still appears in RustFS, this variable is most likely either unset or set to a value > that excludes your Formbricks origin — set it to (or add) your origin. Use an explicit origin list in > production; `*` allows all origins and should be avoided outside local testing. > > This changed in `1.0.0-beta.2`. Older images baked `RUSTFS_CORS_ALLOWED_ORIGINS=*` in, so leaving it unset > was permissive by default — and on versions up to `1.0.0-beta.1` the server reflected the caller's origin back > with `Access-Control-Allow-Credentials: true` > ([GHSA-x5xv-223c-8vm7](https://github.com/rustfs/rustfs/security/advisories/GHSA-x5xv-223c-8vm7)). The image no > longer bakes that value. If you relied on the old default, set this variable explicitly when you upgrade. > [!WARNING] > > For standalone deployments, prefer the server-level `RUSTFS_CORS_ALLOWED_ORIGINS` variable over manually applying > a per-bucket CORS policy: RustFS's support for the S3 `PutBucketCors` API has varied across releases and can > return "not implemented" on some builds. (The bundled bootstrap pins `rustfs/rustfs:1.0.0-rc.2`, on which > per-bucket `rc bucket cors set` is verified to work.) ### RustFS Security When using bundled RustFS: * Credentials are auto-generated and secure * Generated RustFS credentials are written to a local `.env` file; keep it private and restrict it to `0600` * Access is restricted through Traefik proxy * CORS is automatically configured * Rate limiting is applied to prevent abuse * A bucket policy with the least privileges is applied to the bucket * Prefer local SSD or NVMe-backed storage for `rustfs-data`, use XFS on dedicated host-managed disks when possible, and avoid NFS or other network filesystems for RustFS data * Back up the `rustfs-data` volume regularly, especially for single-server deployments * Ship RustFS and Formbricks container logs into your normal logging and alerting stack; the bundled setup does not provision centralized audit-log export or alerting for you ## Troubleshooting ### Common Issues **Files not uploading:** 1. Check that S3 credentials are correct 2. Verify bucket exists and is accessible 3. Ensure bucket permissions allow uploads from your server 4. Check network connectivity to S3 endpoint 5. We use S3 presigned URLs for uploads. Make sure your CORS policy allows presigned URL uploads; otherwise, uploads will fail. Some providers (e.g., Hetzner’s object storage) [require a specific CORS configuration](https://github.com/formbricks/formbricks/discussions/6641#discussioncomment-14574048). If you’re using the bundled RustFS setup, this is already configured for you. 6. **The file appears in your storage but Formbricks still reports “upload failed.”** This is the classic CORS symptom — the browser uploaded the file successfully but could not read the response. For RustFS, set `RUSTFS_CORS_ALLOWED_ORIGINS` to include your Formbricks origin (see [RustFS CORS Configuration](#rustfs-cors-configuration)). **Images not displaying in surveys:** 1. Verify bucket has public read access 2. Check CORS configuration allows requests from your domain 3. Ensure S3\_ENDPOINT\_URL is correctly set for third-party services **RustFS not starting:** 1. **Verify subdomain DNS**: Ensure `files.yourdomain.com` points to your server IP (this is the most common issue) 2. **Check DNS propagation**: Use tools like `nslookup` or `dig` to verify DNS resolution 3. **Verify ports**: Ensure ports 80 and 443 are open in your firewall 4. **SSL certificate**: Check that SSL certificate generation completed successfully 5. **Container logs**: Check Docker container logs: `docker compose logs rustfs` ### Testing Your Configuration To test if file uploads are working: 1. **Admin Panel**: Try uploading a Workspace logo in **Settings → Workspace → Appearance** 2. **Survey Editor**: Attempt to add a background image to a survey 3. **Question Types**: Create a 'File Upload' or 'Picture Selection' question 4. **Check Logs**: Monitor container logs for any storage-related errors ```bash theme={null} # Check Formbricks logs docker compose logs formbricks # Check RustFS logs (if using bundled RustFS) docker compose logs rustfs ``` For additional help, join the conversation on [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Third-party Integrations (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations Configure third-party integrations on a self-hosted Formbricks instance. Formbricks connects to third-party tools such as Slack, Notion, or Google Sheets on behalf of your users. On Formbricks Cloud we register and operate the OAuth apps behind those connections, so they work out of the box. A self-hosted instance talks to those services under your own identity instead, which means you register the OAuth app yourself and hand its credentials to your instance. > [!NOTE] > > Using Formbricks Cloud? You do not need any of this. Head to the [Cloud integration > guides](/docs/platform/features/integrations/overview) instead. ## Before you configure an integration **1. Know your public-facing URL** Every OAuth app needs a redirect URL that points back at your instance, built from your own `https://` rather than `app.formbricks.com`. The callback path differs per service, so take it from the guide you are following. **2. Serve Formbricks over HTTPS** Slack refuses to talk to an instance without a valid certificate, and the other providers expect HTTPS in production too. See [Custom SSL](/docs/self-hosting/configuration/custom-ssl) if you have not set this up yet. **3. Restart after changing environment variables** Credentials go into the same place as every other setting — see [Environment Variables](/docs/self-hosting/configuration/environment-variables). Restart your containers for new values to take effect. ## What each integration needs The integrations fall into two groups. The first four need credentials from an OAuth app you register with the third-party service. The last three connect from the other side — through a Formbricks API key or your instance URL — and need no server configuration at all. | Integration | What you register | Environment variables | | - | - | - | | [Airtable](/docs/self-hosting/configuration/integrations/airtable) | An OAuth integration in the Airtable Developer hub | `AIRTABLE_CLIENT_ID` | | [Google Sheets](/docs/self-hosting/configuration/integrations/google-sheets) | An OAuth client in a Google Cloud project | `GOOGLE_SHEETS_CLIENT_ID`, `GOOGLE_SHEETS_CLIENT_SECRET`, `GOOGLE_SHEETS_REDIRECT_URL` | | [Notion](/docs/self-hosting/configuration/integrations/notion) | A public Notion integration | `NOTION_OAUTH_CLIENT_ID`, `NOTION_OAUTH_CLIENT_SECRET` | | [Slack](/docs/self-hosting/configuration/integrations/slack) | A Slack app with bot scopes and public distribution | `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET` | | [n8n](/docs/self-hosting/configuration/integrations/n8n) | Nothing — n8n authenticates with a Formbricks API key | None | | [Zapier](/docs/self-hosting/configuration/integrations/zapier) | Nothing — Zapier authenticates with a Formbricks API key | None | | [ActivePieces](/docs/self-hosting/configuration/integrations/activepieces) | Nothing — point the connection at your instance URL | None | ## Configuration guides > [card] [Airtable](/docs/self-hosting/configuration/integrations/airtable) > > Send responses to an Airtable base. > [card] [Google Sheets](/docs/self-hosting/configuration/integrations/google-sheets) > > Send responses to a Google Sheet. > [card] [Notion](/docs/self-hosting/configuration/integrations/notion) > > Send responses to a Notion database. > [card] [Slack](/docs/self-hosting/configuration/integrations/slack) > > Post responses to a Slack channel. > [card] [n8n](/docs/self-hosting/configuration/integrations/n8n) > > Build automations on survey events with n8n. > [card] [Zapier](/docs/self-hosting/configuration/integrations/zapier) > > Connect Formbricks to thousands of apps on Zapier. > [card] [ActivePieces](/docs/self-hosting/configuration/integrations/activepieces) > > Build automations on survey events with ActivePieces. Once an integration is enabled on your instance, connecting it to a survey works exactly as it does on Formbricks Cloud. Follow the matching [Cloud guide](/docs/platform/features/integrations/overview) from there. > [!NOTE] > > For automations that stay inside Formbricks — without a third-party tool — use > [Workflows](/docs/workflows/overview) to trigger actions such as sending an email when a response is completed. Still struggling or something not working as expected? [Join our GitHub Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # ActivePieces (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/activepieces Learn how to configure ActivePieces integration in your survey for self-hosting instance. ## Setting Up ActivePieces with Self-Hosted Formbricks ### Prerequisites * A self-hosted Formbricks instance * Access to an ActivePieces account ### Configuration Steps For general setup instructions, refer to our [comprehensive ActivePieces integration guide](https://formbricks.com/docs/platform/features/integrations/activepieces). #### Important Note for Self-Hosting When following the main guide, pay special attention to **Step 3** where you create a new connection: Instead of using `app.formbricks.com` as your `APP_URL`, you must substitute this with your own self-hosted Formbricks instance URL. ![ActivePieces Connection Setup](https://mintcdn.com/formbricks/FxVXbfRFRc8kmKdj/images/self-hosting/configuration/integrations/activepieces/new-connection.webp?fit=max\&auto=format\&n=FxVXbfRFRc8kmKdj\&q=85\&s=3d0bff1738310a6452855bf238c2261c) ### Verification After configuring the connection: 1. Test the integration by submitting a sample survey 2. Verify that your ActivePieces workflow executes as expected 3. Check the logs if you encounter any issues ## Troubleshooting If you encounter issues with your ActivePieces integration: * Ensure your self-hosted Formbricks instance is accessible from the internet * Verify that you've entered the correct URL for your instance * Check that any necessary API keys are properly configured # Airtable (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/airtable Instantly populate your Airtable table with survey data The Airtable integration allows you to automatically send responses to an Airtable of your choice. > [!NOTE] > > If you are using Formbricks Cloud, you will need to configure this > integration differently. Please follow this guide > [here](/docs/platform/features/integrations/airtable) to set it up. ## Setup Enabling the Airtable Integration in a self-hosted environment requires creating an airtable account and changing the environment variables of your Formbricks instance. > [!NOTE] > > If your Airtable app is in development use, please ensure that the email used in the Airtable integration matches the email used in the Airtable OAuth app. To use other email addresses, you need to fill this information in your OAuth app settings again: > > ![airtable img](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738251900/image_eoaxg3.jpg) * Go to the [Airtable](https://airtable.com) and create a new account if you dont already have one. * Click on user icon on top left and open to **Developer hub** ![opendevhub](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252268/image_l3w3an.jpg) * Navigate to OAuth integrations and click on **Register an OAuth integrations** ![new](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252316/image_xmqyee.jpg) * Select a name for your integration and also add a redirect URL which will be `/api/v1/integrations/airtable/callback` ![air](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252498/image_ufbmot.jpg) * . Now fill some basic details about your integrations and then go to scope section. You need to **enable** 5 scopes: * data.records:read * data.records:write * schema.bases:read * schema.bases:write * user.email:read ![tables](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252641/image_veqzki.jpg) * Click on the "Save" button and you are done * Now just copy **Client ID** for your integration & add it to your **Formbricks environment variables** as in the docker compose file: * `AIRTABLE_CLIENT_ID` Voila! You have successfully enabled the Airtable integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in [Airtable Integration with Formbricks](/docs/platform/features/integrations/airtable) section to link an Airtable with Formbricks. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Google Sheets (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/google-sheets Instantly populate your Google Sheet table with survey data The Google Sheets integration allows you to automatically send responses to an Google Sheets of your choice. > [!NOTE] > > If you are using Formbricks Cloud, you will need to configure this > integration differently. Please follow this guide > [here](/docs/platform/features/integrations/google-sheets) to set it up. ## Setup Integrating Google Sheets with a self-hosted Formbricks instance requires configuring Google Cloud and updating your environment variables. > [!NOTE] > > If your Google Cloud Console project has a publishing status of "Testing" your refresh token will expire after 7 days. To avoid that, you need to change the publishing status to "Production". [Google OAuth 2.0 documentation](https://developers.google.com/identity/protocols/oauth2?hl=en#expiration) * Go to the [Google Cloud Console](https://console.cloud.google.com/) and **create a new project**. * Enable necessary APIs: * Now select the project you just created and go to the **APIs & Services** section. * Click on the **Enable APIs and Services** button and search for **Google Sheets API** and enable it. * Configure OAuth Consent Screen: * Go to **OAuth Consent screen** and select the appropriate User Type (External or Internal). Select **Internal** if you want only the users of your Google Workspace to be able to use the integration. * Fill the required details: * App name: Name displayed during OAuth authentication. * User support email and Developer contact information: Your contact details for support. * Click on **Save and Continue**. * Add required Scopes: * Click on the **Add or Remove Scopes** button and add the scopes: * [`https://www.googleapis.com/auth/userinfo.email`](https://www.googleapis.com/auth/userinfo.email) * [`https://www.googleapis.com/auth/spreadsheets`](https://www.googleapis.com/auth/spreadsheets) * Click on the **Update** button. Verify the scopes and click on the **Save and Continue** button. * Skip the **Test Users** section and click on the **Save and Continue** button. * View the OAuth Consent Screen summary and click on the **Back to Dashboard** button. * Register OAuth Client: * Navigate to **Credentials** > **Create Credentials** > **OAuth Client ID**. * Select **Web Application** and set: * Name: Name of the OAuth Client ID. * Authorized JavaScript Origins: `https://` * Authorized redirect URIs: `https:///api/google-sheet/callback` * Save and note the Client ID and Client Secret. * Copy the Client ID and Client Secret and set them as environment variables in your Formbricks instance: * `GOOGLE_SHEETS_CLIENT_ID` * `GOOGLE_SHEETS_CLIENT_SECRET` * `GOOGLE_SHEETS_REDIRECT_URL` Now just copy **GOOGLE\_SHEETS\_CLIENT\_ID**, **GOOGLE\_SHEETS\_CLIENT\_SECRET** and **GOOGLE\_SHEETS\_REDIRECT\_URL** for your integration & add it to your **Formbricks environment variables** as in the docker compose file: * `GOOGLE_SHEETS_CLIENT_ID` * `GOOGLE_SHEETS_CLIENT_SECRET` * `GOOGLE_SHEETS_REDIRECT_URL` Voila! You have successfully enabled the Google Sheets integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in [Google Sheets Integration with Formbricks](/docs/platform/features/integrations/google-sheets) section to link a Google Sheet with Formbricks. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # n8n (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/n8n Set up automations with your self-hosted n8n instance. The n8n integration allows you to create automations based on survey responses. > [!NOTE] > > If you are using Formbricks Cloud, you will need to configure this > integration differently. Please follow this guide > [here](/docs/platform/features/integrations/n8n) to set it up. ## Setup Enabling the n8n integration in a self-hosted environment requires a new workflow setup using n8n and changing the environment variables of your Formbricks instance. * Setup your n8n workflow: Go to [n8n.io](https://n8n.io) and create a new workflow. Search for “Formbricks” to get started: ![n8n](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252710/image_rp86wt.jpg) * **Connect Formbricks with n8n**: Now, you have to connect n8n with Formbricks via an API Key: ![CreateNewCredentialBtn](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252823/image_kyyvur.jpg) * Click on Create New Credentail button to add your host and API Key ![AddAPIKey](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252907/image_a1fmyc.jpg) Now you need an API key. Please refer to the [API Key Setup](/docs/api-reference/generate-key) page to learn how to create one. Once you copied it in the API Key field, hit Save button to test the connection and save the credentials. ![connectiontest](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738252980/image_asox5o.jpg) * Select Event: Next, you can choose the event you want to trigger the node on. You can select multiple events: ![select event](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253186/image_xrjjrh.jpg) Here, we are adding `Response Finished` as an event, which will trigger when the survey has been filled out. * Select Survey: Next, you can choose from all the surveys you have created in this workspace. You can select multiple surveys: ![select survey](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253219/image_hbubu7.jpg) Here, we are selecting two surveys. ![two survey](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253296/image_lbb4hw.jpg) * Test your trigger: In order to set up n8n you'll need a test response in the selected survey. This allows you to select the individual values of each response in your workflow. ![test trigger](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253356/image_ogjya8.jpg) Next, click on Listen for event button. ![listen](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253388/image_pzerrp.jpg) Then, go to the survey which you selected. Fill it out, and wait for the particular event to trigger (in this case it's `Response Finished`). Once the event is triggered you will see the response that you filled out in the survey. ![response](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253435/image_c0hyo9.jpg) Now you have all the data you need at hand. The next steps depend on what you want to do with it. In this tutorial, we will send submissions to a discord channel: 1. Add Discord to your workflow: Click on the plus and search `Discord`. ![discord](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253513/image_hwld7h.jpg) Fill in the `Webhook URL` and the `Content` that you want to receive in the respective discord channel. Next, click on `Execute Node` button to test the node. ![webhook](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253594/image_avxxkl.jpg) Once the execution is successful, you'll receive the content in the discord channel. ![success](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253753/image_qlxvpv.jpg) Voila! You have successfully enabled the n8n integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Formbricks Integrations](/docs/platform/features/integrations/n8n) section to know more about the capabilities with Formbricks with n8n. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Notion (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/notion Instantly populate a Notion database with survey data The Notion integration allows you to automatically send responses to a Notion database of your choice. > [!NOTE] > > If you are using Formbricks Cloud, you will need to configure this > integration differently. Please follow this guide > [here](/docs/platform/features/integrations/notion) to set it up. ## Setup Enabling the Notion Integration in a self-hosted environment requires a setup using Notion account and changing the environment variables of your Formbricks instance. * Sign up for a [Notion](https://www.notion.so/) account, if you don't have one already. * Go to the [my integrations](https://www.notion.so/my-integrations) page and click on **New integration**. * Fill up the basic information like **Name**, **Logo** and click on **Submit**. * Now, click on **Distribution** tab on the sidebar. A text will appear which will ask you to make the integration public. Click on that toggle button. A form will appear below the text. * Now provide it the details such as requested. Under **Redirect URIs** field: * If you are running formbricks locally, you can enter `http://localhost:3000/api/v1/integrations/notion/callback`. * Or, you can enter `https:///api/v1/integrations/notion/callback` * Once you've filled all the necessary details, click on **Submit**. * Now just copy from the screen the **Client ID** and **Client secret** for your integration & add it to your **Formbricks environment variables** as in the docker compose file: * `NOTION_OAUTH_CLIENT_ID` - OAuth Client ID * `NOTION_OAUTH_CLIENT_SECRET` - OAuth Client Secret Voila! You have successfully enabled the Notion integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in [Notion Integration with Formbricks](/docs/platform/features/integrations/notion) section to link your Notion with Formbricks. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Slack (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/slack Send survey responses automatically to Slack workspace. Send survey responses automatically to Slack workspace. > [!NOTE] > > If you are using Formbricks Cloud, you will need to configure this > integration differently. Please follow this guide > [here](/docs/platform/features/integrations/slack) to set it up. ## Setup Enabling the Slack Integration in a self-hosted environment requires a setup using slack workspace account and changing the environment variables of your Formbricks instance. > [!NOTE] > > Make sure your self-hosted Formbricks instance works with SSL as Slack requires it. * Create a Slack workspace if you don't have one already. * Go to the [Your apps](https://api.slack.com/apps) page and **Create New App**. * Click on **From Scratch** and provide the **App Name** and select your workspace in **Pick a workspace to develop your app in:** dropdown. Click on **Create App**. * Go to the **OAuth & Permissions** tab on the sidebar and add the following **Bot Token Scopes**: * `channels:read` * `groups:read` * `chat:write` * `chat:write.public` * `chat:write.customize` * Add the **Redirect URLs** under **OAuth & Permissions** tab. You can add the following URLs: * If you are running formbricks locally, you can enter `https://localhost:3000/api/v1/integrations/slack/callback`. * Or, you can enter `https:///api/v1/integrations/slack/callback` * Now, click on **Install to Workspace** and **Allow** the permissions. * Go to the **Basic Information** tab on the sidebar and copy the **Client ID** and **Client Secret**. Copy them & add it to your **Formbricks environment variables** as in the docker compose file: * `SLACK_CLIENT_ID` - OAuth Client ID * `SLACK_CLIENT_SECRET` - OAuth Client Secret * Now, you need to enable the public distribution of your app. Go to the **Basic Information** tab and click on the **Manage distribution** button and click on the "Distribute App". * Scroll down to the **Share your app with other workspaces** section, complete the checklist and click on the **Activate public distribution** button. Voila! You have successfully enabled the Slack integration in your self-hosted Formbricks instance. Now you can follow the steps mentioned in the [Slack Integration](/docs/platform/features/integrations/slack) section to link a Slack workspace with Formbricks. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Zapier (On Premise) Source: https://formbricks.com/docs/self-hosting/configuration/integrations/zapier Set up automations with your self-hosted Zapier instance. The Zapier integration allows you to create automations based on survey responses. > [!NOTE] > > If you are using Formbricks Cloud, you will need to configure this > integration differently. Please follow this guide > [here](/docs/platform/features/integrations/zapier) to set it up. ## Setup Setup your Zap: Go to [zapier.com](https://zapier.com/) and create a new Zap. Search for “Formbricks” to get started: ![setup](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253827/image_dj64ty.jpg) Then, choose the event you want to trigger the Zap on: ![trigger event](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738253929/image_p9kpxj_qxz2hw.jpg) Connect Formbricks with Zapier: You have to connect Zapier with Formbricks via an API Key: ![connect](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738254011/image_fqjrtl.jpg) ![second](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738254061/image_apgw1y.jpg) Now you need an API key. Please refer to the [API Key Setup](/docs/api-reference/generate-key) page to learn how to create one. Once you copied it in the newly opened Zapier window, you will be connected: ![last](https://res.cloudinary.com/dwdb9tvii/image/upload/v1738254089/image_kzpadl.jpg) Voila! You have successfully configured Zapier to work with your self-hosted Formbricks instance. Now, you can follow the steps mentioned in the [Zapier Integration](https://formbricks.com/docs/developer-docs/integrations/zapier) section to connect it with your Formbricks app and see it live. Still struggling or something not working as expected? [Join our Github Discussions](https://github.com/formbricks/formbricks/discussions) and we'd be glad to assist you! # Job Runner Source: https://formbricks.com/docs/self-hosting/configuration/job-runner Configure and operate the BullMQ background-job worker in self-hosted Formbricks Formbricks uses a shared BullMQ Job Runner for asynchronous work such as response processing, survey scheduling, and [Workflows](/docs/workflows/overview). Formbricks starts the worker inside the web application by default, so a standard self-hosted deployment does not need a separate worker container. > [!NOTE] > > Every Formbricks web process starts one worker with a concurrency of one by default. You can tune these > values with environment variables after you have measured your workload. ## Runtime architecture The web application creates jobs and consumes them from a shared Redis-backed queue: * Queue name: `background-jobs` * Redis key prefix: `{formbricks:jobs}` * Worker startup: Next.js server instrumentation * Default workers per web process: `1` * Default concurrent jobs per worker: `1` Redis is also used to coordinate recurring jobs. The web process retries worker and recurring-job registration after 30 seconds if startup fails. > [!NOTE] > > Changing a recurring job's cron pattern, interval or time zone — for example by setting > `SURVEY_SCHEDULING_TIME_ZONE` — updates the schedule as soon as the process restarts, but takes effect from > the **following** run: the run already queued keeps its previous timing. For the daily sweeps that can be up > to 24 hours. Inspecting the schedule in Redis shows the new value immediately, so a job firing once more at > the old hour after a restart is expected rather than a sign the setting was ignored. ## Current background jobs Current workloads on the shared queue include: | Workload | Job names | Purpose | | - | - | - | | Response pipeline | `response-pipeline.process` | Processes asynchronous response pipeline events and fans out one delivery job per webhook. | | Webhook delivery | `webhook-delivery.process` | Delivers one response event to one webhook, with its own retry budget. | | Survey scheduling | `survey-scheduling.reconcile` | Reconciles scheduled survey state. | | Survey archive | `survey-archive-purge.process` | Permanently deletes surveys past the archive retention window. | | Usage telemetry | `usage-telemetry.process` | Sends the instance's daily usage update. | | Workflows | `workflow-run.process`, `workflow-run.reconcile` | Executes workflow runs and recovers stalled runs. | These are current examples rather than a fixed list. Future Formbricks features can use the same Job Runner for additional background work. ## Configure the Job Runner **1. Connect Redis** Set `REDIS_URL` to a Redis instance reachable by every Formbricks web replica. ```env theme={null} REDIS_URL=redis://redis:6379 ``` All replicas must use the same Redis instance so they share the BullMQ queue and recurring schedules. **2. Keep the in-process worker enabled** `BULLMQ_WORKER_ENABLED` is enabled by default outside test environments. You can omit it or set it explicitly: ```env theme={null} BULLMQ_WORKER_ENABLED=1 BULLMQ_WORKER_COUNT=1 BULLMQ_WORKER_CONCURRENCY=1 ``` Restart every Formbricks web process after changing these values. **3. Verify startup** Check the web process logs for the exact message `BullMQ runtime started`. Its structured fields include the queue name, Redis prefix, worker count, and worker concurrency. ## Scale across replicas Each web replica starts its own in-process workers and connects to the same queue. BullMQ coordinates job claims so one available worker ordinarily processes a queued job. Total processing capacity is approximately: ```text theme={null} web replicas x BULLMQ_WORKER_COUNT x BULLMQ_WORKER_CONCURRENCY ``` Increase concurrency gradually and monitor database, Redis, and downstream service capacity. Adding replicas also adds workers, so account for both scaling controls. Every response now produces one job per matching webhook in addition to the pipeline job itself, and each delivery holds a worker slot for up to `WEBHOOK_DELIVERY_TIMEOUT_MS` (5 seconds by default). Because those jobs share the queue's concurrency, the deliveries for one response run **as concurrency allows rather than all at once**: at the default of one, ten webhooks are delivered one after another, so the last receiver is contacted later than it would have been when the pipeline job posted to all of them itself. Raise `BULLMQ_WORKER_CONCURRENCY` if your workspaces have several webhooks per survey, or receivers that are slow to answer — otherwise a burst of deliveries also delays pipeline and workflow jobs behind it. Each concurrent slot needs a database connection, so raise the connection pool alongside it. ## Retry behavior BullMQ applies the following defaults to background jobs: | Behavior | Current default | | - | - | | Attempts | 3 | | Backoff | Exponential, starting at 5 seconds | | Completed job retention | Up to 24 hours or 1,000 jobs | | Failed job retention | Up to 7 days or 5,000 jobs | Individual workloads can add their own recovery behavior on top of these queue-level retries. Webhook deliveries override the queue defaults with **5 attempts** and an **exponential backoff starting at 30 seconds** (retries after roughly 30 seconds, 1, 2 and 4 minutes). A receiver that returns a 4xx status other than 408 or 429, or a webhook URL that fails the SSRF policy, fails the job immediately without retrying; network errors, timeouts, DNS failures, 408, 429 and 5xx statuses are retried. Deliveries to a webhook that was deleted or unsubscribed from the event while the job was queued complete without a request. Redirects depend on `DANGEROUSLY_ALLOW_WEBHOOK_INTERNAL_URLS`. Left unset — the default, and the safe setting — a 3xx response is refused rather than followed, and the attempt is retried in case the receiver's configuration is fixed. With the variable set, redirects are followed instead: note that following one turns the POST into a GET, which many receivers answer with `405`, and a 405 is then treated as a permanent rejection. ## Workflows Workflows use the shared Job Runner to execute runs and reconcile runs that lost their queue or worker handoff. No additional worker process is required. ### Configure action dependencies Configure the services required by the workflow actions you use. For example, the **Send email** action uses your deployment's SMTP transport and sender. Configure `SMTP_HOST`, `SMTP_PORT`, `MAIL_FROM`, `MAIL_FROM_NAME`, and any authentication or TLS variables required by your provider. See [SMTP Configuration](/docs/self-hosting/configuration/smtp) for the complete setup. ### Retry and recovery behavior > [!WARNING] > > Workflow delivery supports retries and recovery; it is not an exactly-once guarantee. Formbricks uses > deterministic job IDs and guarded workflow run and step transitions to make redispatch safe, but operators > should still expect jobs to be retried after transient failures. A recurring reconciliation job runs every three minutes to recover workflow runs that lost their queue or worker handoff: * Queued runs older than two minutes are eligible for redispatch. * Queued runs older than 24 hours are marked as failed instead of being redispatched indefinitely. * Running runs with no executor activity for one hour are marked as failed and unfinished steps are skipped. * Each reconciliation sweep processes at most 250 queued and 250 running candidates. Larger backlogs drain over subsequent sweeps. When reconciliation changes runs, Formbricks writes `Workflow run reconciliation acted` with structured counts for redispatched, aged-out, and recovered runs. ### Troubleshoot workflow jobs If workflow runs stay queued after the Job Runner is healthy: 1. Search for `BullMQ job failed` entries where `jobName` is `workflow-run.process` or `workflow-run.reconcile`. 2. Search for `Workflow run reconciliation acted` and inspect the queued and stuck-running counts. 3. Open the workflow's **Runs** view to inspect the run status and step-level error. ## Use a custom external worker The default in-process worker is the supported setup. Formbricks does not ship a standalone worker command or container. The external-worker flags are only for custom deployments that provide their own consumer and register the complete Formbricks application job handlers. In such a custom deployment, configure the web/API processes to keep enqueueing without starting local workers: ```env theme={null} BULLMQ_WORKER_ENABLED=0 BULLMQ_EXTERNAL_WORKER_ENABLED=1 REDIS_URL=redis://redis:6379 ``` > [!WARNING] > > `BULLMQ_EXTERNAL_WORKER_ENABLED=1` only keeps queueing enabled. It does not provide, start, or deploy a > worker. Only use this configuration after your custom consumer registers the complete Formbricks job > handlers and is already consuming the same queue. Otherwise, background jobs will remain queued. ## Troubleshoot the Job Runner Formbricks writes structured logs to stdout and stderr. Search the `msg` field for these exact messages: | Log message | What to check | | - | - | | `BullMQ runtime started` | The worker is connected. Verify its `workerCount`, `workerConcurrency`, `queueName`, and `prefix` fields. | | `BullMQ Redis connection error` | Verify `REDIS_URL`, DNS, network access, Redis credentials, and TLS settings. | | `BullMQ queue error` | The producer queue emitted an error. Review the attached `err` field; usually the same causes as above. | | `Failed to start BullMQ runtime` | Review the attached `err` field, then confirm Redis is reachable from the web process. | | `BullMQ worker registration failed` | Worker startup failed. Formbricks schedules another attempt after 30 seconds. | | `BullMQ worker registration retry scheduled` | A startup retry is pending. Fix the underlying Redis or configuration error before it runs. | | `BullMQ recurring job registration failed` | Recurring schedules could not be registered. Check Redis connectivity. | | `BullMQ recurring job registration retry scheduled` | A recurring-schedule registration retry is pending for 30 seconds. | | `BullMQ job failed` | Inspect `jobName`, `jobId`, `attemptsMade`, and `err`. The job may retry until all its attempts are used (three by default, five for `webhook-delivery.process`). | | `Webhook delivery failed; retry scheduled` | One webhook delivery attempt failed and BullMQ will retry it. Inspect `webhookId`, `webhookUrlHost`, `statusCode`, `reason`, and `attempt` of `maxAttempts`. Usually the receiver is down or slow; nothing to do unless it keeps failing. | | `Webhook delivery failed; retries exhausted` | The last attempt for a webhook delivery failed; the event was not delivered. Same fields as above. Check the receiver, then re-send from the source system if needed — Formbricks does not replay exhausted deliveries. | | `Webhook delivery failed permanently` | The receiver rejected the request (4xx) or the webhook URL failed the SSRF policy, so no retry was attempted. Fix the receiver or the webhook URL; `reason` names the cause. | | `Webhook delivery skipped: webhook deleted` | The webhook was deleted after the event was queued. Expected after deleting a webhook with deliveries in flight. | | `Webhook delivery skipped: webhook no longer subscribed to this event` | The webhook's triggers or surveys were changed after the event was queued. Expected after editing a webhook with deliveries in flight. | | `Webhook delivery could not load the webhook and will be retried` | The database refused the webhook lookup, so no request was made and the attempt is retried. Check database health and the connection pool; the companion message names pool exhaustion explicitly. | | `Dropping BullMQ job with no registered processor: its schedule outlived the code that handled it` | A schedule in Redis outlived the build that handles it — typically after a rollback to a version without that feature. The job is completed rather than retried, so it does not accumulate in the failed set. Redeploy the build that owns `jobName`, or remove the stale schedule from Redis. | | `Dropping BullMQ job with no registered processor` for `webhook-delivery.process` | Seen only while upgrading to the first version that fans webhook delivery out into its own job: replicas still on the older build share the queue but do not know the name, so they complete the job **without delivering it** — the event is not retried and cannot be replayed. It stops as soon as every replica runs the new build. Upgrade during a quiet period if losing a few minutes of webhook events matters, or scale to a single replica for the upgrade. | If background jobs stay queued: 1. Confirm `REDIS_URL` is present and identical on all web replicas. 2. Confirm at least one in-process worker is enabled, or that a compatible external worker is running. 3. Look for `BullMQ runtime started` after the latest deployment or restart. 4. Check Redis connection and `BullMQ job failed` logs. 5. Use the `jobName` field to identify the affected workload and continue in its feature-specific logs or UI. When OpenTelemetry metrics are enabled (`PROMETHEUS_ENABLED=1` or `OTEL_EXPORTER_OTLP_ENDPOINT`), webhook deliveries also emit `formbricks.webhook.delivery.total` (a counter with `outcome`, `event` and `status_class` attributes) and `formbricks.webhook.delivery.duration` (a histogram in milliseconds), so delivery failure rates and receiver latency can be graphed and alerted on without reading logs. See [Monitoring](/docs/self-hosting/setup/monitoring) for how to scrape them. See [Environment Variables](/docs/self-hosting/configuration/environment-variables) for every Job Runner setting and [Monitoring](/docs/self-hosting/setup/monitoring) for log collection guidance. # Rate Limiting Source: https://formbricks.com/docs/self-hosting/configuration/rate-limiting Current request rate limits in Formbricks Formbricks applies request rate limits to protect against abuse and keep API usage fair. Starting with Formbricks v5, rate limiting is split across two layers: * Envoy Gateway for public and API-key routes that can be enforced at ingress * The application server for remaining session-authenticated routes, server actions, and other flows Envoy does not currently cover > [!WARNING] > > Formbricks v5 removes application-level rate limiting for several routes that are now expected to be > protected by Envoy Gateway. If you self-host Formbricks without Envoy or an equivalent edge rate limiter, > those routes will no longer be throttled by the application server after upgrading. > [!NOTE] > > For the full self-hosted upgrade checklist, use this page together with the > [v5 migration guide](/docs/self-hosting/advanced/migration#v5). Rate limits are scoped by identifier, depending on the endpoint and enforcement layer: * IP hash (for unauthenticated/client-side routes and public actions) * API key ID (for Envoy-managed and app-managed authenticated API calls) * User ID (for authenticated session-based calls and server actions) * Organization ID (for follow-up email dispatch and invitation budgets) When a limit is exceeded, the API returns `429 Too Many Requests`. ## v5 Migration Note Before upgrading to Formbricks v5: * deploy Envoy Gateway or an equivalent edge rate limiter for the covered routes below * keep application Redis/Valkey enabled for the remaining app-enforced limits * expect covered routes to emit gateway `429`s instead of the legacy app JSON `429`s For the current source of truth on covered routes and thresholds, use this page together with your deployment configuration and the [v5 migration guide](/docs/self-hosting/advanced/migration#v5). ## Envoy-Managed Limits These limits are expected to be enforced at the gateway layer in Formbricks v5 and later: | **Route Group** | **Limit** | **Window** | **Identifier** | | - | - | - | - | | `POST /api/auth/callback/credentials` | 40 requests | 1 hour | IP hash | | `POST /api/auth/callback/token` | 10 requests | 1 hour | IP hash | | `GET, POST, PUT, PATCH, DELETE /api/v1/management/*` (API key auth only) | 100 requests | 1 minute | API key ID | | `POST /api/v1/management/storage` (API key auth only) | 5 requests | 1 minute | API key ID | | `GET, POST, PUT, PATCH, DELETE /api/v1/webhooks/*` (API key auth only) | 100 requests | 1 minute | API key ID | | `GET /api/v1/client/[workspaceId]/environment` | 100 requests | 1 minute | IP hash | | `POST /api/v1/client/[workspaceId]/responses` | 100 requests | 1 minute | IP hash | | `PUT /api/v1/client/[workspaceId]/responses/[responseId]` | 100 requests | 1 minute | IP hash | | `POST /api/v1/client/[workspaceId]/displays` | 100 requests | 1 minute | IP hash | | `POST /api/v1/client/[workspaceId]/user` | 100 requests | 1 minute | IP hash | | `POST /api/v1/client/[workspaceId]/storage` | 5 requests | 1 minute | IP hash | | `POST /api/v2/client/[workspaceId]/responses` | 100 requests | 1 minute | IP hash | | `PUT /api/v2/client/[workspaceId]/responses/[responseId]` | 100 requests | 1 minute | IP hash | | `POST /api/v2/client/[workspaceId]/displays` | 100 requests | 1 minute | IP hash | | `POST /api/v2/client/[workspaceId]/storage` | 5 requests | 1 minute | IP hash | | `DELETE /storage/[workspaceId]/public/[fileName]` (API key auth only) | 5 requests | 1 minute | API key ID | | `DELETE /storage/[workspaceId]/private/[fileName]` (API key auth only) | 5 requests | 1 minute | API key ID | Session-authenticated `/api/v1/management/*`, `/api/v1/management/me`, `/api/v1/management/storage`, and `DELETE /storage/...` requests are **not** covered by the current Envoy policies and remain app-enforced. ## App-Enforced Limits These are the limits that still run inside the Formbricks application server: | **Config** | **Limit** | **Window** | **Identifier** | **Used For** | | - | - | - | - | - | | `auth.signup` | 30 requests | 60 minutes | IP hash | Signup server action | | `auth.forgotPassword` | 5 requests | 60 minutes | IP hash | Forgot password server action | | `auth.forgotPasswordPerAccount` | 3 emails | 60 minutes | User ID | Password-reset and SSO sign-in-hint emails to one account, however many IPs ask; once spent, further requests get the same answer but no email | | `auth.verifyEmail` | 10 requests | 60 minutes | IP hash | Resend verification server action | | `api.v1` | 100 requests | 1 minute | Session user ID | Session-authenticated v1 management routes, `/api/v1/management/me`, and `/api/v1/integrations/*` | | `api.v2` | 100 requests | 1 minute | API key ID | Authenticated v2 API wrapper outside the Envoy-managed `/api/v2/client/*` subset | | `api.v3` | 100 requests | 1 minute | API key ID or session user ID | v3 API wrapper | | `api.client` | 100 requests | 1 minute | IP hash | Uncovered client routes such as `GET /api/v1/client/og`, `GET /api/v2/client/[workspaceId]/environment`, and `POST /api/v2/client/[workspaceId]/user` | | `storage.upload` | 5 requests | 1 minute | Session user ID | Session-authenticated `POST /api/v1/management/storage` | | `storage.delete` | 5 requests | 1 minute | Session user ID | Session-authenticated `DELETE /storage/[workspaceId]/[accessType]/[fileName]` | | `actions.emailUpdate` | 3 requests | 60 minutes | User ID | Profile email update action | | `actions.inviteMember` | 50 recipients | 24 hours | Organization ID | Single, bulk, onboarding, and resend invite actions | | `actions.inviteMemberPerUser` | 50 recipients | 24 hours | User ID | The same invite actions, counted for the inviting user across all of their organizations | | `actions.createOrganization` | 5 requests | 24 hours | User ID | Organization creation actions (onboarding and the organization switcher) | | `actions.surveyFollowUp` | 50 requests | 60 minutes | Organization ID | Survey follow-up email processing | | `actions.sendLinkSurveyEmail` | 10 requests | 60 minutes | IP hash | Link survey email send action | | `actions.licenseRecheck` | 5 requests | 1 minute | User ID | Enterprise license recheck action | Invite limits count successfully created or refreshed invites. A bulk request for 25 people consumes 25 units only when all 25 invites are created; recipients who are already members, already invited, or otherwise fail do not consume the daily budget. Self-hosters can change the limit with `INVITE_RATE_LIMIT_PER_24_HOURS`; Formbricks Cloud organizations with the `bulk-invite` entitlement receive a limit of 500 recipients. The same allowance also applies to each inviting user across all of their organizations, so creating another organization does not reset it. ## Explicit Envoy Exclusions The current Envoy policy set explicitly excludes these routes: * `GET /api/v1/client/og` (still covered by the app-level `api.client` limiter) * `GET /api/v2/health` (not rate-limited) * `OPTIONS` requests (not rate-limited) ## 429 Response Shape Application-generated v1 `429`s return: ```json theme={null} { "code": "too_many_requests", "details": {}, "message": "Maximum number of requests reached. Please try again later." } ``` Application-generated v2/v3 `429`s return: ```json theme={null} { "error": { "code": 429, "message": "Too Many Requests" } } ``` Envoy-generated `429`s are gateway responses and should include an `x-envoy-ratelimited` header. Their exact body shape is not the same stability contract as the in-app JSON responses above. ## Disabling Rate Limiting For self-hosters, rate limiting can be disabled if necessary. We strongly recommend keeping it enabled in production. Set: ```bash theme={null} RATE_LIMITING_DISABLED=1 ``` After changing this value, restart the server. This setting disables only the **application-level** limiter. It does **not** disable Envoy rate-limit policies. ## Operational Notes * Redis/Valkey is required for the application-level limiter (`REDIS_URL`). * If you deploy Envoy rate limiting, use a dedicated Redis/Valkey backend for Envoy instead of sharing the app cache. * If application Redis is unavailable at runtime, app rate-limiter checks currently fail open (requests are allowed through without enforcement). * Client storage upload rate limits count signed upload URL issuance, not successful object creation in S3-compatible storage. * Authentication failure audit logging uses a separate throttle (`shouldLogAuthFailure()`) and is intentionally **fail-closed**: when Redis is unavailable or errors occur, audit log entries are **skipped entirely** rather than written without throttle control. This prevents spam while preserving the hash-integrity chain required for compliance. In other words, if Redis is down, no authentication-failure audit logs will be recorded—requests themselves are still allowed (fail-open rate limiting above), but the audit trail for those failures will not be written. # SMTP Configuration Source: https://formbricks.com/docs/self-hosting/configuration/smtp Set up email functionality for your self-hosted Formbricks instance By default, Formbricks doesn't include an SMTP server for sending emails. However, you can easily configure your self-hosted instance to use your own email provider through environment variables. ## Why Configure SMTP? Setting up an SMTP server enables important email functionality in Formbricks, including: * Email verification for new accounts * Password reset emails * Team member invitation emails * Survey response notifications ## Email Configuration Options Formbricks uses Nodemailer to send emails and supports various SMTP providers like: * AWS SES * SendGrid * Mailgun * Gmail (for low volume) * Custom SMTP servers * Other SMTP providers ## Required Environment Variables To enable email functionality, configure the following environment variables: ```bash theme={null} # Basic SMTP Configuration MAIL_FROM=noreply@yourdomain.com MAIL_FROM_NAME=Formbricks SMTP_HOST=smtp.yourprovider.com SMTP_PORT=587 SMTP_SECURE_ENABLED=0 SMTP_REQUIRE_TLS=1 SMTP_REJECT_UNAUTHORIZED_TLS=1 SMTP_USER=your_username SMTP_PASSWORD=your_password ``` Additional optional settings: ```bash theme={null} # Use SMTP_SECURE_ENABLED=1 for implicit TLS (typically port 465). # Use SMTP_REQUIRE_TLS=1 to require STARTTLS on non-implicit TLS connections (typically port 587). # SMTP_REQUIRE_TLS defaults to 0 so plaintext local relays remain supported. # If set to 0, the server won't require authentication SMTP_AUTHENTICATED=1 # Verify the SMTP server certificate against trusted CAs (default and recommended) SMTP_REJECT_UNAUTHORIZED_TLS=1 ``` > [!WARNING] > > Do not set `SMTP_REJECT_UNAUTHORIZED_TLS=0` in production. It disables SMTP server certificate verification > and makes encrypted connections vulnerable to an active man-in-the-middle attack. If your SMTP server uses a > private certificate authority, mount that CA certificate into the Formbricks container and add it to Node.js' > trust store instead. ## Trusting A Private Certificate Authority Store the CA certificate as a PEM file, mount it read-only, and set `NODE_EXTRA_CA_CERTS` to the path inside the container. Keep `SMTP_REJECT_UNAUTHORIZED_TLS=1`. For Docker Compose, add the following to the Formbricks service: ```yaml theme={null} volumes: - ./certs/smtp-ca.pem:/etc/ssl/formbricks-ca/smtp-ca.pem:ro environment: NODE_EXTRA_CA_CERTS: /etc/ssl/formbricks-ca/smtp-ca.pem SMTP_REJECT_UNAUTHORIZED_TLS: 1 ``` For Kubernetes, create a ConfigMap containing the public CA certificate: ```sh theme={null} kubectl create configmap formbricks-smtp-ca \ --from-file=smtp-ca.pem=./smtp-ca.pem \ -n formbricks ``` Then mount it with the Helm chart: ```yaml theme={null} deployment: env: NODE_EXTRA_CA_CERTS: /etc/ssl/formbricks-ca/smtp-ca.pem SMTP_REJECT_UNAUTHORIZED_TLS: "1" extraVolumes: - name: smtp-ca configMap: name: formbricks-smtp-ca extraVolumeMounts: - name: smtp-ca mountPath: /etc/ssl/formbricks-ca readOnly: true ``` Restart the Formbricks pods after changing the CA file because Node.js reads `NODE_EXTRA_CA_CERTS` when the process starts. ## Enabling Email Features By default, email verification and password reset features are **disabled** in Formbricks. To enable these features: ```bash theme={null} # Set to 0 to enable email verification (requires working SMTP) EMAIL_VERIFICATION_DISABLED=0 # Set to 0 to enable password reset functionality (requires working SMTP) PASSWORD_RESET_DISABLED=0 # Optional: configure the password reset link lifetime in minutes (5-120, default 30) PASSWORD_RESET_TOKEN_LIFETIME_MINUTES=30 ``` ## Configuration for One-Click Setup If you're using the one-click setup with Docker Compose, you can either: 1. Edit the docker-compose.yml file and add the SMTP environment variables: ```yaml theme={null} environment: # Email Configuration MAIL_FROM: noreply@yourdomain.com MAIL_FROM_NAME: Formbricks SMTP_HOST: smtp.yourprovider.com SMTP_PORT: 587 SMTP_SECURE_ENABLED: 0 SMTP_REQUIRE_TLS: 1 SMTP_REJECT_UNAUTHORIZED_TLS: 1 SMTP_USER: your_username SMTP_PASSWORD: your_password EMAIL_VERIFICATION_DISABLED: 0 PASSWORD_RESET_DISABLED: 0 PASSWORD_RESET_TOKEN_LIFETIME_MINUTES: 30 ``` 2. Or during the setup, answer "Yes" when prompted to set up the email service: ``` 📧 Do you want to set up the email service? You will need SMTP credentials for the same! [y/N] y ``` ## Provider-Specific Examples ### SendGrid ```bash theme={null} MAIL_FROM=noreply@yourdomain.com MAIL_FROM_NAME=Formbricks SMTP_HOST=smtp.sendgrid.net SMTP_PORT=587 SMTP_SECURE_ENABLED=0 SMTP_REQUIRE_TLS=1 SMTP_REJECT_UNAUTHORIZED_TLS=1 SMTP_USER=apikey SMTP_PASSWORD=your_sendgrid_api_key ``` ### AWS SES ```bash theme={null} MAIL_FROM=noreply@yourdomain.com MAIL_FROM_NAME=Formbricks SMTP_HOST=email-smtp.us-east-1.amazonaws.com SMTP_PORT=587 SMTP_SECURE_ENABLED=0 SMTP_REQUIRE_TLS=1 SMTP_REJECT_UNAUTHORIZED_TLS=1 SMTP_USER=your_ses_access_key SMTP_PASSWORD=your_ses_secret_key ``` ### Gmail ```bash theme={null} MAIL_FROM=your_email@gmail.com MAIL_FROM_NAME=Formbricks SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_SECURE_ENABLED=0 SMTP_REQUIRE_TLS=1 SMTP_REJECT_UNAUTHORIZED_TLS=1 SMTP_USER=your_email@gmail.com SMTP_PASSWORD=your_app_password ``` > **Note**: For Gmail, you need to use an App Password if you have 2FA enabled. ## Troubleshooting If you're experiencing issues with your email configuration: 1. Check that all required environment variables are set correctly 2. Verify your SMTP credentials are valid 3. Ensure your email provider allows sending from the specified MAIL\_FROM address 4. If using Gmail, ensure you're using an App Password 5. For port 465, set `SMTP_SECURE_ENABLED=1`. For port 587, set `SMTP_SECURE_ENABLED=0` and `SMTP_REQUIRE_TLS=1`. For additional help, join the conversation on [GitHub Discussions](https://github.com/formbricks/formbricks/discussions). # Self-Hosting Source: https://formbricks.com/docs/self-hosting/overview Learn how to self-host Formbricks. ## System requirements Formbricks is not a single container. The v6 baseline runs eight long-running services — the app, Formbricks Hub (API and worker), Cube, PostgreSQL, Redis/Valkey, SpiceDB and its operator — so size the host for the whole stack rather than for the app alone. | Deployment | CPU | Memory | Disk | | - | - | - | - | | Single server, evaluation | 2 vCPU | 4 GB | 20 GB SSD | | Single server, low load | 4 vCPU | 8 GB | 50 GB SSD | | Kubernetes, production | see below | see below | managed | Chart defaults request 1.9 vCPU and 2.9 GiB across those services — see `charts/formbricks/values.yaml`, plus `charts/spicedb-operator/values.yaml` for the operator. On Kubernetes, add whatever your provider reserves per node on top, typically around 0.5 vCPU and 1 GB. The single-server rows are derived from those totals rather than load-tested. > [!NOTE] > > **HTTPS Required**: Ensure your server runs with a valid HTTPS certificate. > [!WARNING] > > 4 GB is a floor, not a comfortable target. It leaves no headroom for a large response import, a survey > bundle rebuild, or any of the optional AI services. ### Single server or Kubernetes The single-server rows cover the [Docker](/docs/self-hosting/setup/docker) and [one-click](/docs/self-hosting/setup/one-click) installs. Both run every service on one host, so a reboot or an upgrade means downtime — usually an acceptable trade at low load, and not on its own a reason to reach for Kubernetes. Choose [Kubernetes](/docs/self-hosting/setup/kubernetes) when you need to survive a node failure or carry an uptime SLA. For Kubernetes, start at 3 nodes of at least 4 vCPU and 8 GB, autoscaling to 6, with PostgreSQL, Redis and object storage as managed services outside the cluster. Capacity is deliberately provider-neutral: a 2 vCPU node cannot hold the app's 1 vCPU request alongside the platform reserve, some providers exclude burstable instance families from system node pools, and a free control-plane tier carries no uptime SLA. Nothing is highly available out of the box — every replica count in the chart ships as `1`. Object storage must speak the S3 API, so a service without one, such as Azure Blob Storage, needs an [S3-compatible gateway](/docs/self-hosting/configuration/file-uploads) in front of it. The [Kubernetes deployment guide](/docs/self-hosting/setup/kubernetes) has the replica, autoscaling and managed-service settings. ### AI services are much heavier Self-hosted AI is off by default and is a different order of magnitude: Hub embeddings alone request 4 vCPU and 8 Gi for the foreground runtime, and 8 vCPU for the worker pool. Prefer an external endpoint unless you need them constantly. > [!NOTE] > > AI features are an Enterprise feature. Configure your > [Enterprise license](/docs/self-hosting/advanced/license) before enabling them. ### Sizing for a specific load **A burst of responses** is a queue question rather than a request-rate one. Each response enqueues several `response-pipeline.process` jobs — `responseCreated`, one `responseUpdated` per progress save, then `responseFinished` — so the count scales with how often answers are saved, and consumers default to one job in flight per app replica. Size Redis for the deepest backlog you expect: the chart pins `maxmemory-policy noeviction`, so a full Redis refuses writes rather than dropping jobs. See [job runner](/docs/self-hosting/configuration/job-runner). **A large contact list** is storage rather than throughput. Contact attributes are one row per attribute per contact, so 50,000 contacts with 10 attributes each is 500,000 rows before a single response is stored. We publish no responses-per-second figure per replica: it is not load-tested, and a 40-question survey with file uploads is not the same write as a one-question NPS. Watch pod CPU and queue depth separately through your first campaign — they move independently. ## **Self-hosting options** * [**One-Click Setup**](/docs/self-hosting/setup/one-click)**:** Set up Formbricks on Ubuntu in minutes with our shell script. * [**Docker Setup**](/docs/self-hosting/setup/docker)**:** Use our pre-built Docker image for an effortless start. * [**Kubernetes Deployment**](/docs/self-hosting/setup/kubernetes)**:** Deploy the full stack with the official Helm chart. * [**Migration Guide**](/docs/self-hosting/advanced/migration)**:** Upgrade your existing Formbricks instance smoothly. * [**Configuration**](/docs/self-hosting/configuration)**:** Customize your setup with advanced configurations. * [**Integrations**](/docs/self-hosting/configuration/integrations)**:** Connect Formbricks to third-party tools. * [**Licensing**](/docs/self-hosting/advanced/license)**:**  Learn more about our AGPL Formbricks Core and its open-source license & Unlock advanced features tailored for larger teams and enterprises with the EE License. ## **Hosting options** * **Cloud Hosting:** Hassle-free managed deployment at [app.formbricks.com](https://app.formbricks.com). * **Self-Hosting Free:** Perfect for personal use or small teams. * **Self-Hosting with EE License:** Unlock advanced features for large teams or enterprises. ## **Licensing options comparison** For Self Hosting, our core product is free however certain advanced features are a part of our Enterprise License offering. Please refer this table to understand if you want the features that are a part of it and then we’ll reach out to you! | **Feature** | Cloud Hosting | Self-Hosting Free | Self-Hosting EE License | | - | - | - | - | | Setup & Maintenance | Managed | DIY | DIY | | Advanced Functionality | Full (Optional Paid plans) | Most of them | All Advanced Features | | Support & Updates | Included | Community | Prioritized | | Price | Subscription | Free | Fixed Per month | | Customization & Control | Limited | Moderate | Full | For licensing queries, contact us at [**hola@formbricks.com**](). Formbricks is designed to be intuitive and accessible, ensuring an easy setup no matter which option you choose. Start using Formbricks today and take your surveys to the next level! **Need Help?** Join the conversation on [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions). # Cluster Setup Source: https://formbricks.com/docs/self-hosting/setup/cluster-setup Run Formbricks in a high-availability cluster. ## Overview Running Formbricks as a cluster of multiple instances gives you: * **High Availability**: surveys remain accessible even if one app pod becomes unavailable * **Load Distribution**: traffic can be spread across multiple stateless Formbricks app instances * **Scalability**: you can scale app replicas horizontally as usage grows * **Zero-Downtime Updates**: rolling deployments are possible with the right orchestration setup ## Requirements For a Formbricks v5 cluster setup, plan for: * shared PostgreSQL for Formbricks and Hub, with `pgvector` support if Hub shares the same database * shared Redis/Valkey for caching, rate limiting, and audit-related flows * shared S3-compatible storage if you use file uploads or organization branding assets * a load balancer or ingress layer in front of the app * Formbricks Hub as part of the runtime * Cube, either bundled or externally managed * Envoy Gateway or an equivalent external edge rate limiter for the v5-covered public and API-key routes ## Architecture ```mermaid theme={null} graph TD subgraph Edge LB["Load Balancer / Ingress"] RL["Envoy Or Equivalent Edge Rate Limiter"] end subgraph Formbricks Cluster FB1["Formbricks App 1"] FB2["Formbricks App 2"] FB3["Formbricks App n"] HUB["Formbricks Hub"] CUBE["Cube"] end subgraph Data Storage PSQL["PostgreSQL"] REDIS["Redis / Valkey"] S3["S3 Compatible Storage"] end LB --> RL RL --> FB1 RL --> FB2 RL --> FB3 FB1 --> PSQL FB2 --> PSQL FB3 --> PSQL HUB --> PSQL FB1 --> REDIS FB2 --> REDIS FB3 --> REDIS FB1 --> HUB FB2 --> HUB FB3 --> HUB FB1 --> CUBE FB2 --> CUBE FB3 --> CUBE CUBE --> PSQL FB1 --> S3 FB2 --> S3 FB3 --> S3 ``` ### Component Description 1. **Formbricks App Replicas** * stateless application instances that serve the UI, APIs, and survey flows * can be scaled horizontally behind a load balancer 2. **Formbricks Hub** * required in Formbricks v5 * stores and serves Hub-backed feedback record data * can share the same PostgreSQL database as the main app when configured that way 3. **Cube** * required for the supported v5 analytics baseline * can run as the bundled service or as an external deployment shared by every app replica 4. **PostgreSQL** * primary persistent store for the Formbricks app and, by default, Hub * should be backed up and monitored like any other stateful production dependency 5. **Redis / Valkey** * required for caching, remaining application-enforced rate limits, and audit-related flows * should be shared across all app replicas 6. **S3-Compatible Storage** * used for file uploads and media-related features * should be shared across all replicas 7. **Edge Layer** * terminates or routes incoming traffic * enforces rate limiting for the route groups that moved out of the application server in v5 ## Redis Configuration > [!NOTE] > > Redis/Valkey is required for Formbricks to function. The application will not start without `REDIS_URL`. ```sh env theme={null} REDIS_URL=redis://your-redis-host:6379 ``` ## S3 Configuration ```sh env theme={null} S3_ACCESS_KEY=your-access-key S3_SECRET_KEY=your-secret-key S3_REGION=your-region S3_BUCKET_NAME=your-bucket-name # For S3-compatible storage (e.g., StorJ, RustFS) # Leave empty for Amazon S3 S3_ENDPOINT_URL=https://your-s3-compatible-endpoint # Enable for RustFS and most third-party S3-compatible storage # Set to 0 (or omit) for Amazon S3 S3_FORCE_PATH_STYLE=1 ``` When using S3 in a cluster setup, ensure: * all replicas use the same bucket * CORS allows your Formbricks origin (for RustFS, set `RUSTFS_CORS_ALLOWED_ORIGINS`; see [File Uploads](/docs/self-hosting/configuration/file-uploads#rustfs-cors-configuration)) * the credentials have read/write access for the assets you expect Formbricks to manage ## v5 Cluster Notes ### Hub Is Mandatory Formbricks v5 self-hosting requires Hub. Do not plan a cluster upgrade that keeps Hub disabled. ### Edge Rate Limiting Must Exist Somewhere You do not have to use the Formbricks Helm chart's Envoy bundle, but you do need equivalent edge protection for the v5-covered public and API-key routes. Use the [rate-limiting guide](/docs/self-hosting/configuration/rate-limiting) for the exact route coverage. ### Cube Is Part Of The Baseline Cube is part of the supported Formbricks v5 stack and powers analytics flows that depend on Cube queries. The Docker Compose and Helm deployment paths bundle it by default. You can replace the bundled service with an external Cube deployment, but do not remove Cube connectivity from the baseline configuration: * keep the bundled Cube service enabled; or * configure every app replica with the same external `CUBEJS_API_URL` and `CUBEJS_API_SECRET`. ## Kubernetes Setup The current Kubernetes deployment path uses the OCI chart published from [`charts/formbricks`](https://github.com/formbricks/formbricks/tree/main/charts/formbricks): ```sh theme={null} helm install formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \ -n formbricks \ --create-namespace \ -f values.yaml ``` For the Kubernetes-specific installation flow, mandatory Hub behavior, and Envoy bundle modes, use the dedicated [Kubernetes deployment guide](/docs/self-hosting/setup/kubernetes). # Docker Setup Source: https://formbricks.com/docs/self-hosting/setup/docker Set up Formbricks quickly using our ready-to-use Docker image. Use this guide for a manual Docker Compose setup. It downloads the production Compose file and starts the baseline Formbricks stack: Formbricks Web, PostgreSQL, Redis/Valkey, Formbricks Hub, and Cube. Optional services such as Qwen/vLLM, AI taxonomy, and RustFS are documented after the baseline stack is running. The baseline also runs a single SpiceDB instance for Formbricks authorization data. ### Requirements Make sure the following tools are installed: * Docker Engine with Docker Compose V2 (`docker compose`) * `curl` * `openssl` * A POSIX-compatible shell such as `sh`, `bash`, or `zsh` Docker and Docker Compose are usually included in tools like Docker Desktop and Rancher Desktop. > [!NOTE] > > `docker compose` without the hyphen is now the primary method of using docker-compose, according to the > Docker documentation. ## Choose Your Setup Path * Use this manual Docker Compose guide for local installs, custom servers, or custom reverse-proxy setups. * Use the [one-click setup script](/docs/self-hosting/setup/one-click) for production Ubuntu servers where you want Traefik, HTTPS certificates, and optional RustFS automation. * Use the [migration guide](/docs/self-hosting/advanced/migration#v5) before updating an existing Formbricks 4.x install or an older v5 compose file. > [!NOTE] > > Starting with Formbricks v5, the production Docker Compose stack includes Formbricks Hub and Cube as part of > the baseline. Keep `HUB_API_URL` at its internal default unless Hub runs elsewhere. ## Start 1. **Create a New Directory for Formbricks** Open a terminal and run the following commands to create and enter a new directory for Formbricks: ```bash theme={null} mkdir formbricks-quickstart && cd formbricks-quickstart ``` 2. **Download the Docker Files** Get the Docker Compose file, AuthZed database bootstrap helper, and Cube configuration shipped with the baseline stack: ```bash theme={null} mkdir -p cube/schema curl -fsSL \ -o docker-compose.yml \ https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/docker-compose.yml curl -fsSL \ -o authzed-postgres-bootstrap.sh \ https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/authzed-postgres-bootstrap.sh chmod 700 authzed-postgres-bootstrap.sh curl -fsSL \ -o cube/cube.js \ https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/cube/cube.js curl -fsSL \ -o cube/schema/FeedbackRecords.js \ https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/cube/schema/FeedbackRecords.js ``` 3. **Create the Environment File** Store your configuration in `.env`. Docker Compose reads this file for variable interpolation, and the Formbricks container also loads it at startup. For a local install, use `http://localhost:3000`. For a server install, replace both URL values with your public HTTPS URL before starting the stack. ```bash theme={null} POSTGRES_PASSWORD=$(openssl rand -hex 32) cat < .env WEBAPP_URL=http://localhost:3000 BETTER_AUTH_URL=http://localhost:3000 POSTGRES_PASSWORD=$POSTGRES_PASSWORD POSTGRES_PASSWORD_URL_ENCODED=$POSTGRES_PASSWORD BETTER_AUTH_SECRET=$(openssl rand -hex 32) ENCRYPTION_KEY=$(openssl rand -hex 32) CRON_SECRET=$(openssl rand -hex 32) HUB_API_KEY=$(openssl rand -hex 32) CUBEJS_API_SECRET=$(openssl rand -hex 32) CUBEJS_JWT_ISSUER=formbricks-web CUBEJS_JWT_AUDIENCE=formbricks-cube AUTHZED_TOKEN=$(openssl rand -hex 32) AUTHZED_DATABASE_PASSWORD=$(openssl rand -hex 32) EOF chmod 600 .env ``` Keep `POSTGRES_PASSWORD` unchanged after PostgreSQL initializes the `postgres` volume. The generated hexadecimal value is already URL-safe, so `POSTGRES_PASSWORD_URL_ENCODED` uses the same value. If you replace an existing `docker-compose.yml`, copy the exact password from that deployment instead of generating a new one. If it contains URI-reserved characters, set `POSTGRES_PASSWORD_URL_ENCODED` to its percent-encoded form; otherwise you can use the same value or omit the encoded variable. The PostgreSQL image only applies the raw password when it creates a new database volume. 4. **Validate the Docker Compose Configuration** Validate the Compose file after `.env` contains the required values: ```bash theme={null} docker compose config >/dev/null ``` If validation fails, check that `.env` contains the required values and that `docker-compose.yml` has valid syntax. 5. **Start the Docker Setup** Now, you're ready to run Formbricks with Docker. Use the command below to start Formbricks together with PostgreSQL, Redis, the Formbricks Hub API and worker, Cube, and SpiceDB. ```bash theme={null} docker compose up -d ``` The `-d` flag runs the containers in the background, so they keep running even after you close the terminal. 6. **Verify the Stack** Confirm the baseline services started and the Formbricks health endpoint responds: ```bash theme={null} docker compose ps -a curl -fsS http://localhost:3000/health docker compose logs --tail=100 formbricks-migrate hub-migrate authzed-db-bootstrap spicedb-migrate docker compose logs --tail=100 formbricks hub hub-worker cube spicedb ``` `formbricks-migrate`, `hub-migrate`, `authzed-db-bootstrap`, and `spicedb-migrate` should complete successfully. `postgres`, `redis`, `cube`, `hub`, `hub-worker`, `spicedb`, and `formbricks` should be running or healthy. The worker has no HTTP health endpoint, so verify that it stays `Up` without repeated restarts. 7. **Open Formbricks in Your Browser** Once the setup is running, open [**http://localhost:3000**](http://localhost:3000) in your browser to access Formbricks. The first time you visit, you'll see a setup wizard. Follow the steps to create your first user and start using Formbricks. > [!NOTE] > > The bundled Docker stack keeps Formbricks Hub and Cube internal to the compose network. The app reaches them > through `http://hub:8080` and `http://cube:4000`. When AI taxonomy beta is enabled, Hub reaches taxonomy > internally through `http://taxonomy:8000`. ## AuthZed and SpiceDB The bundled SpiceDB service stores its data in a dedicated `spicedb` database and login inside the existing PostgreSQL container. Database bootstrap, datastore migration, and the release-matched `authzed-initialize` service are idempotent. Fresh installs apply the canonical schema and verify an empty or reconciled graph without making Formbricks startup or `/health` depend on SpiceDB. SpiceDB is reachable only inside the Compose network at `spicedb:50051`; it is not published on the host or routed through Traefik. The Formbricks container receives the supported AuthZed variables automatically. Keep `AUTHZED_TOKEN` and `AUTHZED_DATABASE_PASSWORD` private and include `.env` and the PostgreSQL volume in your backup plan. Running `docker compose down` preserves the volume; `docker compose down -v` deletes both Formbricks and SpiceDB data. The release image includes an opt-in operations CLI. It does not start during normal installation: ```bash theme={null} docker compose --profile authzed-ops run --rm authzed-ops health docker compose --profile authzed-ops run --rm authzed-ops schema check docker compose --profile authzed-ops run --rm authzed-ops backfill docker compose --profile authzed-ops run --rm authzed-ops upgrade check ``` See [AuthZed Operations](/docs/self-hosting/configuration/authzed-operations) before applying a schema, repairing relationships, upgrading SpiceDB, or restoring a backup. The bundled PostgreSQL service leaves `track_commit_timestamp` at its default `off` value, so SpiceDB reports that its Watch API is disabled. This does not affect schema writes, relationship writes, or permission checks. If a future integration consumes the Watch API, enable that PostgreSQL setting separately and plan for the required database restart. Repository development exposes SpiceDB on `127.0.0.1:50051`. To start the optional authenticated browser UI: ```bash theme={null} docker compose -f docker-compose.dev.yml --profile authzed-ui up -d authzed-ui ``` Then open [http://127.0.0.1:50052](http://127.0.0.1:50052). Run `pnpm authzed:smoke` for an isolated application-health, authentication-failure, bounded-outage, schema, permission, migration-idempotency, and persistence check. The smoke command uses its own Compose project and random host port, then removes its test data afterward. To check the developer stack through the Formbricks AuthZed client without writing data, run: ```bash theme={null} pnpm authzed:health ``` It reads the repository `.env`, prints one JSON result, and returns exit code `0` only when healthy. An empty SpiceDB schema is still a healthy connection. There is no AuthZed browser health page, and the normal Formbricks `/health` endpoint deliberately remains independent of SpiceDB. Restart Formbricks after changing any `AUTHZED_*` value. ## Optional Services Start and verify the baseline stack before enabling optional services. > [!NOTE] > > If `.env` already contains a `COMPOSE_PROFILES` line, update that line instead of adding a second one. ### Enable Bundled Qwen/vLLM For AI The Docker stack can optionally run Qwen through vLLM as an OpenAI-compatible `/v1` endpoint. Baseline installs do not start vLLM and can still use Google Vertex, Azure, AWS Bedrock, or another OpenAI-compatible endpoint. The bundled Qwen/vLLM service requires a GPU-capable Docker host with the NVIDIA Container Toolkit installed. Model files are stored in the `qwen-model-cache` Docker volume. Startup can take several minutes while vLLM downloads and loads the model. To use the bundled Qwen runtime, add these values to `.env`: ```bash theme={null} cat <> .env COMPOSE_PROFILES=qwen AI_PROVIDER=openai-compatible AI_MODEL=qwen3-14b-awq AI_OPENAI_COMPATIBLE_BASE_URL=http://vllm:8000/v1 AI_OPENAI_COMPATIBLE_PROVIDER_NAME=vllm AI_OPENAI_COMPATIBLE_SUPPORTS_STRUCTURED_OUTPUTS=1 EOF ``` Then start the stack with the profile and check vLLM: ```bash theme={null} docker compose --profile qwen up -d docker compose --profile qwen ps docker compose logs --tail=100 vllm formbricks curl -fsS http://127.0.0.1:8000/health ``` The vLLM endpoint is available inside the Compose network at `http://vllm:8000/v1` and is bound to `127.0.0.1:8000` by default for local checks. If you run your own Qwen/vLLM service, do not enable the `qwen` profile. Set `AI_PROVIDER`, `AI_MODEL`, and `AI_OPENAI_COMPATIBLE_BASE_URL` to your external endpoint instead. ### Enable AI Taxonomy Beta The standalone AI taxonomy service is included as an opt-in Docker Compose profile. Baseline installs do not start taxonomy and do not require taxonomy or LLM secrets. To enable taxonomy with the bundled Qwen runtime, add these values to `.env`: ```bash theme={null} cat <> .env COMPOSE_PROFILES=qwen,taxonomy TAXONOMY_SERVICE_URL=http://taxonomy:8000 TAXONOMY_SERVICE_TOKEN=$(openssl rand -hex 32) HUB_INTERNAL_API_TOKEN=$(openssl rand -hex 32) TAXONOMY_IMAGE_REF=:v0.1.0 TAXONOMY_LLM_PROVIDER=openai-compatible TAXONOMY_LLM_MODEL=qwen3-14b-awq TAXONOMY_LLM_BASE_URL=http://vllm:8000/v1 TAXONOMY_LLM_API_KEY=not-used EOF ``` Replace `:v0.1.0` with the current released `ghcr.io/formbricks/taxonomy` image tag for your Formbricks version. Production installs should pin a release tag instead of relying on `:latest`. If you run your own OpenAI-compatible endpoint, use `COMPOSE_PROFILES=taxonomy` instead and point `TAXONOMY_LLM_BASE_URL` at that `/v1` endpoint. The selected model must reliably return strict JSON because taxonomy generation validates an exact 5-level tree. To use Amazon Bedrock instead of an OpenAI-compatible endpoint, replace the taxonomy LLM values with: ```bash theme={null} TAXONOMY_LLM_PROVIDER=bedrock TAXONOMY_LLM_MODEL=eu.anthropic.claude-sonnet-4-5-20250929-v1:0 AWS_REGION=eu-north-1 AWS_BEARER_TOKEN_BEDROCK= ``` To use Gemini on Vertex AI instead, replace the taxonomy LLM values with: ```bash theme={null} TAXONOMY_LLM_PROVIDER=vertex-gemini TAXONOMY_LLM_MODEL=gemini-2.5-flash TAXONOMY_VERTEX_PROJECT= TAXONOMY_VERTEX_LOCATION= TAXONOMY_GOOGLE_CLOUD_CREDENTIALS_JSON= ``` Start the stack after updating `.env`. Compose reads `COMPOSE_PROFILES` from `.env`, so the same command works for `taxonomy` and `qwen,taxonomy` setups: ```bash theme={null} docker compose up -d docker compose ps docker compose logs --tail=100 taxonomy hub ``` If you enabled the bundled Qwen profile, also check vLLM: ```bash theme={null} docker compose logs --tail=100 vllm ``` Run the authenticated preflight after startup to verify Hub internal auth and LLM reachability: ```bash theme={null} docker compose --profile taxonomy exec -T taxonomy python - <<'PY' import os import urllib.request request = urllib.request.Request( "http://127.0.0.1:8000/v1/preflight", headers={"Authorization": "Bearer " + os.environ["TAXONOMY_SERVICE_TOKEN"]}, ) print(urllib.request.urlopen(request, timeout=10).read().decode()) PY ``` This command runs inside the taxonomy container, so `127.0.0.1:8000` refers to the taxonomy service itself. The preflight endpoint then checks Hub internal auth and LLM reachability from taxonomy. The taxonomy service remains internal to the compose network by default. `TAXONOMY_MAX_RECORDS` defaults to `10000`; change it only after sizing CPU, memory, and LLM capacity. > [!NOTE] > > The taxonomy service is internal to the Docker network. Formbricks Web still calls Hub with > `HUB_API_KEY`; Hub calls taxonomy with `TAXONOMY_SERVICE_TOKEN`; taxonomy calls Hub > internal APIs with `HUB_INTERNAL_API_TOKEN`. > [!NOTE] > > The one-click installer does not prompt for AI taxonomy settings. One-click users can enable the beta later > by editing `./formbricks/.env`, adding the taxonomy variables above, ensuring `COMPOSE_PROFILES=taxonomy` is > set, and restarting with `docker compose up -d`. > [!NOTE] > > If you use the one-click Traefik setup, FeedbackRecords are available on the Formbricks origin at > `/api/v3/feedbackRecords` and `/v1/feedback-records`. Custom Docker reverse proxies need equivalent wiring: > run gateway auth against the Formbricks app, rewrite `/api/v3/feedbackRecords` to Hub's > `/v1/feedback-records`, and inject `Authorization: Bearer ` only on the Hub-bound hop. ## Update See our [migration guide](/docs/self-hosting/advanced/migration) for version-specific steps to update Formbricks. ### Add SpiceDB to an Existing Docker Installation The normal image update commands do not add new services to an existing customized Compose file. Before the first release that requires the AuthZed runtime: 1. Follow the [maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade): stop all writers and controllers, drain in-flight work, then back up configuration, secrets, and databases. 2. Download `authzed-postgres-bootstrap.sh` from the same Formbricks release as the Compose file. 3. Generate `AUTHZED_TOKEN` and `AUTHZED_DATABASE_PASSWORD` with `openssl rand -hex 32` and add them to `.env`. 4. Merge `authzed-db-bootstrap`, `spicedb-migrate`, `spicedb`, `authzed-initialize`, and the profiled `authzed-ops` service, plus the six `AUTHZED_*` Formbricks variables, from the released Compose file into your customized file. Use `AUTHZED_CONSISTENCY=fully_consistent`. Preserve proxy, storage, and SMTP settings. 5. Validate the reviewed Compose configuration privately and pull the pinned images. Keep writers stopped. 6. Wait for PostgreSQL and SpiceDB, then run the target image's maintenance command. It runs application migrations before graph preparation and verification: ```bash theme={null} docker compose up -d --wait postgres spicedb docker compose --profile authzed-ops run --rm --no-deps \ --entrypoint formbricks-authzed-prepare authzed-ops \ --backup-confirmed --writers-stopped ``` A non-empty mismatched schema requires the reviewed `remoteDigest` as described in [AuthZed Operations](/docs/self-hosting/configuration/authzed-operations#upgrade-an-existing-installation-to-v6). 7. Only after preparation and verification exit `0`, set `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true` in `.env` and run `docker compose up -d`. The one-click updater only checks the already-prepared graph; it does not perform online preparation. Keep maintenance active until authorization checks pass. 8. Confirm `authzed-db-bootstrap`, `spicedb-migrate`, and `authzed-initialize` completed and `spicedb` is healthy with `docker compose ps -a`. 9. Back up the new authorization database with `docker compose exec -T postgres pg_dump -U postgres -d spicedb > spicedb-backup.sql` after validation and include it in future database backup procedures. After database changes, restoring the old image alone may not be safe. Remain in maintenance and either fix forward or restore coordinated backups with the matching v5 configuration. Never delete volumes. See the rollback procedure in [AuthZed Operations](/docs/self-hosting/configuration/authzed-operations#roll-back-a-v6-upgrade). > [!NOTE] > > For a major migration such as Formbricks 4.x to 5.0, update your compose structure and configuration first. > Pulling images alone is not enough if your stack does not yet include Hub (`HUB_API_KEY`), Cube (`cube/` > config files plus `CUBEJS_API_SECRET`), or the new edge rate-limiting setup. 1. Pull the latest Formbricks image ```bash theme={null} docker compose pull ``` 2. Check the target release's already-prepared authorization graph. If blocked, follow the maintenance preparation guide above before proceeding. ```bash theme={null} docker compose --profile authzed-ops run --rm --no-deps authzed-ops upgrade check ``` 3. Refresh the bundled Cube model, so analytics charts can use members the release adds. The commands do nothing when Cube runs outside this Compose project. They download both files before replacing either one, and keep the previous copies in `cube/previous/`. Use the release's tag instead of `stable` when your deployment is pinned. ```bash theme={null} if [ -f cube/schema/FeedbackRecords.js ]; then base=https://raw.githubusercontent.com/formbricks/formbricks/stable/docker curl -fsSL -o cube/cube.js.download "$base/cube/cube.js" && curl -fsSL -o cube/FeedbackRecords.js.download "$base/cube/schema/FeedbackRecords.js" && mkdir -p cube/previous/schema && cp -p cube/cube.js cube/previous/cube.js && cp -p cube/schema/FeedbackRecords.js cube/previous/schema/FeedbackRecords.js && mv cube/cube.js.download cube/cube.js && { # Never leave the new cube.js paired with the old model. mv cube/FeedbackRecords.js.download cube/schema/FeedbackRecords.js || { cp -p cube/previous/cube.js cube/cube.js; false; } } fi ``` 4. Stop the Formbricks stack ```bash theme={null} docker compose down ``` 5. Wait for PostgreSQL and complete application migrations before restarting the updated stack. Stop if a command fails; do not restart against a partially migrated database. If `formbricks-migrate` fails, follow [If a migration fails](/docs/self-hosting/advanced/migration#if-a-migration-fails). ```bash theme={null} docker compose up -d --wait postgres && docker compose run --rm --no-deps formbricks-migrate && docker compose up -d ``` > [!WARNING] > > **Security (existing installs):** these steps — and the [one-click setup script](/docs/self-hosting/setup/one-click) > updater — do **not** rewrite your existing > `docker-compose.yml`. If your bundled `redis` (Valkey) service still publishes `ports: - "6379:6379"`, it > stays exposed to the host after updating. See [Debug](#debug) for how to remove the mapping and, if the port > was reachable from an untrusted network, invalidate existing sessions. ## Optional: Add RustFS for File Storage RustFS provides S3-compatible object storage for file uploads in Formbricks. It is not required for the baseline Docker setup. Add it only when you want features like image uploads, survey file uploads, or custom logos. > [!NOTE] > > For a broader overview of file storage options and required environment variables, see our [File Uploads > Configuration](/docs/self-hosting/configuration/file-uploads) guide. > [!WARNING] > > **For production deployments with HTTPS**, use the [one-click setup script](/docs/self-hosting/setup/one-click) > which automatically configures RustFS with Traefik, SSL certificates, a dedicated `files.` subdomain, and > least-privilege service credentials. The examples below are best suited for development, testing, or custom > local setups. > [!WARNING] > > The bundled RustFS examples on this page are convenience-oriented single-server setups. They work well for > development, evaluation, and smaller self-hosted deployments, but they are not the ideal RustFS architecture > for high-availability or larger-scale production storage. For stricter production requirements, use external > object storage or run a dedicated RustFS deployment separately. ### Quick Start: Repository Development Stack If you cloned the Formbricks repository, the fastest way to test file uploads locally is to use the included `docker-compose.dev.yml`, which already starts RustFS and auto-creates the `formbricks` bucket. > [!NOTE] > > This development compose file is not downloaded by the manual production quickstart above. If you only > downloaded `docker-compose.yml`, use the manual RustFS setup below or the one-click production setup. 1. **Start the local stack** From the repository root: ```bash theme={null} docker compose -f docker-compose.dev.yml up -d ``` This starts PostgreSQL, Valkey (Redis), Mailhog, RustFS, a permissions helper, a one-time bucket bootstrap job, Formbricks Hub, and a local Cube instance for analytics testing. 2. **Access the RustFS console** Open [http://localhost:9001](http://localhost:9001) in your browser and sign in with: * Username: `devrustfs` * Password: `devrustfs123` 3. **Configure Formbricks** Update your `.env` file or environment variables: ```bash theme={null} S3_ACCESS_KEY="devrustfs" S3_SECRET_KEY="devrustfs123" S3_REGION="us-east-1" S3_BUCKET_NAME="formbricks" S3_ENDPOINT_URL="http://localhost:9000" S3_FORCE_PATH_STYLE="1" ``` 4. **Verify uploads** After uploading a file in Formbricks, open [http://localhost:9001](http://localhost:9001) and navigate to **Buckets → formbricks** to confirm the object was stored successfully. > [!NOTE] > > The development compose file also runs a `rustfs-init` job so you do not need to create the bucket manually. ### Manual RustFS Setup (Custom Configuration) > [!NOTE] > > **Recommended:** Prefer `docker-compose.dev.yml` for local development unless you > need to fold RustFS into an existing custom Compose stack. If you want to add RustFS to your own `docker-compose.yml`, use a pinned RustFS image plus two helper services: ```yaml theme={null} services: rustfs-perms: image: busybox:1.36.1 user: "0:0" command: ["sh", "-c", "mkdir -p /data && chown -R 10001:10001 /data"] volumes: - rustfs-data:/data rustfs: image: rustfs/rustfs:1.0.0-rc.2@sha256:7d6d361c49c08d427250fb59aae5d78df83d644c3405d9ccf4b21cda0b0692d0 restart: always depends_on: rustfs-perms: condition: service_completed_successfully command: /data environment: RUSTFS_ACCESS_KEY: "${FORMBRICKS_RUSTFS_ADMIN_USER}" RUSTFS_SECRET_KEY: "${FORMBRICKS_RUSTFS_ADMIN_PASSWORD}" RUSTFS_ADDRESS: ":9000" RUSTFS_CONSOLE_ENABLE: "true" RUSTFS_CONSOLE_ADDRESS: ":9001" # CORS for browser uploads: set to your Formbricks origin(s), comma-separated. # Unset = no CORS headers are emitted, so browser uploads fail; a value is treated as an allow-list. # See the File Uploads guide. RUSTFS_CORS_ALLOWED_ORIGINS: "https://app.yourdomain.com" ports: - "9000:9000" - "9001:9001" volumes: - rustfs-data:/data rustfs-init: image: rustfs/rc:v0.1.36@sha256:ab024bfebee49a750ce886b4c70963ccd9ddaa03f491704a90710641d7a26699 depends_on: - rustfs environment: RUSTFS_ADMIN_USER: "${FORMBRICKS_RUSTFS_ADMIN_USER}" RUSTFS_ADMIN_PASSWORD: "${FORMBRICKS_RUSTFS_ADMIN_PASSWORD}" RUSTFS_SERVICE_USER: "${FORMBRICKS_RUSTFS_SERVICE_USER}" RUSTFS_SERVICE_PASSWORD: "${FORMBRICKS_RUSTFS_SERVICE_PASSWORD}" RUSTFS_BUCKET_NAME: "${FORMBRICKS_RUSTFS_BUCKET_NAME}" RUSTFS_POLICY_NAME: "${FORMBRICKS_RUSTFS_POLICY_NAME}" entrypoint: - /bin/sh - -c - | set -e until rc alias set rustfs http://rustfs:9000 "$RUSTFS_ADMIN_USER" "$RUSTFS_ADMIN_PASSWORD" >/dev/null 2>&1 \ && rc bucket list rustfs >/dev/null 2>&1; do sleep 2 done rc bucket create rustfs/"$RUSTFS_BUCKET_NAME" --ignore-existing cat > /tmp/formbricks-policy.json << EOF { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["s3:DeleteObject", "s3:GetObject", "s3:PutObject"], "Resource": ["arn:aws:s3:::$RUSTFS_BUCKET_NAME/*"] }, { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": ["arn:aws:s3:::$RUSTFS_BUCKET_NAME"] } ] } EOF if ! rc admin policy info rustfs "$RUSTFS_POLICY_NAME" >/dev/null 2>&1; then rc admin policy create rustfs "$RUSTFS_POLICY_NAME" /tmp/formbricks-policy.json fi if ! rc admin user info rustfs "$RUSTFS_SERVICE_USER" >/dev/null 2>&1; then rc admin user add rustfs "$RUSTFS_SERVICE_USER" "$RUSTFS_SERVICE_PASSWORD" fi rc admin policy attach rustfs "$RUSTFS_POLICY_NAME" --user "$RUSTFS_SERVICE_USER" ``` Declare the corresponding volume: ```yaml theme={null} volumes: rustfs-data: driver: local ``` Store the generated RustFS credentials in a local `.env` file next to your `docker-compose.yml` instead of hardcoding them in Compose: ```bash theme={null} FORMBRICKS_RUSTFS_ADMIN_USER=formbricks-root FORMBRICKS_RUSTFS_ADMIN_PASSWORD=change-this-secure-password FORMBRICKS_RUSTFS_SERVICE_USER=formbricks-service FORMBRICKS_RUSTFS_SERVICE_PASSWORD=change-this-service-password FORMBRICKS_RUSTFS_BUCKET_NAME=formbricks FORMBRICKS_RUSTFS_POLICY_NAME=formbricks-policy FORMBRICKS_RUSTFS_REGION=us-east-1 ``` Then configure Formbricks to use the RustFS service credentials: ```bash theme={null} S3_ACCESS_KEY="${FORMBRICKS_RUSTFS_SERVICE_USER}" S3_SECRET_KEY="${FORMBRICKS_RUSTFS_SERVICE_PASSWORD}" S3_REGION="${FORMBRICKS_RUSTFS_REGION}" S3_BUCKET_NAME="${FORMBRICKS_RUSTFS_BUCKET_NAME}" S3_ENDPOINT_URL="http://rustfs:9000" S3_FORCE_PATH_STYLE="1" ``` Start the stack: ```bash theme={null} docker compose up -d ``` The bucket and service account are created automatically by the `rustfs-init` job defined above, so no manual RustFS console step is required. > [!NOTE] > > Restrict the `.env` file to `0600` and do not commit it to source control. For production, prefer the > [one-click setup script](/docs/self-hosting/setup/one-click), which creates a separate least-privilege service > account automatically. #### Tips & Common Gotchas * **Permission denied on `/data`**: Ensure the mounted directory or volume is owned by UID `10001`. The `rustfs-perms` helper handles this for Compose-managed volumes. * **Storage medium matters**: Prefer local SSD or NVMe storage for `rustfs-data`, use XFS on dedicated host-managed disks where possible, and avoid NFS or other network filesystems for RustFS data. * **Connection refused**: Ensure the `rustfs` container is running and port `9000` is reachable from the Formbricks container. * **Bucket not found**: Confirm that `rustfs-init` completed successfully or create the bucket manually with `rc`. * **Auth failed**: Confirm that `S3_ACCESS_KEY` and `S3_SECRET_KEY` match the RustFS credentials configured on the server. * **Backups**: Back up the `rustfs-data` volume regularly, especially for single-server deployments. * **Console exposure**: Do not expose the RustFS console port publicly in production. Keep it on a private network or behind admin-only controls. * **Health check**: From the Formbricks container: ```bash theme={null} docker compose exec formbricks sh -c 'wget -O- http://rustfs:9000/health' ``` ### Production Setup with Traefik For production deployments, use the [one-click setup script](/docs/self-hosting/setup/one-click), which automatically configures: * RustFS behind Traefik on a dedicated `files.yourdomain.com` subdomain * Automatic SSL certificate generation via Let's Encrypt * CORS configuration scoped to your Formbricks domain * Rate limiting middleware * Separate RustFS admin and Formbricks service credentials * A `rustfs-init` job that creates the bucket and access policy The production setup from [formbricks.sh](https://github.com/formbricks/formbricks/blob/main/docker/formbricks.sh) adds the reverse proxy wiring and bootstrap automation needed for long-lived deployments. > [!NOTE] > > Even in the one-click flow, bundled RustFS remains a convenience-oriented single-server deployment. For > higher availability, stricter operational requirements, or larger storage footprints, prefer external object > storage or a dedicated RustFS deployment managed separately from Formbricks. ## Debug If startup fails, first check the resolved configuration and container state: ```bash theme={null} docker compose config >/dev/null docker compose ps -a ``` Then inspect the services that commonly explain startup issues: ```bash theme={null} docker compose logs --tail=200 formbricks-migrate hub-migrate formbricks hub hub-worker cube docker compose logs --tail=200 postgres redis ``` Common checks: * **Missing or empty secrets**: Confirm `.env` contains `BETTER_AUTH_SECRET`, `ENCRYPTION_KEY`, `CRON_SECRET`, `HUB_API_KEY`, and `CUBEJS_API_SECRET`. * **Migration failures**: Check `formbricks-migrate`, `hub-migrate`, and `postgres` logs. Do not remove Docker volumes on an existing install unless you intend to delete its data. For a failed `formbricks-migrate`, follow [If a migration fails](/docs/self-hosting/advanced/migration#if-a-migration-fails). * **Cube is unhealthy**: Confirm `cube/cube.js`, `cube/schema/FeedbackRecords.js`, and `CUBEJS_API_SECRET` exist, then inspect `docker compose logs cube`. * **Hub auth errors**: Confirm the same `HUB_API_KEY` from `.env` is used by Formbricks Web and the Hub service. * **Hub jobs remain queued**: Confirm `docker compose ps hub-worker` reports `Up`, then inspect `docker compose logs --tail=200 hub-worker`. The worker has no HTTP health endpoint; a stable process and a shrinking River backlog are its readiness signals. If it restarts, confirm each configured enrichment provider/model has the required credentials and that the worker can reach PostgreSQL. * **Port conflicts**: Confirm port `3000` and any optional service ports you enabled are not already in use on the host. The current template does not publish the bundled Valkey (`redis` service) to the host — it is reachable only on the internal compose network — so a fresh install does not need port `6379` free on the host. * **Optional Qwen/vLLM issues**: Check GPU availability, NVIDIA Container Toolkit installation, and `docker compose --profile qwen logs --tail=200 vllm`. > [!WARNING] > > **Existing installs: remove the bundled Valkey host port.** Older templates published the `redis` > (Valkey) service on `0.0.0.0:6379` with no password. That instance stores Better Auth sessions and > verification tokens, so an exposed port lets anyone who can reach it read live sessions and take over > accounts. Updating Formbricks (`docker compose pull` / `up -d`) does **not** rewrite your existing > `docker-compose.yml`, so the mapping stays until you remove it. Open your `docker-compose.yml`, delete the > > ```yaml theme={null} > ports: > - "6379:6379" > ``` > > lines from the `redis:` service, then run `docker compose up -d`. The app reaches Valkey over the internal > compose network, so no other configuration change is needed. Only keep a publish if an external tool > genuinely needs it, and then bind it to loopback (`127.0.0.1:6379:6379`) rather than all interfaces. > > **If the port was reachable from an untrusted network, also invalidate existing sessions.** Valkey persists > to its `redis` volume, so removing the port does not clear session or token state an attacker may already > have written — a forged session can remain valid afterward. After closing the port, set a new > `BETTER_AUTH_SECRET` in your `.env`, then recreate the app container so it picks up the change: > > ```bash theme={null} > docker compose up -d --force-recreate formbricks > ``` > > A plain `docker compose restart` keeps the container's original environment, so the rotated secret would not > take effect. Recreating invalidates every session cookie, so all users must sign in again, while stored > data, the job queue, and the cache stay intact. (On an instance installed before this variable was > renamed, the secret may live in your `.env` under the older name, `NEXTAUTH_SECRET`. Replace the value > of whichever name your `.env` actually defines. Adding the *other* name alongside it does not reliably > rotate anything: `BETTER_AUTH_SECRET` wins whenever both are set, so a new `NEXTAUTH_SECRET` next to an > existing `BETTER_AUTH_SECRET` changes nothing and leaves the forged session valid.) Leave > `ENCRYPTION_KEY` unchanged, and do **not** run a blanket `FLUSHDB` — the same Valkey also holds BullMQ > job queues and the application cache. > [!NOTE] > > To edit any of the available environment variables, check out our > [Configuration](/docs/self-hosting/configuration/environment-variables) section. If you have any questions or require help, reach out on [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions). # Kubernetes Deployment Source: https://formbricks.com/docs/self-hosting/setup/kubernetes Deploy Formbricks on Kubernetes with the current OCI Helm chart. Deploy Formbricks on Kubernetes using the current OCI Helm chart published from the `charts/formbricks` directory in the Formbricks repository. > [!NOTE] > > Formbricks v5 self-hosting expects Hub to be part of the runtime. The chart handles that by default. Use the > [migration guide](/docs/self-hosting/advanced/migration#v5) before upgrading an existing 4.x deployment. ## Prerequisites Ensure you have the following before proceeding: * a running Kubernetes cluster * Helm 3 installed locally * a public hostname for `formbricks.webappUrl` * a plan for PostgreSQL and Redis/Valkey, either in-cluster or managed externally * an edge rate-limiting plan for the v5-covered routes: the chart's Envoy bundle or an equivalent external edge solution ## 1. Install The Chart **1. Create A Minimal values.yaml** ```yaml theme={null} formbricks: webappUrl: https://surveys.example.com ``` Add any additional overrides you need for ingress, external services, secrets, or Enterprise license features. **2. Install Formbricks** ```sh theme={null} helm install formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \ -n formbricks \ --create-namespace \ -f values.yaml ``` By default, the chart deploys: * the Formbricks application * Formbricks Hub * Cube * PostgreSQL * Redis * generated Kubernetes Secrets > [!WARNING] > > The default values are a starting point, not a production edge or high-availability configuration. Both > `ingress.enabled` and `envoy.enabled` default to `false`, so the chart does not expose the application or add > the v5 edge rate limits unless you configure them. The defaults also combine `autoscaling.minReplicas: 1` with > `pdb.minAvailable: 1`; that PodDisruptionBudget can block a node drain because Kubernetes cannot voluntarily > evict the only app pod. ## 2. Configure Secrets And External Services ### Using Generated Secrets The default chart path keeps `secret.enabled: true`, which lets the chart generate the required application secrets for you. ### Adding An Enterprise License There is no separate `enterprise.enabled` switch. Enterprise features are unlocked by a valid `ENTERPRISE_LICENSE_KEY`. For a quick-start deployment that uses the chart-generated app Secret, set: ```yaml theme={null} enterprise: licenseKey: your-enterprise-license-key ``` For production, keep the license out of a values file and provide `ENTERPRISE_LICENSE_KEY` through your existing Secret or ExternalSecret instead. The `enterprise.licenseKey` chart value only writes to the generated app Secret when `secret.enabled: true`. ### Using Managed PostgreSQL And Redis For production workloads, many teams prefer managed services: ```yaml theme={null} postgresql: enabled: false externalDatabaseUrl: "postgresql://user:password@your-postgres-host:5432/formbricks" redis: enabled: false externalRedisUrl: "redis://your-redis-host:6379" ``` ### Using External Secrets If your cluster already uses an external secret manager, enable `externalSecret` and point it at your existing SecretStore. Ensure the resulting app secret exposes the values your deployment needs, including `DATABASE_URL`, `REDIS_URL`, and `HUB_API_KEY`. ### SpiceDB authorization Formbricks v6 uses SpiceDB, maintained by AuthZed, as its authorization engine. Fresh chart installations enable a private, two-replica SpiceDB cluster and `fully_consistent` decisions by default. If the cluster already has a compatible SpiceDB operator, keep the authorization runtime enabled but disable this release's operator installation: ```yaml theme={null} authzed: operator: install: false ``` The default `authzed.operator.install: true` installs the pinned operator, creates the cluster, and bootstraps a dedicated `spicedb` database and login. Install only one operator in a Kubernetes cluster. For managed PostgreSQL, create a separate SpiceDB database and login first. Store its connection URI and a strong API token in a Kubernetes Secret using the keys `datastore_uri` and `preshared_key`, then configure: ```yaml theme={null} authzed: enabled: true auth: existingSecret: formbricks-authzed datastore: existingSecret: formbricks-authzed ``` Use `authzed.mode: external`, `authzed.operator.install: false`, `authzed.endpoint: :`, and `authzed.insecure: false` when connecting to an externally managed AuthZed endpoint. The external endpoint must serve TLS because the preshared token is sent on every authenticated request. The application endpoint remains internal and uses plaintext gRPC by default when the chart owns SpiceDB. For an already-running v6 installation, Helm prints release-specific diagnostic commands that execute the release-matched operator CLI inside a Formbricks pod: ```bash theme={null} kubectl exec -n deployment/ -- formbricks-authzed health kubectl exec -n deployment/ -- formbricks-authzed schema check kubectl exec -n deployment/ -- formbricks-authzed upgrade check ``` A fresh install runs an idempotent initialization Job, but application startup and probes remain independent from it. Upgrades never run relationship preparation automatically. For an existing v5 installation, follow [the v6 upgrade procedure below](#upgrading-from-v5-to-v6) before running `helm upgrade` or resuming GitOps. The chart refuses an unacknowledged upgrade, disabled AuthZed, or weaker consistency. Follow [AuthZed Operations](/docs/self-hosting/configuration/authzed-operations) for ongoing operations and do not expose SpiceDB through an Ingress. ## 3. v5-Specific Deployment Notes ### Hub Is Mandatory Formbricks v5 does not support `hub.enabled=false`. Keep the default `hub.enabled=true` behavior in place. Use `hub.image.tag`, `hub.resources`, and `hub.existingSecret` only when you need to pin or customize the Hub deployment details. ### Envoy Bundle Modes The chart supports these edge patterns for the v5-covered routes: * **Bundled Envoy controller and CRDs**: set `envoy.enabled=true`, `envoy.controller.enabled=true`, and `envoy.crds.enabled=true` * **Bundled Envoy controller with platform-managed CRDs**: keep the controller enabled and set `envoy.crds.enabled=false` * **Existing cluster Envoy controller**: set `envoy.enabled=true`, `envoy.controller.enabled=false`, `envoy.formbricks.gatewayClass.create=false`, and `envoy.formbricks.gatewayClass.name` to the existing class * **Equivalent external edge protection**: keep using your platform's own ingress or gateway layer if it already provides equivalent rate-limiting coverage If you use the chart-managed Envoy rate-limiting path, enable a dedicated backend with: ```yaml theme={null} envoy: enabled: true controller: enabled: true crds: enabled: true envoyRedis: enabled: true ``` This installs Envoy Gateway 1.8.4 with Gateway API 1.5.1 and keeps Envoy rate-limiting state separate from the application's own Redis traffic. If your platform already manages compatible Gateway API CRDs, install only the matching Envoy Gateway CRDs: ```bash theme={null} crd_dir="$(mktemp -d)" helm pull oci://docker.io/envoyproxy/gateway-crds-helm \ --version v1.8.4 --untar --untardir "${crd_dir}" helm template envoy-gateway-crds "${crd_dir}/gateway-crds-helm" \ --set crds.gatewayAPI.enabled=false \ --set crds.envoyGateway.enabled=true \ | kubectl apply --server-side --force-conflicts -f - ``` Pulling the OCI chart first keeps Helm 4's pull messages out of the manifest pipe. Remove the temporary directory after the apply succeeds. Then keep the bundled controller but prevent the Formbricks release from managing either CRD set: ```yaml theme={null} envoy: enabled: true controller: enabled: true crds: enabled: false ``` For a Flux `HelmRelease`, also make the ownership boundary explicit: ```yaml theme={null} spec: install: crds: Skip upgrade: crds: Skip ``` The example installs the bundled controller. If your cluster already provides a compatible Envoy Gateway controller, set `envoy.controller.enabled: false`, disable GatewayClass creation, and provide the existing GatewayClass name. The controller dependency, including its CRDs, is disabled in this mode. In either mode, configure `envoy.formbricks.ingress` or your platform ingress/load balancer so public traffic reaches the Envoy-managed routes. If you use an equivalent external edge solution instead, verify that it covers every route in the [rate-limiting guide](/docs/self-hosting/configuration/rate-limiting) before exposing Formbricks. > [!WARNING] > > Istio and other Gateway API implementations can remain in front of Formbricks, but they do not reconcile > Envoy-specific resources such as `SecurityPolicy`, `HTTPRouteFilter`, or `EnvoyProxy`. Enabling the Feedback > Records gateway route therefore still requires an Envoy Gateway controller. ### Production Replicas And Disruption Budgets For a production deployment that should remain available during a voluntary disruption, run at least two app replicas: ```yaml theme={null} autoscaling: enabled: true minReplicas: 2 pdb: enabled: true minAvailable: 1 ``` If you intentionally run a single app replica, either disable the PDB or use `maxUnavailable: 1` instead of `minAvailable` and accept downtime during the eviction. Never set both fields; set the unused field to `null` in your values file. Two autoscaling defaults are easy to miss: * **`maxReplicas: 10` can exceed what the node pool can hold.** Each app pod requests 1 vCPU, so the ceiling needs about 10 allocatable vCPU for the app alone, on top of the platform reserve and the Hub, Cube and SpiceDB pods. A smaller pool leaves the extra replicas `Pending` — an HPA does not lower its own ceiling. * **The HPA scales on CPU and memory utilization only.** Queue depth is not one of its metrics, so a job backlog can grow while both targets sit under their thresholds and no replica is added. Backlog-driven scaling needs a queue-depth metric published to the metrics API and added to the HPA yourself. ### Cube Cube is part of the baseline Formbricks v5 stack and is bundled with the chart by default (`cube.enabled: true`). To run an external Cube cluster instead: * set `cube.enabled: false` to skip the bundled Cube deployment * point the app at your external endpoint via `deployment.env.CUBEJS_API_URL` * supply `CUBEJS_API_SECRET` via `deployment.env` or `deployment.envFrom` if you disable generated secrets ### Optional Bundled Qwen/vLLM For AI The Helm chart can optionally deploy a Formbricks-provided Qwen runtime through vLLM. This is disabled by default and requires GPU-capable Kubernetes nodes. To deploy Qwen/vLLM and automatically point the Formbricks app at the in-cluster OpenAI-compatible endpoint: ```yaml theme={null} llm: enabled: true ``` With `llm.enabled: true`, the chart renders the vLLM router and Qwen serving engine, then injects the required `AI_PROVIDER=openai-compatible` app environment variables unless you override them in `deployment.env`. If you want to deploy the bundled Qwen runtime without changing the Formbricks app AI configuration: ```yaml theme={null} llm: enabled: true autoConfigureApp: false ``` Keep `llm.enabled: false` when you use Google Vertex, Azure, AWS Bedrock, or an externally managed OpenAI-compatible endpoint. Configure those providers through `deployment.env`. ### Optional AI Taxonomy Beta The Helm chart can optionally deploy the standalone taxonomy service. This is disabled by default and does not force the bundled Qwen/vLLM runtime. To deploy taxonomy and reuse the bundled Qwen/vLLM runtime: ```yaml theme={null} llm: enabled: true taxonomy: enabled: true ``` With this setup, taxonomy uses the in-cluster vLLM router for cluster labeling and 5-level taxonomy generation. The chart also injects `TAXONOMY_SERVICE_URL`, `TAXONOMY_SERVICE_TOKEN`, and `HUB_INTERNAL_API_TOKEN` into Hub API. To use your own OpenAI-compatible LLM endpoint instead, keep `llm.enabled: false` and set the taxonomy LLM values: ```yaml theme={null} taxonomy: enabled: true llm: model: qwen3-14b-awq baseUrl: http://my-llm-gateway:8000/v1 existingSecret: taxonomy-llm-secret ``` The `taxonomy-llm-secret` secret must contain `TAXONOMY_LLM_API_KEY`. If your endpoint does not enforce authentication, store a non-empty dummy value. To use Gemini on Vertex AI instead, keep `llm.enabled: false`, create a secret containing `TAXONOMY_GOOGLE_CLOUD_CREDENTIALS_JSON`, and configure the Vertex provider: ```yaml theme={null} taxonomy: enabled: true llm: provider: vertex-gemini model: gemini-2.5-flash vertex: project: formbricks-cloud location: europe-west3 existingSecret: taxonomy-vertex-secret ``` The service account in `TAXONOMY_GOOGLE_CLOUD_CREDENTIALS_JSON` must be allowed to call Vertex AI for the selected project and location. After startup, run the authenticated preflight check from inside the taxonomy pod: ```sh theme={null} kubectl exec -n formbricks deploy/formbricks-taxonomy -- \ python -c 'import os, urllib.request; req = urllib.request.Request("http://127.0.0.1:8000/v1/preflight", headers={"Authorization": "Bearer " + os.environ["TAXONOMY_SERVICE_TOKEN"]}); print(urllib.request.urlopen(req, timeout=10).read().decode())' ``` The taxonomy service is internal-only by default. Kubernetes probes use public `/health`; `/v1/preflight` is for operator validation and requires the internal taxonomy bearer token. ## 4. Upgrade The Deployment ### Upgrading from v5 to v6 Use the [v6 maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade) for the complete procedure, temporary Job template, and recovery instructions. Use only an upgrade pair listed as tested in the target release notes. Pin the target Formbricks image by digest and the matching chart version; preserve existing database, storage, and Secret bindings. **1. Enter maintenance and take backups** Prepare private SpiceDB connectivity and complete its datastore migrations before the application upgrade. Suspend GitOps reconciliation, autoscalers, image updaters, and schedules that could restart writers. Stop all writers, including application replicas, Hub/workflow workers, running Jobs, and external integrations, then wait for in-flight work and database transactions to finish. Take recoverable backups after writers stop and keep maintenance active through preparation and access verification. **2. Prepare with the target v6 image** Run an explicit, temporary Kubernetes Job using the exact target image and the database/AuthZed environment bindings that v6 will use, including `AUTHZED_CONSISTENCY=fully_consistent`. Run this command in that Job, not in an existing v5 application pod: ```bash theme={null} formbricks-authzed-prepare --backup-confirmed --writers-stopped ``` The command validates configuration and SpiceDB health, runs application database migrations, prepares the schema, drains the outbox, repairs relationships, and performs a separate final `upgrade check`. The flags acknowledge prerequisites you have already verified; they do not stop workloads or take backups. Review any non-empty schema mismatch using the guide's guarded replacement procedure. **3. Deploy only after preparation succeeds** Require the preparation Job to exit `0`, then set `authzed.migrationAcknowledged: true` and deploy the same image digest with the reviewed chart version. The Helm pre-upgrade hook verifies the prepared graph; it does not run database migrations, apply the schema, or backfill relationships. Verify authorization and outbox delivery before restoring controllers, workers, and public traffic as described in the guide. > [!WARNING] > > If preparation fails, remain in maintenance. After database changes, `helm rollback` or switching back to a > v5 image may be unsafe; recovery may require restoring the coordinated backups. `/health` alone does not > establish authorization readiness. ### Later chart upgrades For later v6 upgrades, follow the target release's compatibility and maintenance notes. A changed canonical SpiceDB schema requires explicit preparation again; a previous migration acknowledgement does not bypass verification. For a compatible routine upgrade: ```sh theme={null} helm upgrade formbricks oci://ghcr.io/formbricks/helm-charts/formbricks \ -n formbricks \ --version \ -f values.yaml ``` For a Formbricks 4.x to 5.0 migration, confirm the following before running the upgrade: * Hub remains enabled * `HUB_API_KEY` is present * your edge rate-limiting plan is in place * any required `AI_*` variables are added * `CUBEJS_API_SECRET` is configured (the generated app secret supplies it by default; provide an external endpoint if you set `cube.enabled: false`) If the `formbricks-migration` Job fails during any upgrade, follow [If a migration fails](/docs/self-hosting/advanced/migration#if-a-migration-fails) before upgrading again. ## 5. Key Values | Field | Description | | - | - | | `formbricks.webappUrl` | Public base URL for the Formbricks app | | `deployment.image.tag` | Formbricks image tag override | | `hub.enabled` | Must stay `true` in Formbricks v5 | | `hub.image.tag` | Hub image tag override | | `envoy.enabled` | Enables chart-managed Envoy Gateway resources | | `envoy.controller.enabled` | Installs the bundled Envoy controller when `true` | | `envoyRedis.enabled` | Deploys a dedicated Redis backend for Envoy rate limiting | | `llm.enabled` | Deploys the optional bundled Qwen/vLLM runtime | | `llm.autoConfigureApp` | Injects Formbricks OpenAI-compatible env vars for bundled Qwen | | `taxonomy.enabled` | Deploys the optional standalone AI taxonomy service | | `postgresql.externalDatabaseUrl` | Uses an external PostgreSQL service instead of in-cluster | | `redis.externalRedisUrl` | Uses an external Redis/Valkey service instead of in-cluster | For the complete values surface, refer to the chart README in the repository: [charts/formbricks/README.md](https://github.com/formbricks/formbricks/tree/main/charts/formbricks). ## 6. Uninstalling The Deployment To remove the deployment: ```sh theme={null} helm uninstall formbricks -n formbricks ``` If you also want to remove in-cluster persistent volumes: ```sh theme={null} kubectl delete pvc --all -n formbricks ``` # Monitoring Source: https://formbricks.com/docs/self-hosting/setup/monitoring Monitoring your Formbricks installation for optimal performance. ## Logging Formbricks follows Next.js best practices with all logs being written to stdout/stderr, making it easy to collect and forward logs to your preferred logging solution. ### Log Levels * `debug`: Detailed information for debugging purposes. * `info`: General information about the system's operation. * `warn`: Potential issues that may require attention. * `error`: Errors that occur during the operation of the system. * `fatal`: Critical errors that cause the system to crash. ### Log Format Formbricks uses JSON format for logs, which is structured and easy to parse. Each log entry includes: * `level`: The log level (e.g., info, error). * `time`: Timestamp of the log entry in milliseconds since epoch. * `pid`: Process ID of the application. * `hostname`: Hostname of the server where the log was generated. * `requestId`: Unique identifier for the request (if applicable). * `userId`: Unique identifier for the user (if applicable). * `msg`: The log message. * `stack`: Stack trace (if applicable). * `data`: Additional data related to the log entry. ### Example Log Entry ```json theme={null} { "hostname": "server-1", "level": 30, "msg": "User logged in successfully", "pid": 12345, "requestId": "abc-123", "time": 1710000000000, "userId": "user-789" } ``` ### Configuring Log Levels You can configure the minimum log level using the `LOG_LEVEL` environment variable. Valid values: `debug`, `info`, `warn`, `error`, `fatal`. The default log level in production environments is `warn`, while in development environments it is `debug`. ```env theme={null} LOG_LEVEL=debug ``` ### AccessDocker Container Logs ```bash theme={null} # One-Click setup cd formbricks docker compose logs # Standard Docker commands docker logs docker logs -f # Follow logs ``` ### Access Kubernetes Pod Logs ```bash theme={null} kubectl logs -n kubectl logs -f -n # Follow logs ``` ### Log Forwarding Since all logs are written to stdout/stderr, you can integrate with various logging solutions: * ELK Stack (Elasticsearch, Logstash, Kibana) * Fluentd/Fluent Bit * Datadog * Splunk * CloudWatch Logs (AWS) ## OpenTelemetry Integration Formbricks offers two complementary observability approaches: 1. **Next.js OpenTelemetry** - For tracing and APM integration 2. **Prometheus Integration** - For metrics collection and monitoring ### Next.js OpenTelemetry for Tracing Formbricks leverages Next.js's built-in OpenTelemetry instrumentation for tracing and APM integration. When enabled, it automatically instruments various aspects of your application, providing detailed insights into request flows and performance. To enable Next.js OpenTelemetry, set the following environment variables: ```env theme={null} OTEL_ENABLED=true OTEL_ENDPOINT= # e.g., http://localhost:4318/v1/traces for OTLP HTTP OTEL_SERVICE_NAME=formbricks NEXT_OTEL_VERBOSE=1 # Optional: enables detailed tracing ``` #### Default Next.js Instrumentation The Next.js OpenTelemetry integration automatically tracks: * HTTP requests and responses * Route rendering * API route execution * Server-side operations * Database queries * External API calls #### Supported Backends for Tracing OpenTelemetry trace data can be exported to various observability platforms: ##### Tracing Backends * Jaeger * Zipkin * Tempo ##### APM & Full-Stack Observability Platforms * New Relic * Datadog * Dynatrace * Azure Monitor * AWS X-Ray * Google Cloud Trace ## Prometheus Integration Formbricks implements a dedicated Prometheus metrics exporter using OpenTelemetry. This integration runs a metrics server on a separate port and exposes metrics in Prometheus format for scraping. It focuses specifically on host and runtime metrics rather than application-specific traces. ### Configuration To enable and configure the Prometheus exporter, set the following environment variables: ```env theme={null} PROMETHEUS_ENABLED=1 PROMETHEUS_EXPORTER_PORT=9464 # Optional, defaults to 9464 ``` The `PROMETHEUS_ENABLED` environment variable must be set to `1` to enable metrics collection. The `PROMETHEUS_EXPORTER_PORT` variable is optional and defaults to 9464 if not specified. The exporter listens on all network interfaces (0.0.0.0) and exposes metrics at the `/metrics` endpoint. ### Available Metrics The metrics exported by the Prometheus integration include: * **Host Metrics**: * CPU usage (user, system, idle) * Memory usage (used, free, cached) * Disk I/O (reads, writes) * Network I/O (bytes in/out, packets in/out) * **HTTP Metrics**: * Request counts * Request durations * Error rates * **Runtime Metrics**: * Garbage collection frequency and duration * Event loop lag * Heap statistics (size, used, available) * **v3 Responses API Metrics** — the two counters and the two `unresolved` counters below are exported under exactly these series names through both the Prometheus exporter and an OTLP collector. The two histograms are metric *families*: querying the family name returns nothing, and their queryable series are the `_bucket`, `_sum` and `_count` suffixes. * `formbricks_api_v3_responses_reads_total` — one count per list, count or get, at the route boundary, so a 401, 429 or 400 counts too. Attributes: `operation`, `via` (`ui`, `api`, `mcp`), `status_class`, and `filters` (the sorted filter keys the caller used, never their values). * `formbricks_api_v3_responses_read_duration_seconds` (histogram family) — wall-clock seconds per read, by `operation`, `via` and `status_class`. Series: `formbricks_api_v3_responses_read_duration_seconds_bucket`, `..._sum`, `..._count`. For example, the p95 per operation: `histogram_quantile(0.95, sum by (le, operation) (rate(formbricks_api_v3_responses_read_duration_seconds_bucket[5m])))`. * `formbricks_api_v3_responses_page_surveys` (histogram family) — how many distinct surveys one list page spans, i.e. the size of its single survey query. Series: `formbricks_api_v3_responses_page_surveys_bucket`, `..._sum`, `..._count`. The first bucket boundary is `0.5`, so `formbricks_api_v3_responses_page_surveys_bucket{le="0.5"}` counts empty pages and is distinguishable from one-survey pages. * `formbricks_api_v3_responses_unresolved_responses_total` and `formbricks_api_v3_responses_unresolved_entries_total` — responses served with a non-empty `unresolved[]`, and its entries by `reason`. These count every *read*, so a client polling one unchanged response raises them without any survey edit, and `valueShapeMismatch` can be legacy malformed data rather than a definition change. Read `unresolved_responses_total` over `reads_total` by `operation` as unresolved responses served per read (a list page can carry several, so for `list` this can exceed 1; for `get` it is the share of affected reads), and use `unresolved_entries_total` grouped by `reason` for the breakdown, rather than a rising raw count. ### Collecting Metrics You can scrape metrics from your Prometheus server by adding the following to your Prometheus configuration: ```yaml theme={null} scrape_configs: - job_name: "formbricks" static_configs: - targets: ["your-formbricks-host:9464"] ``` ### Resource Attributes The metrics include resource attributes automatically detected from: * Environment variables * Process information * Host information These attributes can help you filter and group metrics in your dashboards. ## Health Checks Available endpoints: ``` GET /health ``` Use these endpoints for monitoring system health in container orchestration and monitoring tools. ## AuthZed and SpiceDB Self-hosted v6 upgrades use a maintenance window and do not require a v5 bridge or shadow comparisons. Monitor projection failures, disabled outcomes, schema drift, authorization operational errors, and latency. The v6 direct-authority release exposes authoritative allow/deny/operational-error and latency metrics plus outbox backlog, revocation delivery latency, oldest pending item, dead-letter, reconciliation drift, and repair signals. The fixed revocation thresholds warn at 15 seconds, become critical at 45 seconds, and make protected authorization fail closed at 60 seconds; the 60-second bound is not configurable. A dead-lettered revocation triggers warning, critical, and fail-closed states immediately, regardless of its age. Follow the release-matched [AuthZed Operations guide](/docs/self-hosting/configuration/authzed-operations) during upgrade rather than treating v5 comparison metrics as a v6 rollout gate. For every release, also monitor SpiceDB pod availability, datastore migrations, PostgreSQL pool saturation, dispatch latency, and cache behavior. The general Formbricks `/health` endpoint intentionally stays independent from SpiceDB. Use the release-matched `formbricks-authzed health` command for authenticated authorization health checks. The [AuthZed Operations guide](/docs/self-hosting/configuration/authzed-operations) contains metric names, PromQL examples, starting alert thresholds, stable error codes, and the outage-repair runbook. # One-Click Setup Source: https://formbricks.com/docs/self-hosting/setup/one-click How to set up Formbricks instance with a one-click script > [!NOTE] > > This only works with an Ubuntu machine, so ensure the underlying OS is verified beforehand! If you’re looking to quickly set up a production instance of Formbricks on an Ubuntu server, this guide is for you. Using a convenient shell script, you can install everything—including Docker, Postgres DB, SpiceDB, and an SSL certificate—in just a few steps. The script takes care of all the dependencies and configuration for your server, making the process smooth and simple. > [!NOTE] > > This setup uses **Traefik** as a **reverse proxy**, essential for directing incoming traffic to the correct > container and enabling secure internet access to Formbricks. Traefik is chosen for its simplicity and > automatic SSL management via Let’s Encrypt. > [!WARNING] > > The bundled RustFS option in this one-click setup is designed for convenience on a single server. It is a > good fit for small-scale or low-complexity self-hosted deployments, but it is not the ideal RustFS > architecture for high-availability or larger production environments. For stricter production requirements, > use external object storage or run a dedicated RustFS deployment separately from the Formbricks one-click > stack. > [!NOTE] > > The installer stores generated PostgreSQL, Hub, Cube, and AuthZed credentials in `./formbricks/.env` and > restricts the file to `0600`. PostgreSQL has a raw password for the database plus a URL-encoded companion for > connection strings. When bundled RustFS is enabled, its generated credentials are stored there too. Keep that > file private, include it in your server backup plan, and avoid checking it into source control or copying it to > shared locations. > [!NOTE] > > For better RustFS performance and stability, prefer local SSD or NVMe-backed storage for the host volume > behind `rustfs-data`. Avoid NFS and other network filesystems for bundled RustFS data, and use XFS on > dedicated storage disks when you manage the host layout yourself. For other operating systems or a more customized installation, please refer to the advanced installation guide with [Docker](/docs/self-hosting/setup/docker). ### Requirements * An Ubuntu Virtual Machine with SSH access. * A custom domain with an **A record** pointing to your server. * Ports **80** and **443** are open in your VM's Security Group, allowing Traefik to create an SSL certificate. ### Deployment Run this command in your terminal: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/formbricks.sh -o formbricks.sh && chmod +x formbricks.sh && ./formbricks.sh install ``` > [!NOTE] > > The v6 one-click stack is based on the production Docker Compose file and includes the Formbricks Hub API, > `hub-worker`, and Cube as part of the baseline (Cube configuration lives under `formbricks/cube/`). Ensure your > generated `formbricks/docker-compose.yml` contains the worker service and a non-empty `HUB_API_KEY`, and that > `formbricks/.env` contains `CUBEJS_API_SECRET`, `AUTHZED_TOKEN`, and `AUTHZED_DATABASE_PASSWORD` before > treating the stack as ready. The installer generates these values without printing them and restricts `.env` > to `0600`. `HUB_API_URL` should normally stay at `http://hub:8080`. Bundled SpiceDB is installed for every new > setup and does not require an Enterprise license check. > [!NOTE] > > The v5 one-click Traefik setup also exposes Hub-backed FeedbackRecords through Formbricks at > `/api/v3/feedbackRecords` and `/v1/feedback-records`. Traefik calls the internal Formbricks gateway auth > endpoint first, then forwards allowed requests to Hub with the generated `HUB_API_KEY`. Browser callers should > request short-lived gateway tokens from `/api/v3/gateway/token` with `{ "service": "feedbackRecords" }`. ### Script Prompts During installation, the script will prompt you to provide some details: * **Overwriting Docker GPG Keys**: If Docker GPG keys already exist, the script will ask whether you want to overwrite them. ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) ``` * **Domain Name**: Enter the domain name where you’ll host Formbricks. The domain will be used to generate an SSL certificate. Do not include the protocol (http/https). ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): ``` * **HTTPS Certificate Setup**: The script will ask if you’d like to create an HTTPS certificate for your domain. Enter `Y` to proceed (highly recommended for secure access). ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): my.hosted.url.com 🔗 Do you want us to set up an HTTPS certificate for you? [Y/n] ``` * **DNS Setup Prompt**: Ensure that your domain's DNS is correctly configured and ports 80 and 443 are open. Confirm this by entering `Y`. This step is crucial for proper SSL certificate issuance and secure server access. ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): my.hosted.url.com 🔗 Do you want us to set up an HTTPS certificate for you? [Y/n] Y 🔗 Please make sure that the domain points to the server's IP address and that ports 80 & 443 are open in your server's firewall. Is everything set up? [Y/n] ``` * **Email Address for SSL Certificate**: Provide an email address to register the SSL certificate. Notifications regarding the certificate will be sent to this address. ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): my.hosted.url.com 🔗 Do you want us to set up an HTTPS certificate for you? [Y/n] Y 🔗 Please make sure that the domain points to the server's IP address and that ports 80 & 443 are open in your server's firewall. Is everything set up? [Y/n] Y 💡 Please enter your email address for the SSL certificate: ``` * **Enforce HTTPS with HSTS**: Enabling HTTP Strict Transport Security (HSTS) ensures all communication with your server is encrypted. It’s a recommended best practice. Enter `Y` to enforce HTTPS. ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): my.hosted.url.com 🔗 Do you want us to set up an HTTPS certificate for you? [Y/n] Y 🔗 Please make sure that the domain points to the server's IP address and that ports 80 & 443 are open in your server's firewall. Is everything set up? [Y/n] Y 💡 Please enter your email address for the SSL certificate: docs@formbricks.com 🔗 Do you want to enforce HTTPS (HSTS)? [Y/n] ``` * **Email Service Setup Prompt**: The script will ask if you want to set up the email service. Enter `Y` to proceed.(default is `N`). You can skip this step if you don't want to set up the email service. You will still be able to use Formbricks without setting up the email service. ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): my.hosted.url.com 🔗 Do you want us to set up an HTTPS certificate for you? [Y/n] Y 🔗 Please make sure that the domain points to the server's IP address and that ports 80 & 443 are open in your server's firewall. Is everything set up? [Y/n] Y 💡 Please enter your email address for the SSL certificate: docs@formbricks.com 🔗 Do you want to enforce HTTPS (HSTS)? [Y/n] Y 🚗 Configuring Traefik... 💡 Created traefik.yaml and traefik-dynamic.yaml file. 💡 Created acme.json file with correct permissions. 📧 Do you want to set up the email service? You will need SMTP credentials for the same! [y/N] ``` **That's it**! After running the command and providing the required information, visit the domain name you entered, and you should see the Formbricks home wizard! ``` 🚀 Executing default step of installing Formbricks 🧱 Welcome to the Formbricks Setup Script 🛸 Fasten your seatbelts! We're setting up your Formbricks environment on your Ubuntu 24.04 LTS server. 🧹 Time to sweep away any old Docker installations. 🔄 Updating your package list. 📦 Installing the necessary dependencies. 🔑 Adding Docker's official GPG key and setting up the stable repository. File '/etc/apt/keyrings/docker.gpg' exists. Overwrite? (y/N) y 🔄 Updating your package list again. 🐳 Installing Docker. 🚀 Testing your Docker installation. 🎉 Docker is installed! 🐳 Adding your user to the Docker group to avoid using sudo with docker commands. 🎉 Hooray! Docker is all set and ready to go. You're now ready to run your Formbricks instance! 📁 Created Formbricks Quickstart directory at ./formbricks. 🔗 Please enter your domain name for the SSL certificate (🚨 do NOT enter the protocol (http/https/etc)): my.hosted.url.com 🔗 Do you want us to set up an HTTPS certificate for you? [Y/n] Y 🔗 Please make sure that the domain points to the server's IP address and that ports 80 & 443 are open in your server's firewall. Is everything set up? [Y/n] Y 💡 Please enter your email address for the SSL certificate: docs@formbricks.com 🔗 Do you want to enforce HTTPS (HSTS)? [Y/n] Y 🚗 Configuring Traefik... 💡 Created traefik.yaml and traefik-dynamic.yaml file. 💡 Created acme.json file with correct permissions. 📧 Do you want to set up the email service? You will need SMTP credentials for the same! [y/N] N 📥 Downloading docker-compose.yml from Formbricks GitHub repository... % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 6632 100 6632 0 0 24280 0 --:--:-- --:--:-- --:--:-- 24382 🚙 Updating docker-compose.yml with your custom inputs... 🚗 BETTER_AUTH_SECRET updated successfully! 🚗 ENCRYPTION_KEY updated successfully! 🚗 CRON_SECRET updated successfully! [+] Running 4/4 ✔ Network formbricks_default Created 0.2s ✔ Container formbricks-postgres-1 Started 1.0s ✔ Container formbricks-formbricks-1 Started 1.6s ✔ Container traefik Started 2.8s 🔗 To edit more variables and deeper config, go to the formbricks/docker-compose.yml, edit the file, and restart the container! 🚨 Make sure you have set up the DNS records as well as inbound rules for the domain name and IP address of this instance. 🎉 All done! Please setup your Formbricks instance by visiting your domain at https://my.hosted.url.com. You can check the status of Formbricks & Traefik with 'cd formbricks && sudo docker compose ps.' ``` ## Update To update Formbricks for a minor or patch release, first go to the directory that contains your `formbricks/` folder. Download the current stable updater there, replacing any older `formbricks.sh`, and then run it: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/formbricks/formbricks/stable/docker/formbricks.sh \ -o formbricks.sh chmod +x formbricks.sh ./formbricks.sh update ``` The script first validates the resolved Compose project and warns — without stopping — when the baseline `hub-worker` is missing, then pulls images and runs the read-only AuthZed upgrade check. A failed preflight leaves the existing application running. Otherwise it stops the stack, waits for PostgreSQL, completes application migrations, and only then starts the new stack. A failed migration leaves the stack stopped for recovery; preparation is never run against a live installation by the updater. Once those checks pass, the update also publishes the Formbricks container's port `3000` on `127.0.0.1` only, if your `docker-compose.yml` or your Compose override file (such as `docker-compose.override.yml`) still publishes it on every interface (`- 3000:3000`). Traefik reaches Formbricks over the Compose network and keeps serving it on ports `80` and `443`, so outside traffic always passes through Traefik. Each file it changes is kept as `.before-loopback-port`. Before stopping anything, it renders the Compose files exactly as Docker Compose will load them and checks that they publish port `3000` once, on `127.0.0.1`; if not, it restores the files it changed and continues the update with the port as it was. A mapping with an address you chose, such as `- 0.0.0.0:3000:3000`, is left as it is, and so is everything when `.env` sets `COMPOSE_FILE`. On Docker Engine before 28.0, and on 28.2.0 to 28.3.2, other machines on your local network can still reach a port published on `127.0.0.1`, so the installer and the update warn you to upgrade Docker. Starting with v5.4, the updater also recognizes the old amd64-only bundled Valkey digest. It backs up your Compose file, replaces only that exact image reference with the native amd64/arm64 digest, and validates the result before pulling. An already-updated or custom Valkey image is left unchanged. The named `redis` volume and its AOF data are preserved. While the stack is stopped, the updater also refreshes the bundled Cube model (`cube/cube.js` and `cube/schema/FeedbackRecords.js`), so analytics charts can use members a release adds. It downloads the files of the release your Formbricks image runs: the `stable` branch for `latest`, or the tag the image is pinned to. It keeps the previous files in `cube/previous/`. The two files change together: if either cannot be downloaded, backed up or replaced, both stay as they were, the update finishes, and the updater prints the command to retry, `./formbricks.sh refresh-cube`. An image pinned to anything else, such as a digest, leaves both files unchanged. Existing one-click installations keep the database credentials in their local `docker-compose.yml` or `.env`. The update command does not regenerate or rotate them. > [!WARNING] > > Apart from the exact v5.4 Valkey pin migration and the port `3000` narrowing described above, > `./formbricks.sh update` does **not** rewrite your existing `formbricks/docker-compose.yml`. For a major migration such as Formbricks 4.x to 5.0, follow > the [migration guide](/docs/self-hosting/advanced/migration#v5) first, merge the current v5 Compose changes into > your existing deployment, confirm `HUB_API_KEY` is set, and only then run the update command. If your older > one-click install also uses bundled MinIO for file uploads, review that storage path separately before the > first v5 restart; newer self-hosting updates move the bundled object-storage path to RustFS, while external > S3-compatible storage keeps the same `S3_*` app contract. The updater warns and continues when the Compose > project is missing the release-matched `hub-worker`; adding it is recommended, and the next major release will > require it — see the > [Hub worker migration](/docs/self-hosting/advanced/migration#hub-worker-for-docker). The v6 updater also requires the > release-matched AuthZed services and requires `.env` to contain > `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true` after a clean preparation. > > The same applies to pinned third-party images. Because the update command only re-pulls what your Compose > file already names, a bundled `rustfs` service stays on whatever version it was installed with — `docker > compose pull` cannot move a pinned tag. To take a newer RustFS, edit the `image:` line of the `rustfs` > service in `formbricks/docker-compose.yml` to match the version in the [Docker > guide](/docs/self-hosting/setup/docker), then run the update command. Your `rustfs-data` volume is reused as-is; > roll back by restoring the previous `image:` line. ### Add SpiceDB to an Existing One-Click Installation The update command intentionally preserves your customized Compose file, so it cannot add SpiceDB by itself. Before upgrading to a release that uses AuthZed: 1. Follow the [maintenance upgrade guide](/docs/self-hosting/advanced/v6-maintenance-upgrade): stop writers and controllers, drain in-flight work, then back up configuration, secrets, and databases. 2. Download the release-matched `authzed-postgres-bootstrap.sh` into the `formbricks` directory. 3. Generate and add `AUTHZED_TOKEN` and `AUTHZED_DATABASE_PASSWORD` to `.env` using `openssl rand -hex 32`. 4. Merge `authzed-db-bootstrap`, `spicedb-migrate`, `spicedb`, `authzed-initialize`, and the profiled `authzed-ops` service from the released Compose file while preserving installer-added Traefik, storage, and mail configuration. Add the six application variables and use `AUTHZED_CONSISTENCY=fully_consistent`. 5. Validate the target Compose file privately and pull the pinned images from the `formbricks` directory. Keep maintenance active and writers stopped. 6. Wait for the datastores, then run migrations, preparation, and verification using the target image: ```bash theme={null} docker compose up -d --wait postgres spicedb docker compose --profile authzed-ops run --rm --no-deps \ --entrypoint formbricks-authzed-prepare authzed-ops \ --backup-confirmed --writers-stopped ``` A mismatched non-empty schema requires the reviewed digest described in the maintenance guide. 7. If preparation exits `0`, add `FORMBRICKS_AUTHZED_V6_MIGRATION_ACKNOWLEDGED=true` to `.env` and run `./formbricks.sh update`. Do not bypass a blocked check. Keep maintenance active until access tests pass. 8. Verify `authzed-db-bootstrap`, `spicedb-migrate`, and `authzed-initialize` completed and `spicedb` is healthy. 9. Back up the authorization database with `docker compose exec -T postgres pg_dump -U postgres -d spicedb > spicedb-backup.sql` and add it to your regular backup procedure. Do not use `docker compose down -v` during this migration or rollback because the existing PostgreSQL volume stores both Formbricks and SpiceDB data. For upgrades, restoration, schema changes, and relationship repair, follow the canonical [AuthZed Operations guide](/docs/self-hosting/configuration/authzed-operations). ## Stop To stop Formbricks, simply run the following command: ``` ./formbricks.sh stop ``` The script will automatically stop all the Formbricks related containers and brings the entire stack down. ## Restart To restart Formbricks, simply run the following command: ``` ./formbricks.sh restart ``` The script will automatically restart all the Formbricks related containers and brings the entire stack up with the previous configuration. ## Cleanup RustFS init (optional) During the one-click setup, a temporary `rustfs-init` service configures RustFS (bucket, policy, service user). It is idempotent and safe to leave in place; it will do nothing on subsequent starts once the configuration exists. If you prefer to remove the `rustfs-init` service and its references after a successful setup, run: ``` ./formbricks.sh cleanup-rustfs-init ``` `./formbricks.sh cleanup-minio-init` is still available as a backward-compatible alias. This only removes the init job and its Compose references; it does not delete any data or affect your RustFS configuration. ## Uninstall To uninstall Formbricks, simply run the following command, but keep in mind that this will delete all your data! ``` ./formbricks.sh uninstall ``` The script will automatically stop all the Formbricks related containers, remove the Formbricks directory, and delete the Docker network. ## Debug If you encounter any issues, you can check the logs of the containers with: ``` ./formbricks.sh logs ``` ## Troubleshooting If you encounter any issues, consider the following steps: * **Inbound Rules**: Make sure you have added inbound rules for Port 80 and 443 in your VM's Security Group. * **A Record**: Verify that you have set up an A record for your domain, pointing to your VM's IP address. * **Check Docker Instances**: Run `docker ps` to check the status of the Docker instances. * **Check Formbricks Logs**: Run `cd formbricks && docker compose logs` to check the logs of the Formbricks stack. If you have any questions or require help, feel free to reach out to us on [**GitHub Discussions**](https://github.com/formbricks/formbricks/discussions). 😃[ ](https://formbricks.com/docs/developer-docs/rest-api) # Reading Survey Results Source: https://formbricks.com/docs/surveys/analysis/reading-results Every activated survey has two views: a Summary that aggregates answers question by question, and a Responses table with one row per submission. Open any survey and you land on its results. There are two tabs, and they answer different questions. * **Summary** — what did people say, in aggregate? * **Responses** — what did *this* person say? ## Summary The Summary tab opens with five figures for the survey as a whole, then a card per question. ![The survey summary, with completion stats and per-question breakdowns](https://mintcdn.com/formbricks/Glz_qG2pDZ_zNBao/images/surveys/analysis/summary.webp?fit=max\&auto=format\&n=Glz_qG2pDZ_zNBao\&q=85\&s=30b278ab90886cc9f779658ff636e2cf) The headline figures: | Figure | What it counts | | - | - | | **Impressions** | How many times the survey was displayed. | | **Starts** | How many people began answering, with the share of impressions. | | **Completed** | How many reached the end. | | **Drop-Offs** | How many started but did not finish, with the share of starts. | | **Time to Complete** | How long a completed response takes, once there are enough to average. | Below them, each question gets its own card in survey order. What the card shows depends on the question: open text lists individual answers, choice questions show each option with its share, and rating-style questions show the distribution. ## Responses The Responses tab is one row per submission, with a column per question. ![The response table, one row per submission](https://mintcdn.com/formbricks/Glz_qG2pDZ_zNBao/images/surveys/analysis/responses.webp?fit=max\&auto=format\&n=Glz_qG2pDZ_zNBao\&q=85\&s=e75af97388bd814e93bf3e99eac3a6da) The table also carries columns you did not ask for directly: * **Status** — whether the response was completed or abandoned part-way. * **Person** — the [contact](/docs/platform/features/contacts) who answered, or *Anonymous*. * **Tags** — any [tags](/docs/surveys/general-features/tags) applied to the response. * **[Hidden fields](/docs/surveys/general-features/hidden-fields)** — values passed in with the survey rather than answered. * **[Metadata](/docs/surveys/general-features/metadata)** — source, URL, browser, OS, device and country. The table is wide, so scroll horizontally to reach the later columns, or use the column settings to hide the ones you do not need. ## Filtering and exporting Both tabs share the same **Filter** and time-range controls at the top, so a filter you set on the Summary carries to the Responses table. Filter on any answer, tag, hidden field or metadata value. **Download** offers three scopes, each as CSV or Excel: * **All responses** — everything, ignoring the current filter. * **Filtered responses** — only what the current filter matches. * **Selected responses** — only the rows you ticked in the table. # Churn Survey Source: https://formbricks.com/docs/surveys/best-practices/cancel-subscription Learn why customers cancel their subscription, at the moment they cancel. A churn survey asks why someone is leaving, at the one moment they are certain of the answer. ## Purpose Asked a week later by email, the answer is a rationalisation. Asked at the click of the cancel button, it is the reason. ## 1. Start from the template Open **Surveys**, click **New Survey** and choose **Choose a template**. Search for **Churn Survey**, then click the card to create the survey. ![The Churn Survey template in the template picker](https://mintcdn.com/formbricks/5gmPPlpgcBxnNfUX/images/surveys/best-practices/cancel-subscription/template.webp?fit=max\&auto=format\&n=5gmPPlpgcBxnNfUX\&q=85\&s=01c5a3b37f283dcc6d715a2bce321704) The template asks for a reason and then for detail. Keep it to that: someone mid-cancellation will not fill in a long form. ## 2. Trigger it at the right moment The trigger is your cancel button. Open the **Settings** tab, find **Survey Trigger** and add an action that matches it — **Inner Text** `Cancel Subscription` is usually enough, and a **CSS Selector** such as `#cancel-subscription` is better if more than one button carries that label. ![The Survey Trigger section with the action attached](https://mintcdn.com/formbricks/5gmPPlpgcBxnNfUX/images/surveys/best-practices/cancel-subscription/trigger.webp?fit=max\&auto=format\&n=5gmPPlpgcBxnNfUX\&q=85\&s=648d8c1f819c097c85a27313cec68de2) > [!TIP] > > Creating the action itself — Click versus Page View, Inner Text versus CSS Selector — is the same dialog > in every recipe. It is walked through once on the [Feedback Box](/docs/surveys/best-practices/feedback-box) > page, and the full reference is the [Actions manual](/docs/surveys/website-app-surveys/actions). ## 3. Decide how often it may appear Still on **Settings**, open **Display & Recontact**. Choose **Show only once**. A cancellation is a one-time event, and someone who has already answered should not be asked twice. > [!NOTE] > > Recontact Options and the workspace-wide [Cooldown Period](/docs/surveys/website-app-surveys/cooldown-period) > are two separate gates and a survey has to pass both — Recontact Options first, then the cooldown. If > your workspace shows at most one survey a week, this survey inherits that unless you set **Ignore > Cooldown Period**. ## 4. Activate **Activate** starts it. The widget picks up the change within a minute. > [!NOTE] > > This is an app survey, so it needs the Formbricks widget running in your product. If you have not > installed it yet, follow [the quickstart](/docs/surveys/website-app-surveys/quickstart) first. # Contact Form Source: https://formbricks.com/docs/surveys/best-practices/contact-form Build a contact form as a Formbricks survey and embed it on your website. A contact form is a survey that happens to sit on a website. Building it in Formbricks means the submissions land where the rest of your feedback already is, rather than in an inbox. ## What you will build A four-question form — name, email, reason for contact, message — embedded on a page of your site. ## 1. Create a link survey Open **Surveys**, click **New Survey** and choose **Start from scratch**. Then open **Settings → Survey Type** and make sure **Link survey** is selected. > [!NOTE] > > Check it rather than assuming it. A new survey inherits its type from the workspace channel you picked > during onboarding, so a workspace set up for a website or app creates **app** surveys by default — only > a workspace with no channel set defaults to link. ## 2. Add the questions Four questions, each a standard type documented in its own page: | Field | Question type | Notes | | - | - | - | | Name | [Free text](/docs/surveys/question-type/free-text) | Text input | | Email | [Free text](/docs/surveys/question-type/free-text) | Set the input type to **Email** so the address is validated | | Reason for contact | [Select single](/docs/surveys/question-type/select-single) | Sales, support, something else — keep the list short | | Message | [Free text](/docs/surveys/question-type/free-text) | Switch on **Long answer** | > [!TIP] > > Use [validation rules](/docs/surveys/general-features/validation-rules) on the message — a minimum length of > 20 characters or so filters out the "hi" submissions without annoying anyone with something real to say. Turn off the welcome card unless you want an extra click before the form, and edit the ending card to say what happens next: how soon someone will reply is the one thing every person filling in a contact form wants to know. ## 3. Embed it on your site Open the survey's **Distribute** dialog and choose **Website embed**. ![The Website embed panel of the Distribute dialog](https://mintcdn.com/formbricks/iXG9xO1vWD0VUZc9/images/surveys/best-practices/contact-form/embed.webp?fit=max\&auto=format\&n=iXG9xO1vWD0VUZc9\&q=85\&s=dc3d8edc7a27ea1540fffcbdf494d78a) Copy the snippet into the page where the form should appear. The embed is an iframe, so it needs no widget and no SDK — this works on a static site. > [!NOTE] > > A contact form is a link survey, not an app survey. It does not need the Formbricks widget, and none > of the [app survey](/docs/surveys/website-app-surveys/quickstart) targeting applies to it. ## 4. Handle what comes in Submissions arrive in the survey's **Responses** tab. Two things worth setting up before you announce the form: * A [Workflow](/docs/workflows/overview) that emails an internal teammate — support, sales, whoever answers — on **Response completed**, so nothing waits on someone remembering to check the tab. The literal address you put in the **Send email** action has to belong to a member of this workspace; the workflow will not enable otherwise. To acknowledge the sender instead, point the recipient at the Email question rather than at a literal address. * [Tags](/docs/surveys/general-features/tags), so sales and support enquiries stay separable. # Docs Feedback Source: https://formbricks.com/docs/surveys/best-practices/docs-feedback A step-by-step guide to getting feedback on your Documentation with Formbricks Docs Feedback allows you to measure how clear your documentation is. ## Purpose Your users don’t spend as much time thinking about your product as you do. To fight the "Curse of Knowledge" you have to measure how clear your docs are. ## Installation To get this running, you'll need a bit of time. Here are the steps we're going through: * Set up Formbricks Cloud * Build the frontend * Connect to API * Test ## 1. Setting up Formbricks Cloud Create a [Formbricks Cloud](https://app.formbricks.com/auth/signup) account, then a survey from the **Docs Feedback** template — **New Survey → Choose a template**, then search for it. ### Make it a link survey Open **Settings → Survey Type** and make sure **Link survey** is selected. A new survey inherits its type from the workspace channel chosen during onboarding, so a workspace set up for a website or app creates **app** surveys by default — check it rather than assuming it. This matters more than it looks. You are going to post responses to the client API from your own frontend, so nothing here uses the Formbricks widget. An **app** survey cannot be activated without a trigger — `survey-menu-bar.tsx` refuses to save one with no triggers — which is why older versions of this guide told you to invent an action that never fires. A link survey has no such requirement, so the workaround is unnecessary. ### Set the question IDs The frontend below refers to questions by ID, so give them names you will recognise. Open a question, click **Show Question settings** at the foot of its card, and set the **Question ID**: | Question | ID | | - | - | | Is this page helpful? | `isHelpful` | | Please elaborate | `additionalFeedback` | | Page URL | `pageUrl` | > [!NOTE] > > The **answers** must match the frontend too. If you replace "Yes 👍" and "No 👎" with your own wording, change the choices in the code below to match — they are compared as strings. > [!WARNING] > > Question IDs can only be changed **before** a survey is activated. Afterwards they are fixed, because the responses already collected refer to them. Set them now. Activate the survey. ## 2. Build the frontend > [!NOTE] > > Your frontend might work differently Your frontend likely looks and works > differently. This is an example specific to our tech stack. We want to > illustrate what you should consider building yours. Before we start, lets talk about the widget. It works like this: * Once the user selects yes/no, a partial response is sent to the Formbricks API. It includes the feedback and the current page url. * Then the user is presented with an additional open text field to further explain their choice. Once it's submitted, the previous response is updated with the additional feedback. This allows us to capture and analyze partial feedback where the user is not willing to provide additional information. **Let's do this 👇** * Open the code editor where you handle your docs page. * Likely, you have a template file or similar which renders the navigation at the bottom of the page: ![doc navigation](https://mintcdn.com/formbricks/HVXK9qhSV5tjWeAg/images/surveys/best-practices/docs-feedback/docs-navi.webp?fit=max\&auto=format\&n=HVXK9qhSV5tjWeAg\&q=85\&s=4f0fb1f90d2ff578fd40700a675d0232) Locate that file. We are using the [Tailwind Template “Syntax”](https://tailwindui.com/templates/syntax) in this case. * Write the frontend code for the widget. Here is the full component (we break it down right below): ```tsx Entire Widget theme={null} import { Button } from "@/modules/ui/components/Button"; import { Popover, PopoverContent, PopoverTrigger } from "@/modules/ui/popover"; import { useRouter } from "next/router"; import { useState } from "react"; import { handleFeedbackSubmit, updateFeedback, } from "../../lib/handleFeedbackSubmit"; export const DocsFeedback = () => { const router = useRouter(); const [isOpen, setIsOpen] = useState(false); const [sharedFeedback, setSharedFeedback] = useState(false); const [responseId, setResponseId] = useState(null); const [freeText, setFreeText] = useState(""); if ( !process.env.NEXT_PUBLIC_FORMBRICKS_COM_DOCS_FEEDBACK_SURVEY_ID || !process.env.NEXT_PUBLIC_FORMBRICKS_COM_API_HOST || !process.env.NEXT_PUBLIC_FORMBRICKS_COM_WORKSPACE_ID ) { return null; } return (
{!sharedFeedback ? (
Was this page helpful?
{["Yes 👍", " No 👎"].map((option) => ( { const id = await handleFeedbackSubmit( option, router.asPath ); setResponseId(id); }} > {option} ))}