Skip to main content
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)

​
CSS Customization

You can customize the embedded Flatfile iframe and its container elements using CSS variables and class selectors. This allows you to control colors, sizing, borders, and other visual aspects of the iframe wrapper to match your application’s design.

​
CSS Variables

Define these CSS variables in your application’s stylesheet to control the appearance of Flatfile’s embedded components: 
:root {
  --ff-primary-color: #4c48ef;
  --ff-secondary-color: #616a7d;
  --ff-text-color: #090b2b;
  --ff-dialog-border-radius: 4px;
  --ff-border-radius: 5px;
  --ff-bg-fade: rgba(0, 0, 0, 0.2);
}

​
Container Elements

Target these elements to customize the iframe container: 
/* The default mount element */
#flatfile_iFrameContainer {
  /* Your custom styles */
}

/* A div around the iframe that contains Flatfile */
.flatfile_iframe-wrapper {
  /* Your custom styles */
}

/* The actual iframe that contains Flatfile */
#flatfile_iframe {
  /* Your custom styles */
}
When displayAsModal is set to true, customize the modal appearance: 
/* Container styles when displayed as modal */
.flatfile_displayAsModal {
  padding: 50px !important;
  width: calc(100% - 100px) !important;
  height: calc(100vh - 100px) !important;
}

.flatfile_iframe-wrapper.flatfile_displayAsModal {
  background: var(--ff-bg-fade);
}

/* Close button styles */
.flatfile_displayAsModal .flatfile-close-button {
  /* Your custom styles */
}

.flatfile_displayAsModal .flatfile-close-button svg {
  fill: var(--ff-secondary-color);
}

/* Iframe border radius when displayed as modal */
.flatfile_displayAsModal #flatfile_iframe {
  border-radius: var(--ff-border-radius);
}

​
Exit Confirmation Dialog

Customize the confirmation dialog that appears when closing Flatfile: 
/* Modal backdrop */
.flatfile_outer-shell {
  background-color: var(--ff-bg-fade);
  border-radius: var(--ff-border-radius);
}

/* Inner container */
.flatfile_inner-shell {
  /* Your custom styles */
}

/* Dialog box */
.flatfile_modal {
  border-radius: var(--ff-dialog-border-radius);
}

/* Button container */
.flatfile_button-group {
  /* Your custom styles */
}

/* All buttons */
.flatfile_button {
  /* Your custom styles */
}

/* Primary "Yes, cancel" button */
.flatfile_primary {
  border: 1px solid var(--ff-primary-color);
  background-color: var(--ff-primary-color);
  color: #fff;
}

/* Secondary "No, stay" button */
.flatfile_secondary {
  color: var(--ff-secondary-color);
}

/* Dialog heading */
.flatfile_modal-heading {
  color: var(--ff-text-color);
}

/* Dialog description text */
.flatfile_modal-text {
  color: var(--ff-secondary-color);
}

​
Error Component

Customize the error display component: 
/* Error container */
.ff_error_container {
  /* Your custom styles */
}

/* Error heading */
.ff_error_heading {
  /* Your custom styles */
}

/* Error description */
.ff_error_text {
  /* Your custom styles */
}

​
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.