Admin Panel

The admin panel is the owner/admin control surface for an org. It lives under /admin in the web dashboard and exposes a set of REST endpoints under /api/admin/*. Every write is permission-gated through the roles system — see Roles & Permissions.

What admins do

• Invite and remove members
• Change member roles (including create custom roles)
• Manage teams and team membership
• Create API-only agents (non-human clients that post to MCP)
• Edit org name / slug / metadata
• Read usage metrics against plan limits

Endpoints

All require Authorization: Bearer <token> and run in the caller's active org.

Members

Method & Path	Permission	Purpose
GET /api/admin/users	users.invite	List members (user_id, email, name, role, role_id, joined_at)
POST /api/admin/users/{user_id}/role	users.change_role	Change a member's role
POST /api/admin/users/{user_id}/deactivate	users.remove	Remove a member from the org

Organization

Method & Path	Permission	Purpose
GET /api/admin/org	org.manage	Fetch org details
PATCH /api/admin/org	org.manage	Update name, slug, or metadata

Agents (API-only clients)

Method & Path	Permission	Purpose
POST /api/admin/agents	agents.manage	Create a named agent; enforces the agents plan limit

The response includes the agent's client_id; pair it with an API key (see Authentication) to let it call the MCP endpoint.

Usage

Method & Path	Permission	Purpose
GET /api/admin/usage	org.manage	Returns current plan + usage counters vs. limits

Useful for in-app dashboards that warn before a limit is hit. See Billing for the plan catalog and Roles & Permissions for permission strings.

The last-Owner guard

An org must always have at least one Owner. Both change_role and deactivate refuse to demote or remove the only Owner and return 409 Conflict with {"error":"cannot demote the last Owner"}.

# Example: promote someone to Owner before demoting yourself
curl -X POST https://api.klaxon.sh/api/admin/users/$NEW_OWNER_ID/role \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"role":"owner"}'

Only Owners can grant Owner

Any admin with users.change_role can edit regular roles, but the Owner role is gated separately — only callers whose own role is owner can assign owner. This matches the invitation flow in Invitations.

Example: full invite loop

TOKEN="…owner session token…"

# 1. Create an email invite
curl -X POST https://api.klaxon.sh/api/admin/invitations \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"email":"new@example.com","role":"member"}'

# 2. List open invitations
curl https://api.klaxon.sh/api/admin/invitations \
  -H "Authorization: Bearer $TOKEN"

# 3. The invitee accepts at /invite/<code> in the web UI,
#    or via POST /auth/invitations/accept with their own token.

# 4. Check usage vs. plan
curl https://api.klaxon.sh/api/admin/usage \
  -H "Authorization: Bearer $TOKEN"

Audit trail

Every admin mutation writes an entry to the audit_log table with the actor, action, and a JSON details blob. Members with audit.read can list it via the audit endpoints — see the REST API reference.

Related guides

• Roles & Permissions — permission strings + custom roles
• Invitations — inviting via email or shareable link
• Teams — grouping members within an org
• Billing — plans and limits surfaced by /api/admin/usage