# Provider Integrations API

Base path: `/v1/provider-control`

## Category Modes

### `GET /category-modes`

Lists category operating modes.

Required permission: one of `category_mode.read.all`, `admin.content.read`, `admin.provider.read`, `superadmin.integration.manage`.

### `PATCH /category-modes/:categoryId`

Updates a category operating mode.

Required permission: one of `category_mode.update`, `admin.content.write`, `admin.provider.write`, `superadmin.integration.manage`.

Body:

```json
{
  "operatingMode": "SANDBOX_READY",
  "note": "Provider sandbox is ready for sales demo"
}
```

Creates an `AuditLog` row with resource type `category_mode`.

## Provider Integrations

### `GET /provider-integrations`

Lists provider integration configurations.

Required permission: one of `provider_integration.read.all`, `admin.provider.read`, `superadmin.integration.manage`.

### `POST /provider-integrations`

Creates a provider integration.

Required permission: one of `provider_integration.write`, `admin.provider.write`, `superadmin.integration.manage`.

Body:

```json
{
  "name": "Example Hotel Sandbox",
  "categoryKind": "STAY",
  "environment": "SANDBOX",
  "apiBaseUrl": "https://sandbox.example.com",
  "webhookUrl": "https://sandbox.example.com/webhooks/navi",
  "vaultSecretRef": "doppler/navi/providers/example-hotel",
  "enabled": true,
  "bookingEnabled": true,
  "paymentEnabled": false,
  "refundEnabled": false,
  "commissionEnabled": false,
  "inquiryOnly": true,
  "sandboxReady": true,
  "liveReady": false
}
```

Raw secret values are rejected. Store only vault reference names.

### `PATCH /provider-integrations/:integrationId`

Updates provider integration configuration.

Required permission: one of `provider_integration.write`, `admin.provider.write`, `superadmin.integration.manage`.

### `PATCH /provider-integrations/:integrationId/disable`

Disables an integration and all capability flags. Creates an audit log.

### `POST /provider-integrations/:integrationId/health-check`

Runs a safe mock health check and records the result. This does not call external provider APIs in the foundation phase.

Required permission: one of `provider_integration.health.check`, `provider_integration.write`, `admin.provider.write`, `superadmin.integration.manage`.

## Health and Audit

### `GET /provider-health`

Support-readable health view.

Required permission: one of `provider_integration.health.read`, `provider_integration.read.all`, `audit.read.support`, `admin.provider.read`, `superadmin.integration.manage`.

### `GET /audit-history?limit=100`

Lists provider control tower audit entries.

Required permission: one of `provider_integration.audit.read`, `admin.audit.read`, `audit.read.all`, `superadmin.integration.manage`.