> ## Documentation Index
> Fetch the complete documentation index at: https://flatfile.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Examples

> Standardized authentication setup patterns for Flatfile

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

## Environment Setup

### Basic .env Configuration

```bash theme={null}
# 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

```bash theme={null}
# 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)

```javascript theme={null}
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

```bash theme={null}
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

```javascript theme={null}
// 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

```bash theme={null}
# 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

```javascript theme={null}
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

```javascript theme={null}
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