This file contains standardized authentication examples that can be referenced across all guides to ensure consistency.

​
Environment Setup

​
Basic .env Configuration

# Required for all Flatfile integrations
FLATFILE_API_KEY=sk_your_secret_key_here
FLATFILE_ENVIRONMENT_ID=us_env_your_environment_id

# Optional: For webhook endpoints
WEBHOOK_URL=https://your-app.com/webhook/flatfile

​
Development vs Production

# Development environment
FLATFILE_API_KEY=sk_dev_your_development_key
FLATFILE_ENVIRONMENT_ID=us_env_dev_your_dev_id

# Production environment  
FLATFILE_API_KEY=sk_prod_your_production_key
FLATFILE_ENVIRONMENT_ID=us_env_prod_your_prod_id

​
API Authentication Examples

​
Using Secret Keys (Server-side)

import api from "@flatfile/api";

// Secret key is automatically used from FLATFILE_API_KEY environment variable
// No additional configuration needed
const workbooks = await api.workbooks.list();

​
Using Personal Access Tokens

​
Creating a PAT via API

curl --location 'api.x.flatfile.com/api/v1/auth' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "your-email@domain.com",
    "password": "your-password"
}'

​
Using PAT in API Requests

// Set PAT in environment
// FLATFILE_API_KEY=your_personal_access_token

import api from "@flatfile/api";
const result = await api.workbooks.list();

​
Legacy Client Credentials Flow

# Get access token using client credentials
curl -X POST https://platform.flatfile.com/api/v1/auth \
-H 'Content-Type: application/json' \
-d '{
  "clientId": "your-client-id", 
  "secret": "your-client-secret"
}'

​
Secure Credential Management

​
Using Flatfile Secrets

export default function flatfileEventListener(listener) {
  listener.on("job:ready", async (event) => {
    // Retrieve secret from Flatfile's secure storage
    const apiKey = await event.secrets("EXTERNAL_API_KEY");
    const webhookUrl = await event.secrets("WEBHOOK_URL");
    
    // Use credentials securely
    const response = await fetch(webhookUrl, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(data)
    });
  });
}

​
Environment-specific Secrets

export default function flatfileEventListener(listener) {
  listener.on("job:ready", async (event) => {
    // Get secret from specific environment/space
    const credential = await event.secrets("API_TOKEN", {
      environmentId: "us_env_specific_env",
      spaceId: "us_spa_specific_space"
    });
  });
}

​
Authentication Best Practices

  1. Never hardcode credentials in your code
  2. Use environment variables for local development
  3. Use Flatfile Secrets for hosted listeners
  4. Rotate tokens regularly for enhanced security
  5. Use separate credentials for development and production
  6. Create separate PATs for different applications or use cases