# Contrato API — Governance (Spec 040)

**Base URL:** `https://desk.ligbox.com.br/api/v1/governance`  
**Auth:** `Authorization: Bearer {jwt}`  
**Permissão:** `can_manage_users` (role `super_admin`)

---

## GET /modules

Lista módulos de access capabilities, níveis e grupos.

**Response 200:**

```json
{
  "modules": ["desk", "openpanel", "billing", "api", "security", "ai_agents"],
  "levels": ["none", "read", "partial", "full"],
  "groups": ["Comercial", "Externo", "Negócio", "Ops", "Plataforma"]
}
```

---

## GET /users/stats

**Response 200:**

```json
{
  "total": 8,
  "active": 6,
  "frozen": 2,
  "super_admin": 1
}
```

---

## GET /users/{username}/meta

**Response 200:**

```json
{
  "meta": {
    "username": "user@empresa.com",
    "internal_id": "LB-A1B2C3D4",
    "main_group": "Ops",
    "secondary_groups": [],
    "account_status": "active",
    "module_permissions": { "desk": "partial" },
    "invite_token": null
  }
}
```

---

## POST /users/wizard

**Request body:**

```json
{
  "display_name": "Ana Silva",
  "email": "ana@empresa.com",
  "phone": "+351900000000",
  "password": "senha-inicial",
  "account_status": "active",
  "force_password_change": true,
  "mfa_required": false,
  "notifications_enabled": true,
  "api_access": false,
  "role": "technician",
  "main_group": "Ops",
  "secondary_groups": ["Comercial"],
  "module_permissions": {
    "desk": "partial",
    "openpanel": "read",
    "billing": "none",
    "api": "none",
    "security": "none",
    "ai_agents": "none"
  },
  "notes": "Observações opcionais",
  "send_invite_email": true,
  "activate_account": true
}
```

**Response 201:**

```json
{
  "user": { "username": "ana@empresa.com", "role": "technician", "active": true },
  "meta": { "internal_id": "LB-…" },
  "audit": { "action": "user.created", "summary": "Created by Roger" },
  "internal_id": "LB-…",
  "invite_link": "https://desk.ligbox.com.br/register.html?invite=…",
  "message": "Utilizador criado"
}
```

---

## POST /users/{username}/freeze

Toggle activo/congelado + audit.

**Response 200:** `{ "user": {…}, "audit": {…} }`

---

## POST /users/{username}/reset-password

**Response 200:** `{ "ok": true, "generated_password": "…", "audit": {…} }`

---

## GET /audit

**Query:** `target_type`, `target_id`, `limit` (max 200)

**Response 200:** `{ "events": [ { "action", "summary", "actor_username", "created_at" } ] }`