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

# Environment Setup

> Configure your development environment for Bloom

## Required Environment Variables

Bloom requires specific environment variables depending on your integration method:

### For Direct API Integration

<CodeGroup>
  ```bash .env theme={null}
  BLOOM_AGENT_ID=your-agent-id-here
  BLOOM_ORG_API_KEY=your-organization-api-key
  ```

  ```bash Terminal theme={null}
  export BLOOM_AGENT_ID="your-agent-id-here"
  export BLOOM_ORG_API_KEY="your-organization-api-key"
  ```
</CodeGroup>

### For MCP Server Integration

<CodeGroup>
  ```bash .env theme={null}
  BLOOM_ORG_API_KEY=your-organization-api-key
  BLOOM_AGENT_ID=your-agent-id-here
  BLOOM_AUTH=bloom_your-org-key_agent_your-agent-id
  ```

  ```bash Terminal theme={null}
  export BLOOM_ORG_API_KEY="your-organization-api-key"
  export BLOOM_AGENT_ID="your-agent-id-here" 
  export BLOOM_AUTH="bloom_${BLOOM_ORG_API_KEY}_agent_${BLOOM_AGENT_ID}"
  ```
</CodeGroup>

## Finding Your Credentials

<AccordionGroup>
  <Accordion title="Agent ID">
    1. Navigate to the **Agents** tab in your Bloom dashboard
    2. Find your agent in the list
    3. Copy the **Agent ID** from the agent details

    <Info>
      Agent IDs are unique identifiers that look like: `agent_abc123def456`
    </Info>
  </Accordion>

  <Accordion title="Organization API Key">
    1. Go to your **Profile** tab in the Bloom dashboard
    2. Look for the **API Keys** section
    3. Copy your **Organization API Key**

    <Warning>
      Keep your organization API key secure. It provides access to all your organization's resources.
    </Warning>
  </Accordion>

  <Accordion title="BLOOM_AUTH Format">
    For MCP servers, combine your credentials in this format:

    ```
    bloom_{YOUR_ORG_API_KEY}_agent_{YOUR_AGENT_ID}
    ```

    Example:

    ```
    bloom_sk-org-abc123def456_agent_agt-xyz789abc123
    ```
  </Accordion>
</AccordionGroup>

## Development vs Production

### Development Environment

For local development, use a `.env` file:

```bash theme={null}
# .env file
BLOOM_AGENT_ID=agent_dev_12345
BLOOM_ORG_API_KEY=sk-org-dev-abcdef
BLOOM_AUTH=bloom_sk-org-dev-abcdef_agent_agent_dev_12345
```

<Note>
  Consider creating separate agents for development and production environments.
</Note>

### Production Environment

For production, set environment variables through your deployment platform:

<Tabs>
  <Tab title="Docker">
    ```dockerfile theme={null}
    ENV BLOOM_AGENT_ID=agent_prod_67890
    ENV BLOOM_ORG_API_KEY=sk-org-prod-xyz123
    ```
  </Tab>

  <Tab title="Railway">
    ```bash theme={null}
    railway variables set BLOOM_AGENT_ID=agent_prod_67890
    railway variables set BLOOM_ORG_API_KEY=sk-org-prod-xyz123
    ```
  </Tab>

  <Tab title="Vercel">
    Add to your Vercel project settings or `vercel.json`:

    ```json theme={null}
    {
      "env": {
        "BLOOM_AGENT_ID": "agent_prod_67890",
        "BLOOM_ORG_API_KEY": "sk-org-prod-xyz123"
      }
    }
    ```
  </Tab>
</Tabs>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="shield-check">
    * Never commit API keys to version control
    * Use `.env` files for local development
    * Rotate keys regularly in production
  </Card>

  <Card title="Agent Scopes" icon="lock">
    * Follow principle of least privilege
    * Create specific scopes for each use case
    * Regularly audit agent permissions
  </Card>
</CardGroup>

## Validation Script

Use this script to validate your environment setup:

```python theme={null}
import os
import requests

def validate_environment():
    """Validate Bloom environment configuration"""
    
    # Check required variables
    agent_id = os.getenv("BLOOM_AGENT_ID")
    org_key = os.getenv("BLOOM_ORG_API_KEY")
    
    if not agent_id:
        print("❌ BLOOM_AGENT_ID not set")
        return False
        
    if not org_key:
        print("❌ BLOOM_ORG_API_KEY not set")
        return False
        
    print("✅ Environment variables found")
    
    # Test connection
    try:
        response = requests.get(
            "https://iam.bloomtechnologies.app/health",
            headers={"Authorization": f"Bearer {org_key}"},
            timeout=10
        )
        
        if response.status_code == 200:
            print("✅ Connection to Bloom API successful")
            return True
        else:
            print(f"❌ API returned status {response.status_code}")
            return False
            
    except requests.exceptions.RequestException as e:
        print(f"❌ Connection failed: {e}")
        return False

if __name__ == "__main__":
    validate_environment()
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Environment Variables Not Loading">
    **Symptoms**: Getting "None" values for environment variables

    **Solutions**:

    * Ensure `.env` file is in the correct directory
    * Check that you're using `python-dotenv` if needed
    * Verify variable names match exactly (case-sensitive)
  </Accordion>

  <Accordion title="Authentication Errors">
    **Symptoms**: 401 Unauthorized responses

    **Solutions**:

    * Verify your organization API key is correct
    * Check that the agent ID exists and is active
    * Ensure you have the latest API key (not revoked)
  </Accordion>

  <Accordion title="Permission Denied">
    **Symptoms**: 403 Forbidden responses

    **Solutions**:

    * Verify agent has required scopes assigned
    * Check scope permissions include the HTTP method and path
    * Confirm integration is properly configured
  </Accordion>
</AccordionGroup>