Authentication Methods Bloom uses Bearer token authentication with your organization API key.
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 variablesKey Rotation : Regularly rotate your organization API keysScope Limitation : Create agents with minimal required scopesMonitor Usage : Review API usage logs regularlySecure 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()
