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 /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 /stats`

The dashboard payload.

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

Room and event counters join it in Phase 3, when there is something to
count.

## 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. Rooms arrive with the roomserver in Phase 3.