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

# OAuth Account Management

> Best practices for managing OAuth connections across accounts

## One API Key Per OAuth Account

OAuth connections are scoped to your **API key** (not organization). This enables multiple OAuth accounts within the same org—just use different API keys.

```
API Key → api_key_id → connection → OAuth tokens
```

**Example**: To use Gmail MCP with two different email addresses:

1. Create two API keys in your dashboard
2. Use API key A with Gmail account A
3. Use API key B with Gmail account B
4. Each key sees only its own OAuth connections

## Why This Design?

Connections are keyed by `(api_key_id, deployment_id, name)`. Different API keys within the same org get separate OAuth connections. This provides:

* **Multi-account support**: Easy to use multiple OAuth identities
* **Isolation**: Each API key's connections are independent
* **Simplicity**: No account switching needed—just use different keys

## Switching Accounts

To "switch" OAuth accounts, simply use a different API key. If you need to re-authenticate the same key:

1. Revoke access in the provider's settings (e.g., [Google Account](https://myaccount.google.com/permissions))
2. Next MCP call triggers fresh OAuth flow

<Warning>
  Deleting an API key will delete all OAuth connections associated with it (CASCADE DELETE). Create
  new connections with your new key.
</Warning>

## Data Model Reference

| Entity            | Key                                 | Notes                            |
| ----------------- | ----------------------------------- | -------------------------------- |
| API Key           | `id` (uuid)                         | Belongs to an organization       |
| Connection        | `(api_key_id, deployment_id, name)` | Unique per key + server + name   |
| OAuth Credentials | `connection_id` (FK)                | Encrypted tokens, auto-refreshed |