> ## Documentation Index
> Fetch the complete documentation index at: https://help.bodharouteplanner.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes & Security

> How Bodha Route Planner protects your fleet data — scopes, encryption, tenant isolation, rate limiting, and audit logging.

# Scopes & Security

Your fleet data is sensitive. The MCP server is designed with security at every layer — from how keys are stored, to what each key can access, to how every request is logged.

***

## Scopes

Scopes control which tools an API key can access. When you create a key, you choose which scopes to grant. Tools outside the key's scopes are invisible to the AI assistant — it doesn't even know they exist.

### Available scopes

| Scope | Tools unlocked | What the AI can see |
| - | - | - |
| `routes:read` | `list_routes`, `get_route`, `get_route_summary` | Route names, dates, statuses, driver assignments, stop sequences, ETAs, distances |
| `stops:read` | `list_stops`, `get_stop`, `search_stops` | Stop addresses, recipient names, delivery status, failure reasons, POD metadata |
| `drivers:read` | `list_drivers`, `get_driver_performance` | Driver names, vehicle types, assignment status, performance metrics |
| `orders:read` | `list_orders`, `get_order` | Order references, addresses, status, source system, custom fields |
| `analytics:read` | `get_analytics`, `compare_periods` | Aggregate metrics — completion rates, distances, stop counts, trends |
| `depots:read` | `list_depots`, `get_depot` | Depot names, addresses, shift hours, break schedules |

### Scope presets

| Preset | What it includes | When to use |
| - | - | - |
| **Read-only** *(recommended)* | All 6 read scopes | Full visibility for conversational queries. Best for most users. |
| **Custom** | Pick individual scopes | When you want to limit access — for example, a key that can only see analytics but not individual stop addresses. |

### Principle of least privilege

If someone only needs to ask analytics questions ("How did we do this week?"), create a key with just `analytics:read`. The AI won't have access to individual stops, orders, or driver details — it can only see aggregate numbers.

***

## Key security

### How keys are stored

| Aspect | Detail |
| - | - |
| **Plaintext** | Shown **once** at creation. Never stored by Bodha Route Planner after that. |
| **Storage** | Only a **bcrypt hash** of the key is stored in the database. |
| **Lookup** | When a request arrives, the key prefix (first 8 characters) is used to find the hash, then bcrypt verifies the full key. |

This means:

* Even if the database were compromised, attackers would not have usable API keys
* Bodha Route Planner support staff cannot retrieve your key — only you have it
* If you lose a key, you must create a new one

### Key format

```
bdk_live_a3f8c9d2e1b4f7a6...
```

| Part | Meaning |
| - | - |
| `bdk` | Bodha Developer Key |
| `live` | Production environment |
| `a3f8c9d2...` | Unique random token |

***

## Tenant isolation

Every MCP request is scoped to the tenant (organization) that owns the API key. This is enforced at the query level — not just application logic.

| Guarantee | How it's enforced |
| - | - |
| **No cross-tenant data** | Every database query includes the tenant ID from the authenticated key. It is impossible to query another organization's routes, stops, drivers, or orders — even if you know their IDs. |
| **No tenant ID guessing** | Tenant IDs are MongoDB ObjectIDs — 24-character hex strings. They cannot be enumerated or guessed. |
| **Middleware enforcement** | The tenant filter is applied in authentication middleware, before any controller code runs. Individual tools cannot bypass it. |

***

## PII protection

The MCP server masks or excludes personally identifiable information:

| Field | Handling |
| - | - |
| **Customer phone** | Masked (e.g. `***-***-4567`) |
| **Customer email** | Masked (e.g. `j***@example.com`) |
| **Driver phone** | Masked |
| **Addresses** | Returned in full (required for delivery context) |
| **Driver names** | Returned in full (required for assignment context) |
| **Recipient names** | Returned in full (required for delivery context) |

***

## Rate limiting

| Limit | Value |
| - | - |
| **Per-key read rate** | 60 requests per minute |
| **Hard ceiling** | 10 requests per second (API Gateway) |
| **Burst** | Short bursts above the per-minute rate are allowed up to the hard ceiling |

Normal conversational use (one person asking questions in an AI assistant) will never hit these limits. They exist to prevent runaway scripts or misconfigured automations.

When a rate limit is hit, the MCP server returns a standard error with a `Retry-After` header. AI assistants handle this gracefully — they wait and retry.

***

## Audit logging

Every MCP tool call is logged. The audit log captures:

| Field | Example |
| - | - |
| **Timestamp** | `2026-10-29T14:32:17Z` |
| **Key prefix** | `bdk_live_a3f8...` |
| **Tool called** | `list_routes` |
| **Parameters** | `{ date: "2026-10-29", status: "in_progress" }` |
| **Duration** | `142ms` |
| **Result** | `success` (or error code) |
| **IP address** | Requesting IP |

### Viewing the audit log

Go to **Settings → API Keys → Activity** in your Bodha Route Planner dashboard. You can:

* Filter by key, tool, or date range
* See which questions triggered which tool calls
* Identify unusual access patterns
* Verify that a revoked key is no longer being used

### Retention

Audit logs are retained for **90 days** on Pro plans and **1 year** on Enterprise plans.

***

## Key management best practices

> **One key per person or application**
>
> Create separate keys for each person or system that connects to the MCP server. This way, if one key is compromised, you can revoke it without disrupting others. The audit log also becomes more useful when each key maps to a known user.

> **Use the narrowest scopes that work**
>
> If someone only needs analytics, give them `analytics:read`. If someone needs routes and stops but not orders, create a key with just `routes:read` and `stops:read`. Narrow scopes limit the blast radius of a compromised key.

> **Rotate keys periodically**
>
> While not strictly required, rotating keys every 90 days is good practice. Create a new key, update your AI assistant's config, and revoke the old key.

> **Revoke immediately if compromised**
>
> If a key is accidentally shared, committed to a public repo, or otherwise exposed:
>
> 1. Go to **Settings → API Keys** immediately
> 2. Click **Revoke** on the compromised key
> 3. Create a new key
> 4. Update your AI assistant's config
>
> The revoked key stops working on the very next request — no propagation delay.

> **Don't commit keys to version control**
>
> If you use the MCP server in a team development environment, store the key in environment variables or a secrets manager — not in committed config files. Use `.gitignore` to exclude MCP config files.

***

## Enterprise security features

Enterprise plans include additional security capabilities:

| Feature | Description |
| - | - |
| **Unlimited keys** | No limit on the number of API keys per organization |
| **All scopes** | Access to all current and future scopes, including write scopes when released |
| **Extended audit retention** | 1 year of audit log retention (vs 90 days on Pro) |
| **SSO enforcement** | API key creation restricted to SSO-authenticated admins |
| **IP allowlisting** | Restrict API key usage to specific IP ranges |

Contact [sales@bodharouteplanner.com](mailto:sales@bodharouteplanner.com) for Enterprise pricing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.