Authentication

Embedding Flatfile requires proper authentication to connect your application to your Flatfile account and access your Spaces.

​

Required Credentials

​

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
  spaceId: "us_sp_your_space_id"
};

​

spaceId

Your Space ID identifies which pre-configured Space to load. Each Space contains your data schema, validation rules, and processing workflows.

Where to find it:

1. Go to Platform Dashboard
2. Open your desired Space
3. Copy the Space ID from the URL: https://platform.flatfile.com/space/us_sp_your_space_id

// Example Space URL
// https://platform.flatfile.com/space/us_sp_abc123def456

const spaceId = "us_sp_abc123def456";

​

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,
  spaceId: process.env.REACT_APP_SPACE_ID
};

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

​

Key Rotation

Regularly rotate your API keys in the Platform Dashboard:

1. Generate a new publishable key
2. Update your application configuration
3. Deploy the changes
4. Revoke the old key

​

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

​

Testing Setup

For development and testing:

// Development configuration
const config = {
  publishableKey: "pk_test_1234567890abcdef", // Test key
  spaceId: "us_sp_test_abc123def456"           // Test Space
};

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

​

Next Steps

Once authenticated:

• Configure your Space schema in the Platform Dashboard
• Set up data validation and transformation rules
• Test the embedding in your application
• Deploy to production with production keys

For advanced authentication scenarios like server-side Space creation, see our API Reference.