Environment Setup

Required Environment Variables

Bloom requires specific environment variables depending on your integration method:

For Direct API Integration

BLOOM_AGENT_ID=your-agent-id-here
BLOOM_ORG_API_KEY=your-organization-api-key

export BLOOM_AGENT_ID="your-agent-id-here"
export BLOOM_ORG_API_KEY="your-organization-api-key"

For MCP Server Integration

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

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}"

Finding Your Credentials

Agent ID

Navigate to the Agents tab in your Bloom dashboard
Find your agent in the list
Copy the Agent ID from the agent details

Agent IDs are unique identifiers that look like: agent_abc123def456

Organization API Key

Go to your Profile tab in the Bloom dashboard
Look for the API Keys section
Copy your Organization API Key

Keep your organization API key secure. It provides access to all your organization’s resources.

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

Development vs Production

Development Environment

For local development, use a .env file:

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

Consider creating separate agents for development and production environments.

Production Environment

For production, set environment variables through your deployment platform:

Docker
Railway
Vercel

ENV BLOOM_AGENT_ID=agent_prod_67890
ENV BLOOM_ORG_API_KEY=sk-org-prod-xyz123

railway variables set BLOOM_AGENT_ID=agent_prod_67890
railway variables set BLOOM_ORG_API_KEY=sk-org-prod-xyz123

Add to your Vercel project settings or vercel.json:

{
  "env": {
    "BLOOM_AGENT_ID": "agent_prod_67890",
    "BLOOM_ORG_API_KEY": "sk-org-prod-xyz123"
  }
}

Security Best Practices

Environment Variables

Never commit API keys to version control
Use .env files for local development
Rotate keys regularly in production

Agent Scopes

Follow principle of least privilege
Create specific scopes for each use case
Regularly audit agent permissions

Validation Script

Use this script to validate your environment setup:

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

Environment Variables Not Loading

Symptoms: Getting “None” values for environment variablesSolutions:

Ensure .env file is in the correct directory
Check that you’re using python-dotenv if needed
Verify variable names match exactly (case-sensitive)

Authentication Errors

Symptoms: 401 Unauthorized responsesSolutions:

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)

Permission Denied

Symptoms: 403 Forbidden responsesSolutions:

Verify agent has required scopes assigned
Check scope permissions include the HTTP method and path
Confirm integration is properly configured

Get Started

Guides

Integration Methods

Security

Required Environment Variables

For Direct API Integration

For MCP Server Integration

Finding Your Credentials

Development vs Production

Development Environment

Production Environment

Security Best Practices

Environment Variables

Agent Scopes

Validation Script

Troubleshooting

​Required Environment Variables

​For Direct API Integration

​For MCP Server Integration

​Finding Your Credentials

​Development vs Production

​Development Environment

​Production Environment

​Security Best Practices

Environment Variables

Agent Scopes

​Validation Script

​Troubleshooting

Required Environment Variables

For Direct API Integration

For MCP Server Integration

Finding Your Credentials

Development vs Production

Development Environment

Production Environment

Security Best Practices

Validation Script

Troubleshooting