# 6. External APIs

### 6.1 Microsoft Graph API (Teams Administration)

- **Purpose:** Primary API for all Teams Phone management operations
- **Documentation:** https://learn.microsoft.com/en-us/graph/api/resources/teamsadministration-teamsadminroot
- **Base URL:** `https://graph.microsoft.com/beta`
- **Authentication:** OAuth 2.0 Bearer token (via MSAL)
- **Rate Limits:** Throttling returns HTTP 429 with `Retry-After` header

**Key Endpoints:**

| Method | Endpoint | Purpose |
|--------|----------|---------|
| `GET` | `/admin/teams/userConfigurations` | List user voice configurations |
| `GET` | `/admin/teams/userConfigurations/{id}` | Get single user configuration |
| `GET` | `/admin/teams/telephoneNumberManagement/numberAssignments` | List phone number inventory |
| `GET` | `/admin/teams/telephoneNumberManagement/numberAssignments/{id}` | Get single number details |
| `POST` | `/admin/teams/telephoneNumberManagement/numberAssignments/assignNumber` | Assign number to user (async) |
| `POST` | `/admin/teams/telephoneNumberManagement/numberAssignments/unassignNumber` | Unassign number (async) |
| `POST` | `/admin/teams/telephoneNumberManagement/numberAssignments/updateNumber` | Update number location |
| `GET` | `/admin/teams/telephoneNumberManagement/operations/{id}` | Poll async operation status |
| `POST` | `/admin/teams/policy/userAssignments/assign` | Assign policy to user |
| `GET` | `/users` | Search/resolve users (v1.0) |
| `GET` | `/organization` | Get tenant info (v1.0) |
| `POST` | `/beta/$batch` | Batch multiple requests |

**Integration Notes:**
- All `/admin/teams/*` endpoints are **beta only** - no v1.0 equivalents
- Assign/unassign operations are **async** - return 202 with Location header for polling
- Phone number format varies: digits-only for assign/unassign, E.164 (+prefix) for update
- `locationId` is schema-optional but **backend-enforced for Calling Plan** numbers (E911)
- Batch endpoint must use `beta/$batch` for Teams Admin APIs

### 6.2 Microsoft Entra ID (Authentication)

- **Purpose:** OAuth 2.0 authentication for service principal
- **Documentation:** https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow
- **Base URL:** `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0`
- **Authentication:** Certificate or client secret

### 6.3 Required API Permissions

| Permission | Type | Purpose |
|------------|------|---------|
| `TeamsUserConfiguration.Read.All` | Application | Read user voice configurations |
| `TeamsTelephoneNumber.Read.All` | Application | Read phone number inventory |
| `TeamsTelephoneNumber.ReadWrite.All` | Application | Assign/unassign/update numbers |
| `TeamsPolicyUserAssign.ReadWrite.All` | Application | Assign policies to users |
| `User.Read.All` | Application | Read user profiles, search users |
| `Directory.Read.All` | Application | Read tenant/organization info |

### 6.4 API Limitations (No Graph Endpoint Available)

| Operation | Workaround | Impact |
|-----------|------------|--------|
| List emergency locations | PowerShell `Get-CsOnlineLisLocation` → CSV | CLI reads from CSV cache |
| List policies by type | PowerShell `Get-CsTeamsCallingPolicy` etc. → CSV | CLI reads from CSV cache |
| Reserve/unreserve numbers | None exists | Feature dropped from MVP |

---

