proxmox/docs/04-configuration/SITE_MANAGER_API_SETUP.md

# Site Manager API Setup Guide

**Last Updated:** 2025-01-20  
**Document Version:** 1.0
**Status:** Active Documentation

---

## Overview

This guide covers setting up API integration for Ubiquiti UniFi Site Manager Cloud API using the Site Manager API library and MCP server.

The Site Manager API is a **cloud-based API** that allows you to manage multiple UniFi deployments at scale through the UniFi Site Manager portal (unifi.ui.com).

## Prerequisites

- UniFi account with access to Site Manager (unifi.ui.com)
- Node.js 18+ and pnpm installed
- API key from UniFi Site Manager

## Key Differences from Local APIs

| Feature | Site Manager API (Cloud) | Local APIs |
|---------|-------------------------|------------|
| Location | Cloud (api.ui.com) | Local (UDM Pro IP) |
| Scope | Multiple deployments | Single controller |
| Auth | API key (cloud) | API key (local) or username/password |
| Use Case | Multi-site management | Single site automation |

## Step 1: Get API Key

1. **Sign in to UniFi Site Manager**
   - Go to [unifi.ui.com](https://unifi.ui.com)
   - Sign in with your UniFi account

2. **Navigate to API Section**
   - Click on "API" in the left navigation bar
   - Or go directly to the API settings page

3. **Create API Key**
   - Click "Create API Key"
   - Copy the generated key immediately
   - **Important**: The key is shown only once - store it securely!

4. **Store the API Key**
   - The key will be used in environment variables
   - Keep it secure - it provides access to your UniFi deployments

## Step 2: Configure Environment Variables

Create or update `~/.env` file:

```bash
# Site Manager API Configuration
SITE_MANAGER_API_KEY=your-api-key-here
SITE_MANAGER_BASE_URL=https://api.ui.com/v1  # Optional, this is the default
```

**Security Notes:**
- Never commit the `.env` file to version control
- Store the API key securely
- Rotate the key periodically if needed

## Step 3: Install and Build

```bash
# Install dependencies
pnpm install

# Build packages
pnpm site-manager:build
```

## Step 4: Test the Integration

### Using CLI Tool

```bash
# List hosts
pnpm site-manager:cli hosts

# List sites
pnpm site-manager:cli sites

# List devices
pnpm site-manager:cli devices

# Get ISP metrics
pnpm site-manager:cli isp-metrics

# List SD-WAN configurations
pnpm site-manager:cli sd-wan-configs
```

### Using Node.js

```typescript
import { SiteManagerClient, SitesService } from 'site-manager-api';

const client = new SiteManagerClient({
  apiKey: process.env.SITE_MANAGER_API_KEY!,
});

const sitesService = new SitesService(client);
const sites = await sitesService.listSites();
console.log(sites);
```

## Step 5: MCP Server Setup (Optional)

### For Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "site-manager": {
      "command": "node",
      "args": [
        "/path/to/proxmox/mcp-site-manager/dist/index.js"
      ]
    }
  }
}
```

The server will automatically load environment variables from `~/.env`.

### Start MCP Server

```bash
# Start server
pnpm site-manager:start

# Development mode (with auto-reload)
pnpm site-manager:dev
```

## Available Endpoints

The Site Manager API provides access to:

- **Hosts**: List all hosts across deployments
- **Sites**: List all sites
- **Devices**: List all devices across deployments
- **ISP Metrics**: Get ISP performance metrics
- **SD-WAN Configs**: List and query SD-WAN configurations

## API Status

- **Current Status**: Read-only
- **Write Operations**: Planned for future versions
- **Rate Limits**:
  - Early Access (EA): 100 requests per minute
  - v1 stable: 10,000 requests per minute

## Rate Limiting

If you exceed rate limits, the API will return a `429 Too Many Requests` status with a `Retry-After` header. The library handles this automatically by throwing a `SiteManagerRateLimitError` with the retry time.

## Troubleshooting

### Authentication Errors

- Verify `SITE_MANAGER_API_KEY` is correct
- Check that the API key hasn't expired or been revoked
- Ensure the API key was created from unifi.ui.com (not local controller)
- Test the API key with curl:
  ```bash
  curl -X GET 'https://api.ui.com/v1/hosts' \
    -H 'X-API-KEY: YOUR_API_KEY' \
    -H 'Accept: application/json'
  ```

### Connection Errors

- Verify internet connectivity
- Check that api.ui.com is accessible
- Ensure firewall allows outbound HTTPS connections
- Verify DNS resolution for api.ui.com

### Rate Limit Errors

- Check your API version (EA vs v1)
- Implement exponential backoff
- Reduce request frequency
- Use the `retryAfter` value from the error to wait before retrying

## Documentation References

- [Official Site Manager API Documentation](https://developer.ui.com/site-manager-api/gettingstarted)
- [Site Manager API Library README](../../site-manager-api/README.md)
- [MCP Server README](../../mcp-site-manager/README.md)

## Next Steps

- Explore available endpoints in the API documentation
- Integrate with your automation workflows
- Set up monitoring for rate limits
- Consider caching responses for frequently accessed data