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

# Authentication

> How to authenticate with the Bloom API

## Authentication Methods

Bloom uses **Bearer token authentication** with your organization API key.

### Headers

Include your organization API key in the Authorization header:

```http theme={null}
Authorization: Bearer your-org-api-key
```

### Request Body

All proxy requests must include your agent ID:

```json theme={null}
{
  "agent_id": "your-agent-id",
  // ... other parameters
}
```

## Authentication Flow

<Steps>
  <Step title="API Key Validation">
    Bloom validates your organization API key from the Authorization header
  </Step>

  <Step title="Agent Verification">
    Verifies the agent\_id exists and belongs to your organization
  </Step>

  <Step title="Scope Authorization">
    Checks if the agent has permission to access the requested service and endpoint
  </Step>

  <Step title="Proxy Request">
    Routes the authenticated request to the target service using stored credentials
  </Step>
</Steps>

## API Key Types

<CardGroup cols={2}>
  <Card title="Organization API Key" icon="building">
    * Used in the Authorization header
    * Identifies your organization
    * Required for all API calls
    * Found in Profile → API Keys
  </Card>

  <Card title="Agent ID" icon="robot">
    * Included in request body
    * Identifies the specific agent
    * Determines scope permissions
    * Found in Agents → Agent Details
  </Card>
</CardGroup>

## Example Implementation

<Tabs>
  <Tab title="Python Requests">
    ```python theme={null}
    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
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"}]
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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' }]
        })
      }
    );
    ```
  </Tab>
</Tabs>

## MCP Authentication

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

```bash theme={null}
# 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

<Warning>
  **Never expose API keys in client-side code or public repositories.**
</Warning>

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

```python theme={null}
# 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

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired",
    "type": "authentication_error"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "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:

```python theme={null}
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()
```