Workspace Environments

Overview

Workspace environments provide isolation and organization for forms, submissions, and other resources. Each user can create multiple environments (e.g., development, staging, production) to separate their work.

Environment Concept

What is an Environment?

An environment is a named workspace that isolates data and resources. Think of it as a "project" or "workspace" where you can:

  • Create and manage forms

  • Collect submissions

  • Configure webhooks

  • View analytics

  • Manage API keys

Default Environments

The system provides two default environments:

  • development - For testing and development

  • production - For live forms

Users can create additional custom environments as needed.

Environment Isolation

Data Isolation

All data is scoped by user and environment:

Partition Key Pattern:

USER#{userId}#ENV#{environment}

This ensures that:

  • Forms in different environments are completely isolated

  • Submissions are scoped to their environment

  • API keys are environment-specific

  • Analytics are environment-scoped

Storage Layer Isolation

The isolation happens at the DynamoDB storage layer:

Forms Table:

  • Base table: id + version (for public lookups)

  • GSI: userId + environment (for user queries)

Keys Table:

  • Partition Key: USER#{userId}#ENV#{environment}

  • Sort Key: KEY#{kind}#{keyId}

Submissions:

  • Indexed by formId (which includes environment context)

  • Filtered by workspaceEnvironment attribute

Environment Management

Creating an Environment

Via API:

POST /users/{userId}/environments
{
  "name": "staging"
}

Via Dashboard:

  1. Navigate to Settings

  2. Go to Environments

  3. Click "Create Environment"

  4. Enter environment name

Environment Naming Rules

  • Length: 1-50 characters

  • Characters: Lowercase letters, numbers, hyphens (-), underscores (_)

  • Format: Must match regex: /^[a-z0-9_-]+$/

  • Examples: development, staging, production, test-env, my_env

Environment Validation

The system validates environment names:

  • Rejects invalid characters

  • Rejects names that are too long or too short

  • Provides helpful error messages with default environment suggestions

Environment Usage

Creating Forms in an Environment

When creating a form, you must specify the environment:

{
  "title": "Contact Form",
  "environment": "development",
  "fields": [...]
}

The form will be created in the specified environment and isolated from forms in other environments.

Listing Forms by Environment

GET /forms?environment=development

Returns only forms in the specified environment for the authenticated user.

Environment-Scoped Queries

All queries can be scoped by environment:

  • Forms: GET /forms?environment=development

  • Submissions: GET /responses?environment=development

  • Analytics: GET /analytics?environment=development

  • Webhooks: Filtered by form's environment

API Key Environments

Environment-Specific Keys

API keys are created per environment:

Publishable Keys:

  • Scoped to a specific environment

  • Can only access forms in that environment

  • Format: pk-live-...

Secret Keys:

  • Scoped to a specific environment

  • Can only access resources in that environment

  • Format: sk_live_... or sk-live-...

Key Lookup

Keys are stored with environment context:

  • Partition Key: USER#{userId}#ENV#{environment}

  • Allows efficient lookup by user and environment

Environment Migration

Moving Forms Between Environments

Currently, forms cannot be directly moved between environments. To migrate:

  1. Export form schema from source environment

  2. Create new form in target environment

  3. Update any integrations/webhooks to point to new form

Environment Cleanup

To remove an environment:

  1. Delete all forms in the environment

  2. Delete all API keys for the environment

  3. Delete the environment via API or dashboard

Note: Deleting an environment does not automatically delete associated data. Ensure all forms and keys are removed first.

Environment Best Practices

Naming Conventions

Use clear, descriptive names:

  • ✅ development, staging, production

  • ✅ test, demo, preview

  • ❌ env1, env2, temp

Environment Strategy

Single Environment:

  • Use development for all work

  • Simple for small projects

Two Environments:

  • development - Testing and development

  • production - Live forms

Multiple Environments:

  • development - Local development

  • staging - Pre-production testing

  • production - Live forms

  • demo - Demo/showcase forms

Data Organization

  • Keep production data separate from development

  • Use staging to test form changes before production

  • Archive old environments when no longer needed

Environment in API Requests

Query Parameter

Most API endpoints accept an environment query parameter:

GET /forms?environment=development
GET /responses?environment=production
GET /analytics?environment=staging

Path Parameter (Legacy)

Some legacy endpoints may use path parameters:

GET /{environment}/forms

Note: The system is migrating to query parameters for consistency.

Required vs Optional

Required:

  • Creating forms: Must specify environment

  • Listing resources: Must specify environment for scoped queries

Optional:

  • Getting a form by ID: Environment optional (validates if provided)

  • Public form access: Environment not required

Environment Validation Flow

Form Creation

  1. User provides environment name

  2. System validates environment name format

  3. System checks if environment exists for user

  4. If environment doesn't exist, returns error with suggestion to create it

  5. Form is created with environment context

Form Access

  1. User requests form with environment parameter

  2. System validates environment format (if provided)

  3. System checks form's environment matches (if provided)

  4. Returns form if access is allowed

API Key Validation

  1. API key is looked up by hash

  2. System extracts user ID and environment from key record

  3. Request is validated against key's environment scope

  4. Access is granted or denied based on environment match

Environment Isolation Benefits

Security

  • Prevents accidental access to wrong environment's data

  • API keys cannot access other environments

  • Clear separation of production and development data

Organization

  • Easy to manage multiple projects

  • Clear separation of concerns

  • Better analytics and reporting per environment

Testing

  • Safe testing in development environment

  • Staging environment for pre-production validation

  • No risk of affecting production data

Troubleshooting

"Environment does not exist" Error

Cause: Trying to create a form in an environment that hasn't been created yet.

Solution: Create the environment first:

POST /users/{userId}/environments
{
  "name": "your-environment-name"
}

"Invalid environment name" Error

Cause: Environment name doesn't match validation rules.

Solution: Use only lowercase letters, numbers, hyphens, and underscores. Length must be 1-50 characters.

Forms Not Showing in Environment

Cause: Forms may be in a different environment, or environment parameter not provided.

Solution:

  • Check that you're querying the correct environment

  • Verify forms exist in that environment

  • Ensure you're authenticated as the form owner

Next Steps

  • API Reference - Learn about API endpoints

  • Authentication - Understand authentication flows

  • Dashboard Guide - Use the dashboard

PreviousDashboardNextWebhooks

Last updated