Admin API Reference

The Admin API runs on port 9443. All endpoints require authentication via session cookie or X-Admin-Key header.

Authentication

# Login and get session cookie
curl -k -c cookies.txt \
  -X POST https://localhost:9443/v1/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'
# → {"token": "session_token"}

# Use session cookie for subsequent requests
curl -k -b cookies.txt https://localhost:9443/v1/admin/users

# Or use X-Admin-Key header
curl -k -H "X-Admin-Key: adminkey_XXXXXXXXXXXXXXXX" \
  https://localhost:9443/v1/admin/users

Users

GET /v1/admin/users

List all users.

Response:

[
  {
    "id": "uuid",
    "username": "alice",
    "email": "alice@example.com",
    "is_admin": false,
    "active": true,
    "created_at": "2026-02-19T10:00:00Z",
    "last_login": "2026-02-19T14:00:00Z"
  }
]

POST /v1/admin/users

Create a user.

Request:

{
  "username": "alice",
  "email": "alice@example.com",
  "password": "initial-password",
  "is_admin": false
}

GET /v1/admin/users/:id

Get user details including group memberships and client count.

PUT /v1/admin/users/:id

Update a user. Updatable fields: email, display_name, active.

DELETE /v1/admin/users/:id

Deactivate a user (soft delete). Invalidates all sessions and preshared keys.

POST /v1/admin/users/:id/reset-password

{"password": "new-password"}

POST /v1/admin/users/:id/preshared-keys

Create a preshared key for Ambassador Client registration.

{"label": "Claude Desktop - Work Laptop"}

Response:

{"key": "amb_pk_XXXX", "label": "Claude Desktop - Work Laptop", "id": "uuid"}

GET /v1/admin/users/:id/preshared-keys

List preshared keys for a user (labels and usage status only — keys are not stored in plaintext).

DELETE /v1/admin/users/:id/preshared-keys/:key_id

Revoke a preshared key.

Groups

GET /v1/admin/groups

List all groups.

POST /v1/admin/groups

Create a group.

{"name": "engineers", "description": "Engineering team"}

GET /v1/admin/groups/:id

Get group details including members and assigned MCPs.

PUT /v1/admin/groups/:id/members

Add or remove members.

{"add": ["user_uuid_1"], "remove": ["user_uuid_2"]}

PUT /v1/admin/groups/:id/mcps

Assign or remove MCPs from a group.

{"add": ["mcp_uuid_github"], "remove": ["mcp_uuid_old"]}

MCP Catalog

GET /v1/admin/mcps

List all MCPs in the catalog (all states).

POST /v1/admin/mcps

Add an MCP to the catalog.

{
  "name": "github",
  "display_name": "GitHub",
  "description": "GitHub API — search code, manage PRs, issues",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env_schema": [
    {
      "name": "GITHUB_PERSONAL_ACCESS_TOKEN",
      "description": "GitHub Personal Access Token with repo scope",
      "required": true,
      "secret": true,
      "scope": "user"
    }
  ],
  "isolation": "per_user",
  "tags": ["code", "version-control"]
}

POST /v1/admin/mcps/:id/validate

Test MCP connectivity — spawns the MCP and fetches the tool list.

Response:

{
  "status": "ok",
  "tools": ["github.search_code", "github.list_issues", "github.create_pr"]
}

POST /v1/admin/mcps/:id/publish

Publish MCP to the marketplace. Users in assigned groups can now subscribe.

POST /v1/admin/mcps/:id/archive

Remove MCP from marketplace. Existing subscribers lose access.

PUT /v1/admin/mcps/:id/tools/:tool_name/kill

Tool-level kill switch.

{"active": true, "reason": "Investigating unexpected behavior"}

PUT /v1/admin/mcps/:id/kill

MCP-level kill switch — disables all tools.

{"active": true, "reason": "Security incident"}

Audit Logs

GET /v1/admin/audit

Query the audit log (paginated).

Query parameters:

Response:

{
  "total": 1234,
  "limit": 50,
  "offset": 0,
  "events": [
    {
      "id": "evt_uuid",
      "event_type": "tool_invocation",
      "timestamp": "2026-02-19T14:32:01.123Z",
      "correlation_id": "corr_uuid",
      "user_username": "alice",
      "client_label": "VS Code - Work Laptop",
      "mcp_name": "github",
      "tool_name": "github.search_code",
      "result_status": "success",
      "duration_ms": 234
    }
  ]
}

Health

GET /health

No authentication required.

{"status": "ok", "version": "0.8.0-beta.1", "admin": true}

Error responses

All errors return JSON with error and optional details:

{"error": "Unauthorized", "details": "Invalid session"}
{"error": "Not found", "details": "User not found"}
{"error": "Validation error", "details": "username is required"}