This reference covers all configuration options for embedded Flatfile, from basic setup to advanced customization.

​
Authentication & Security

​
publishableKey

Your publishable key authenticates your application with Flatfile. This key is safe to include in client-side code.

Where to find it:

  1. Log into Platform Dashboard
  2. Navigate to Developer Settings → API Keys
  3. Copy your Publishable Key (starts with pk_)
// Example usage
const config = {
  publishableKey: "pk_1234567890abcdef", // Your actual key
};

​
Security Best Practices

​
Environment Variables

Store your publishable key in environment variables rather than hardcoding:

// ✅ Good - using environment variable
const config = {
  publishableKey: process.env.REACT_APP_FLATFILE_KEY,
};

// ❌ Avoid - hardcoded keys
const config = {
  publishableKey: "pk_1234567890abcdef",
};

​
Common Configuration Options

These options are shared across all SDK implementations:

​
Authentication

OptionTypeRequiredDescription
publishableKeystring✅Your publishable key from Platform Dashboard

​
User Identity

OptionTypeRequiredDescription
userInfoobject❌User metadata for space creation
userInfo.userIdstring❌Unique user identifier
userInfo.namestring❌User’s display name - this is displayed in the dashboard as the associated user
userInfo.companyIdstring❌Company identifier
userInfo.companyNamestring❌Company display name
externalActorIdstring❌Unique identifier for embedded users

​
Space Setup

OptionTypeRequiredDescription
namestring✅Name of the space
environmentIdstring✅Environment identifier
spaceIdstring❌ID of existing space to reuse
workbookobject❌Workbook configuration for dynamic spaces
listenerListener❌Event listener for responding to events

​
Look & Feel

OptionTypeRequiredDescription
themeConfigobject❌Theme values for Space, sidebar and data table
spaceBodyobject❌Space options for creating new Space; used with Angular and Vue SDKs
sidebarConfigobject❌Sidebar UI configuration
sidebarConfig.defaultPageobject❌Landing page configuration
sidebarConfig.showDataChecklistboolean❌Toggle data config, defaults to false
sidebarConfig.showSidebarboolean❌Show/hide sidebar
documentobject❌Document content for space
document.titlestring❌Document title
document.bodystring❌Document body content (markdown)

​
Basic Behavior

OptionTypeRequiredDescription
closeSpaceobject❌Options for closing iframe
closeSpace.operationstring❌Operation type
closeSpace.onClosefunction❌Callback when space closes
displayAsModalboolean❌Display as modal or inline (default: true)

​
Advanced Configuration Options

These options provide specialized functionality for custom implementations:

​
Space Reuse

OptionTypeRequiredDescription
idstring✅Space ID
accessTokenstring✅Access token for space (obtained server-side)

Important: To reuse an existing space, you must retrieve the spaceId and access token server-side using your secret key, then pass the accessToken to the client. See Server Setup Guide for details.

​
UI Overrides

OptionTypeRequiredDescription
mountElementstring❌Element to mount Flatfile (default: “flatfile_iFrameContainer”)
loadingReactElement❌Custom loading component
exitTitlestring❌Exit dialog title (default: “Close Window”)
exitTextstring❌Exit dialog text (default: “See below”)
exitPrimaryButtonTextstring❌Primary button text (default: “Yes, exit”)
exitSecondaryButtonTextstring❌Secondary button text (default: “No, stay”)
errorTitlestring❌Error dialog title (default: “Something went wrong”)

​
On-Premises Configuration

OptionTypeRequiredDescription
apiUrlstring❌API endpoint (default: “https://platform.flatfile.com/api”)
spaceUrlstring❌Spaces API URL (default: “https://platform.flatfile.com/s”)

URLs for other regions can be found here.

​
Configuration Examples

​
Basic Space Creation

const config = {
  publishableKey: "pk_1234567890abcdef",
  name: "Customer Data Import",
  environmentId: "us_env_abc123",
  workbook: {
    // your workbook configuration
  },
  userInfo: {
    userId: "user_123",
    name: "John Doe",
  },
};

​
Space Reuse with Access Token

// Client-side: Use space with access token from server
const config = {
  space: {
    id: "us_sp_abc123def456",
    accessToken: "at_1234567890abcdef", // Retrieved server-side
  },
};

​
Advanced UI Customization

const config = {
  publishableKey: "pk_1234567890abcdef",
  mountElement: "custom-flatfile-container",
  exitTitle: "Are you sure you want to leave?",
  exitText: "Your progress will be saved.",
  themeConfig: {
    // custom theme configuration
  },
};

​
Troubleshooting

​
Invalid publishableKey

Error: "Invalid publishable key"

Solution:

  • Verify key starts with pk_
  • Check for typos or extra spaces
  • Ensure key is from correct environment

​
Space Not Found

Error: "Space not found" or 403 Forbidden

Solution:

  • Verify Space ID format (us_sp_ prefix)
  • Ensure Space exists and is active
  • Check Space permissions in dashboard

​
CORS Issues

Error: "CORS policy blocked"

Solution:

  • Add your domain to allowed origins in Platform Dashboard
  • Ensure you’re using publishable key (not secret key)
  • Check browser network tab for specific CORS errors

​
Access Token Issues

Error: "Invalid access token" when using space reuse

Solution:

  • Ensure access token is retrieved server-side using secret key
  • Check that token hasn’t expired
  • Verify space ID matches the token

​
Testing Setup

For development and testing:

// Development configuration
const config = {
  publishableKey: "pk_test_1234567890abcdef", // publishable key from development environment
};

Create separate test Spaces for development to avoid affecting production data.

​
Next Steps

Once configured:

  • Deploy your event listener to Flatfile
  • Configure data validation and transformation rules
  • Test the embedding in your application
  • Deploy to production with production keys

For server-side space reuse patterns, see our Server Setup Guide.