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

# Proxy Routing

> Understanding how Bloom routes your API requests

## URL-Based Routing

The Bloom proxy uses a simple pass-through URL format. Simply prepend your proxy domain to any API URL:

```
https://iam.bloomtechnologies.app/[TARGET_API_URL]
```

### Examples

| Target API URL                               | Proxy URL                                                                      |
| -------------------------------------------- | ------------------------------------------------------------------------------ |
| `https://api.openai.com/v1/chat/completions` | `https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions` |
| `https://google.serper.dev/search`           | `https://iam.bloomtechnologies.app/https://google.serper.dev/search`           |
| `https://api.github.com/user`                | `https://iam.bloomtechnologies.app/https://api.github.com/user`                |

The proxy automatically:

* Extracts the base URL (e.g., `https://api.openai.com/v1`)
* Matches it to your configured integrations
* Routes the request with proper authentication

## Request Validation Flow

For each request, the proxy performs these validation steps:

<Steps>
  <Step title="Extract Target URL">
    Extracts the full target URL from the proxy path (e.g., "[https://api.openai.com/v1/chat/completions](https://api.openai.com/v1/chat/completions)")
  </Step>

  <Step title="Match Integration">
    Matches the base URL to a configured integration (e.g., "[https://api.openai.com/v1](https://api.openai.com/v1)" → OpenAI integration)
  </Step>

  <Step title="Validate Agent">
    Validates the agent\_id from your request body or Bearer token
  </Step>

  <Step title="Check Scopes">
    Checks if the agent has scopes for that specific integration
  </Step>

  <Step title="Verify Permissions">
    Verifies the HTTP method and path are allowed by the scope
  </Step>

  <Step title="Route Request">
    Routes to the appropriate integration with proper authentication
  </Step>
</Steps>

## Example Flow

When you make a request to `https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions`:

<AccordionGroup>
  <Accordion title="Step 1: URL Parsing">
    Proxy extracts the target URL: "[https://api.openai.com/v1/chat/completions](https://api.openai.com/v1/chat/completions)"
    Base URL: "[https://api.openai.com/v1](https://api.openai.com/v1)"
    Path: "chat/completions"
  </Accordion>

  <Accordion title="Step 2: Integration Lookup">
    Finds your integration by matching base URL "[https://api.openai.com/v1](https://api.openai.com/v1)"
  </Accordion>

  <Accordion title="Step 3: Scope Validation">
    Checks if your agent has scopes configured for this integration
  </Accordion>

  <Accordion title="Step 4: Permission Check">
    Validates the POST method and "chat/completions" path are allowed
  </Accordion>

  <Accordion title="Step 5: Proxy Request">
    Uses your stored OpenAI API key to make the actual request
  </Accordion>

  <Accordion title="Step 6: Response">
    Returns the response back to your agent
  </Accordion>
</AccordionGroup>

## Common Routing Patterns

```bash theme={null}
# OpenAI Chat Completions
POST https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions

# Serper Web Search
POST https://iam.bloomtechnologies.app/https://google.serper.dev/search

# GitHub User Info
GET https://iam.bloomtechnologies.app/https://api.github.com/user

# Slack Message Posting
POST https://iam.bloomtechnologies.app/https://slack.com/api/chat.postMessage
```

## Benefits of URL-Based Routing

<CardGroup cols={2}>
  <Card title="No Configuration Changes" icon="wrench">
    Use any API without manually configuring service names. Just add your integration's credentials.
  </Card>

  <Card title="Works with Any SDK" icon="code">
    Change the `baseURL` parameter in any SDK to point to the proxy - no other code changes needed.
  </Card>

  <Card title="Self-Documenting" icon="book">
    The URL itself shows which API is being called - no need to memorize service names.
  </Card>

  <Card title="Instant Integration" icon="bolt">
    Add a new API integration and start using it immediately without waiting for new routing rules.
  </Card>
</CardGroup>

<Warning>
  If your agent doesn't have the required scopes, the proxy will return a 403 Forbidden error.
</Warning>