Authentication - Bloom Documentation

Authentication Methods

Bloom uses Bearer token authentication with your organization API key.

Headers

Include your organization API key in the Authorization header:

Authorization: Bearer your-org-api-key

Request Body

All proxy requests must include your agent ID:

{
  "agent_id": "your-agent-id",
  // ... other parameters
}

Authentication Flow

API Key Validation

Bloom validates your organization API key from the Authorization header

Agent Verification

Verifies the agent_id exists and belongs to your organization

Scope Authorization

Checks if the agent has permission to access the requested service and endpoint

Proxy Request

Routes the authenticated request to the target service using stored credentials

API Key Types

Organization API Key

Used in the Authorization header
Identifies your organization
Required for all API calls
Found in Profile → API Keys

Agent ID

Included in request body
Identifies the specific agent
Determines scope permissions
Found in Agents → Agent Details

Example Implementation

Python Requests
cURL
JavaScript

import requests
import os

# Setup
headers = {
    "Authorization": f"Bearer {os.getenv('BLOOM_ORG_API_KEY')}",
    "Content-Type": "application/json"
}

payload = {
    "agent_id": os.getenv("BLOOM_AGENT_ID"),
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
}

# Make authenticated request
response = requests.post(
    "https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions",
    headers=headers,
    json=payload
)

curl -X POST https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer your-org-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-id",
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

const response = await fetch(
  'https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BLOOM_ORG_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agent_id: process.env.BLOOM_AGENT_ID,
      model: 'gpt-3.5-turbo',
      messages: [{ role: 'user', content: 'Hello' }]
    })
  }
);

MCP Authentication

For MCP servers using bloom-mcp-wrapper, authentication is handled automatically via the BLOOM_AUTH environment variable:

# Format: bloom_{ORG_API_KEY}_agent_{AGENT_ID}
export BLOOM_AUTH="bloom_sk-org-abc123_agent_agt-xyz789"

The wrapper extracts the credentials and handles proxy authentication transparently.

Security Considerations

Never expose API keys in client-side code or public repositories.

Best Practices

Environment Variables: Store credentials in environment variables
Key Rotation: Regularly rotate your organization API keys
Scope Limitation: Create agents with minimal required scopes
Monitor Usage: Review API usage logs regularly
Secure Storage: Use secure secret management in production

Development Security

# Good: Environment variables
import os
api_key = os.getenv("BLOOM_ORG_API_KEY")

# Bad: Hardcoded keys
api_key = "sk-org-abc123def456"  # Never do this!

Error Responses

Authentication errors return structured error responses:

401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired",
    "type": "authentication_error"
  }
}

403 Forbidden

{
  "error": {
    "code": "insufficient_scope",
    "message": "Agent does not have permission to access this endpoint",
    "type": "authorization_error",
    "required_scope": "openai:chat:completions"
  }
}

Testing Authentication

Verify your setup with this simple test:

import requests
import os

def test_auth():
    response = requests.get(
        "https://iam.bloomtechnologies.app/health",
        headers={
            "Authorization": f"Bearer {os.getenv('BLOOM_ORG_API_KEY')}"
        }
    )

    if response.status_code == 200:
        print("✅ Authentication successful")
        return True
    else:
        print(f"❌ Authentication failed: {response.status_code}")
        print(response.json())
        return False

test_auth()

​Authentication Methods

​Headers

​Request Body

​Authentication Flow

​API Key Types

Organization API Key

Agent ID

​Example Implementation

​MCP Authentication

​Security Considerations

​Best Practices

​Development Security

​Error Responses

​401 Unauthorized

​403 Forbidden

​Testing Authentication

Authentication Methods

Headers

Request Body

Authentication Flow

API Key Types

Example Implementation

MCP Authentication

Security Considerations

Best Practices

Development Security

Error Responses

401 Unauthorized

403 Forbidden

Testing Authentication