Warp/docs/admin-api.md

# Admin API

Everything under `/_warp/admin/v1` is Warp's own, not Matrix. Clients use
the Client-Server API; this is the operator's surface and the backend for
the admin panel (`apps/admin`, PLAN.md section 8.1).

## Authentication

A normal Matrix access token belonging to an account with the admin flag.
The panel logs in the way any client does, so there is no second credential
to manage:

```sh
TOKEN=$(curl -s localhost:8008/_matrix/client/v3/login \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"root"},"password":"..."}' \
  | jq -r .access_token)

curl localhost:8008/_warp/admin/v1/stats -H "Authorization: Bearer $TOKEN"
```

The token must be in the `Authorization` header. Unlike the C-S API, the
`?access_token=` form is not accepted here: an admin token in a URL ends up
in every access log between the browser and the server.

A valid token without the admin flag gets `403 M_FORBIDDEN` rather than a
404. The caller is a legitimate user of this server who is not allowed here,
and pretending the endpoint does not exist only makes the panel harder to
debug.

Make the first admin from the command line:

```sh
./bin/warp create-account --username root --admin
```

## Endpoints

### `GET /federation`, `PUT /federation`

The runtime federation switch of PLAN.md section 3.

```json
{
  "enabled": false,
  "toggleable": true,
  "allowlist": [],
  "denylist": []
}
```

`PUT {"enabled": true}` takes effect on the next request, with no restart,
and answers with the same document. `toggleable` is `false` when
`federation.allow_runtime_toggle` pinned the setting in the config file; a
`PUT` then returns `409` and the panel should grey the switch out rather
than offer something that will bounce.

Editing the allow and deny lists is Phase 9. They are reported now because
the dashboard has to show which servers a running Warp will talk to.

### `GET /federation/destinations`

Delivery health per remote server: the panel's federation status view.
Every server this one has queued something for, or has failed to reach,
with how much it is still owed.

```json
{
  "running": true,
  "destinations": [
    {
      "server_name": "matrix.org",
      "failures": 0,
      "retry_at_ms": 0,
      "last_success_ms": 1760600000000,
      "last_failure_ms": 0,
      "queued_pdus": 0,
      "queued_edus": 0
    }
  ]
}
```

`running` is whether the outbound queue is up — `false` while federation is
switched off. `failures` counts consecutive failed sends; while it is above
zero the server is being backed off, and `retry_at_ms` is when the next
attempt is due. The backoff doubles from ten seconds to six hours.

A server started without a signing key has no federation at all, and both
destination endpoints answer `404`.

### `POST /federation/destinations/{serverName}/reset`

Forget a server's backoff and try it now — for an operator who knows the
server is back and does not want to wait out a six-hour retry. Answers
`{}`.

### `GET /registration`, `PUT /registration`

The same shape, without the lists, for open registration.

### `GET /users`

```
GET /users?search=ali&limit=50&offset=0
```

Ordered by localpart. `search` matches a substring of the localpart or the
display name, case-insensitively. `total` is the number of users matching
the query rather than the number returned, so the panel can page.

```json
{
  "users": [
    {
      "user_id": "@alice:warp.example",
      "display_name": "Alice",
      "admin": false,
      "deactivated": false,
      "created_at_ms": 1760000000000
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

### `POST /users`

```json
{"username": "alice", "password": "...", "display_name": "Alice", "admin": false}
```

`201` with the created user. This is how an operator adds an account to a
server with registration turned off — which is the normal state of a
private Warp — so it ignores the registration switch deliberately: it is
the admin's own action, not a public sign-up. `username` is normalised
(lower-cased) like any other localpart. A taken name is
`400 M_USER_IN_USE`, an unusable one `400 M_INVALID_USERNAME`.

### `GET /rooms`

```
GET /rooms?search=ops&limit=50&offset=0
```

Ordered by joined-member count, biggest first, then by room ID — the second
key is not decoration, because paging an order that is not total can show
the same room on two pages and skip another, and ties in member count are
the common case. `search` matches a substring of the room ID, name, topic or
canonical alias, case-insensitively.

```json
{
  "rooms": [
    {
      "room_id": "!abc:warp.example",
      "room_version": "11",
      "creator": "@alice:warp.example",
      "name": "Operations",
      "topic": "Ops chat",
      "canonical_alias": "#ops:warp.example",
      "join_rule": "public",
      "history_visibility": "shared",
      "guest_access": "forbidden",
      "published": true,
      "joined_members": 12,
      "created_at_ms": 1760000000000
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
```

Everything after `creator` is read from the room's current state and kept in
the room's own row. That is denormalisation on purpose: this listing and the
public room directory both order every room by member count and page the
result, which cannot be done by reading each room's state in turn.

### `GET /rooms/{roomID}`

The list row plus the things only a count can answer.

```json
{
  "room_id": "!abc:warp.example",
  "members": 15,
  "invited_members": 2,
  "joined_members": 12,
  "aliases": ["#ops:warp.example"],
  "forward_extremities": ["$sPfXR..."]
}
```

`members` counts every `m.room.member` event in the current state whatever
the membership, because a room with one member and forty bans is not the
same room as one with a single member. `forward_extremities` is where the
room's DAG ends; there is normally exactly one, and more than one means the
room has forked.

### `DELETE /rooms/{roomID}`

Purges the room: its events, its state, its aliases and its row. There is no
undo and the members are not told — the only way to tell them would have
been to add an event to a room that no longer exists.

It is a `DELETE` on the room rather than a `POST` to an action because that
is what it is, and because the method makes a panel's confirm dialog
mandatory in a way a `POST` does not. Purging a room that is not there is
`404`, not a silent success: an operator who sees an `OK` has to be able to
believe the room was there.

### `POST /rooms/{roomID}/force_leave`

```json
{"user_id": "@alice:warp.example"}
```

Makes a user leave without asking the room's rules whether they may. A user
stuck in a room — one whose power levels are broken, or whose last moderator
has gone — is what this exists for, and in such a room the rules are exactly
what is in the way. It is still an ordinary membership event, signed and
added to the room, so the other members see what happened.

A user who is not in the room gets `403`: there is nothing to leave.

### `GET /stats`

The dashboard payload.

```json
{
  "server_name": "warp.example",
  "version": "0.0.0-dev",
  "database": "sqlite",
  "users": 12,
  "admins": 1,
  "deactivated": 0,
  "devices": 19,
  "rooms": 4,
  "published_rooms": 1,
  "events": 312,
  "federation_enabled": false,
  "registration_enabled": false
}
```

The three room counters are zero on a server that started without a signing
key, which has no roomserver and so no rooms.

## Errors

The same envelope as the Client-Server API — `{"errcode": ..., "error":
...}` — so the panel needs one error path, not two. `409 M_FORBIDDEN` is
specific to this API: the request was well formed and the server's own
configuration is what refuses it.

## Not here yet

Phase 9 completes the admin API: deactivating users, resetting passwords,
revoking devices, granting the admin flag, registration token management,
the federation allow/deny list editor, server notices, media quotas and an
audit log of admin actions.

The room endpoints will grow with it: a room's state and its recent events
for an operator looking at a report, and a way to publish or withdraw a room
from the directory without borrowing a member's token.

A server started without a signing key has no roomserver, and the four room
endpoints then answer `503` rather than failing on the first call.