---
category: reference
tags:
  - phase-2
  - management-api
last_updated: 2026-03-13
---

# P2-4: Management API

**Branch:** `feat/P2-4-management-api` (from `phase-2`)
**Commit:** `1e80a07`
**Tests:** 30 passing

## What was built

WSGI middleware (`ManagementMiddleware`) that intercepts `/admin/*` requests before they reach the otterwiki Flask app. All routes require platform JWT authentication.

## Files

| File | Purpose |
|------|---------|
| `app/management/routes.py` | WSGI middleware with 8 API endpoints |
| `app/management/wiki_init.py` | Git repo init + bootstrap template writer |
| `app/management/token.py` | MCP bearer token generation (secrets + bcrypt) |
| `app/models/user.py` | Added `get_by_email()` scan method |
| `tests/test_management_api.py` | 30 unit tests (moto + tmpdir) |

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/admin/wikis` | Create wiki (repo init, bootstrap, ACL, token) |
| GET | `/admin/wikis` | List user's wikis |
| GET | `/admin/wikis/{slug}` | Wiki details + MCP endpoint |
| DELETE | `/admin/wikis/{slug}` | Delete wiki (repo, DB records, ACLs) |
| POST | `/admin/wikis/{slug}/token` | Regenerate MCP bearer token |
| POST | `/admin/wikis/{slug}/acl` | Grant access (body: `{email, role}`) |
| DELETE | `/admin/wikis/{slug}/acl/{grantee_id}` | Revoke access |
| GET | `/admin/wikis/{slug}/acl` | List ACL entries |

## Design decisions

- **WSGI middleware pattern** — wraps the otterwiki app; if `PATH_INFO` starts with `/admin`, handle it; otherwise pass through.
- **Plain JSON responses** — `json.dumps()` with `Content-Type: application/json`, not Flask.
- **Ownership enforcement** — delete, token regen, and ACL grant/revoke require `role=owner` in ACL table.
- **Tier limits** — `wiki_count >= wiki_limit` check on create; count incremented/decremented atomically.
- **Token shown once** — plaintext returned only on create and regenerate; only bcrypt hash stored.
- **Repo cleanup on create failure** — if `init_wiki_repo` fails, DB records are rolled back.
- **wiki_id format** — `{owner_id}:{wiki_slug}` (consistent with ACL model).
- **MCP endpoint** — returns `/{slug}/mcp` for now (no username mapping yet).

## Integration notes

To wire into the Lambda handler, wrap the otterwiki WSGI app:

```python
from app.management.routes import ManagementMiddleware
wrapped = ManagementMiddleware(
    otterwiki_wsgi_app,
    auth_middleware=auth_middleware,
    user_model=users,
    wiki_model=wikis,
    acl_model=acls,
)
handler = make_lambda_handler(wrapped)
```

## Not included (future work)

- Lambda handler wiring (will be done when all Phase 2 components integrate)
- Username-to-subdomain mapping for MCP endpoint URLs
- Rate limiting on wiki creation