# Bloom Identity - AI Agent Security Platform

> This file helps AI assistants understand how to implement Bloom for securing AI agents.

## What is Bloom?

Bloom is an identity and access management (IAM) platform for AI agents. It provides:
- Authentication & authorization for agent API calls
- Audit logging of all agent actions
- Kill switch for immediate agent termination
- Prompt injection detection
- MCP (Model Context Protocol) tool-level permissions

## Quick Integration (Copy-Paste Ready)

### Option 1: Direct API Proxy (Simplest)

Replace your API base URL with Bloom's proxy:

```python
# Before (direct to OpenAI)
response = requests.post(
    "https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {OPENAI_KEY}"},
    json={"model": "gpt-4", "messages": messages}
)

# After (through Bloom)
response = requests.post(
    "https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {BLOOM_API_KEY}"},
    json={"agent_id": AGENT_ID, "model": "gpt-4", "messages": messages}
)
```

### Option 2: MCP Server Security

Wrap any MCP server with Bloom:

```bash
# Install
npm install -g bloom-mcp

# Use (wraps any MCP server)
BLOOM_API_KEY=your_key BLOOM_AGENT_ID=your_agent npx bloom-mcp secure npx @modelcontextprotocol/server-github
```

### Option 3: Python Package

```bash
pip install bloom-openclaw-skill
```

```python
from bloom_proxy import bloom_request

# All requests are now authenticated, authorized, and logged
response = bloom_request("POST", "https://api.openai.com/v1/chat/completions", json={...})
```

## Environment Variables

```bash
BLOOM_API_KEY=bloom_org_xxx          # From dashboard Profile > API Keys
BLOOM_AGENT_ID=agent_xxx             # From dashboard Agents page
BLOOM_PROXY_URL=https://iam.bloomtechnologies.app  # Optional, this is default
```

## Key URLs

- Dashboard: https://platform.bloomtechnologies.app
- Edge Proxy: https://iam.bloomtechnologies.app
- Docs: https://docs.bloomtechnologies.app
- NPM Package: https://www.npmjs.com/package/bloom-mcp
- PyPI Package: https://pypi.org/project/bloom-openclaw-skill/

## Proxy URL Format

Bloom uses pass-through URL format:
```
https://iam.bloomtechnologies.app/{FULL_TARGET_URL}
```

Examples:
- OpenAI: `https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions`
- GitHub: `https://iam.bloomtechnologies.app/https://api.github.com/user`
- Serper: `https://iam.bloomtechnologies.app/https://google.serper.dev/search`

## Security Features

### Kill Switch
```bash
curl -X POST https://iam.bloomtechnologies.app/admin/agents/{agent_id}/kill \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Prompt Injection Detection
Enabled by default. Configure in scope settings:
- Mode: block | alert | log
- Sensitivity: low | medium | high

### Webhooks
Configure at: Dashboard > Activity > Webhooks
Events: injection_blocked, agent_killed, anomaly_detected, permission_denied

## Common Patterns

### Python Agent with Bloom
```python
import os
import requests

BLOOM_API_KEY = os.environ["BLOOM_API_KEY"]
BLOOM_AGENT_ID = os.environ["BLOOM_AGENT_ID"]
BLOOM_PROXY = "https://iam.bloomtechnologies.app"

def call_api(method, url, **kwargs):
    """Route any API call through Bloom."""
    headers = kwargs.pop("headers", {})
    headers["Authorization"] = f"Bearer {BLOOM_API_KEY}"

    json_data = kwargs.pop("json", {})
    json_data["agent_id"] = BLOOM_AGENT_ID

    return requests.request(
        method,
        f"{BLOOM_PROXY}/{url}",
        headers=headers,
        json=json_data,
        **kwargs
    )

# Usage
response = call_api("POST", "https://api.openai.com/v1/chat/completions", json={
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
})
```

### TypeScript/JavaScript Agent
```typescript
const BLOOM_API_KEY = process.env.BLOOM_API_KEY;
const BLOOM_AGENT_ID = process.env.BLOOM_AGENT_ID;
const BLOOM_PROXY = "https://iam.bloomtechnologies.app";

async function callAPI(url: string, options: RequestInit = {}) {
  const headers = {
    ...options.headers,
    "Authorization": `Bearer ${BLOOM_API_KEY}`,
    "Content-Type": "application/json",
  };

  const body = options.body ? JSON.parse(options.body as string) : {};
  body.agent_id = BLOOM_AGENT_ID;

  return fetch(`${BLOOM_PROXY}/${url}`, {
    ...options,
    headers,
    body: JSON.stringify(body),
  });
}
```

## Setup Steps

1. Sign up at https://platform.bloomtechnologies.app
2. Create an Agent (Dashboard > Agents > Add Agent)
3. Get API Key (Dashboard > Profile > API Keys)
4. Add Integration (Dashboard > Integrations) - store your OpenAI/GitHub/etc keys
5. Create Scope (Dashboard > Scopes) - define what the agent can access
6. Assign Scope to Agent
7. Use the proxy URL in your code

## Need Help?

- Docs: https://docs.bloomtechnologies.app
- Email: support@bloomtechnologies.app