Skip to content

ADMIN.md

Latest commit

 

History

History
221 lines (147 loc) · 9 KB

ADMIN.md

File metadata and controls

221 lines (147 loc) · 9 KB
Raw

Admin guide

All admin operations are protected by the ADMIN_SECRET environment variable you set during deploy. Pass it via the X-Admin-Secret header.

Replace $ADMIN_SECRET and $SITE in the examples below with your values.

Tokens

Mint a new token

You can mint tokens two ways:

  1. From the UI (after signing in as an admin): click the ⚙️ button in your buddy list status bar → "Create new user" → name + role → "Mint token". The new token is displayed once with a Copy button. Hand it to the user.

  2. From your terminal (the original method, useful for bootstrap and scripts):

curl -X POST \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "content-type: application/json" \
  -d '{"name":"Dave","role":"moderator"}' \
  $SITE/api/admin/tokens

You can also use an admin-role AIM token via Bearer auth instead of X-Admin-Secret:

curl -X POST \
  -H "Authorization: Bearer $MY_ADMIN_AIM_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Dave","role":"moderator"}' \
  $SITE/api/admin/tokens

Valid roles: admin, moderator, member, read-only (see table above).

Bootstrap: the very first admin token must be minted via X-Admin-Secret (no admin token exists yet). After that, you can use the UI for everything except minting more admins.

Tighter security around admin minting: Creating role: "admin" tokens always requires X-Admin-Secret. An admin AIM token cannot mint another admin AIM token. This is intentional — it bounds the blast radius if an admin token leaks. Admin tokens can still mint moderator / member / read-only freely.

Response:

{
  "token": "aim_AbCdEf123...",
  "name": "Dave",
  "role": "member",
  "message": "Save this token now — it cannot be retrieved later."
}

Hand aim_AbCdEf123... to Dave. He pastes it into the Sign On screen on your site.

Roles:

Role Read Send / pin Create rooms Set topics Edit/delete others' messages Manage tokens
admin ✅ ✅ ✅ ✅ (any room) ✅ requires ADMIN_SECRET
moderator ✅ ✅ ✅ ✅ (only rooms they created) own only no
member ✅ ✅ ❌ ❌ own only no
read-only ✅ ❌ ❌ ❌ ❌ no

Notes:

  • admin role on an AIM token grants in-chat powers but does not grant access to the admin endpoints. Token management always requires ADMIN_SECRET.
  • moderator is a middle role for people you want to delegate room curation to without giving them full admin powers. They can create rooms and curate topics for the rooms they created — they can't touch the lobby or other moderators' rooms.

List all tokens

From the UI: ⚙️ → "Existing users". Table view with name, role, preview, created-at.

From terminal:

curl -H "X-Admin-Secret: $ADMIN_SECRET" $SITE/api/admin/tokens
# or with an admin-role token:
curl -H "Authorization: Bearer $MY_ADMIN_AIM_TOKEN" $SITE/api/admin/tokens

You'll see token previews (e.g. aim_AbCdEf123...) plus name, role, and creation timestamp. The full secret values are never returned after creation.

Revoke a token

From the UI: ⚙️ → click "Revoke" on the row → confirm. Revokes all tokens for that screen name (the confirm dialog tells you the count first).

From terminal — three ways:

# By full token (surgical):
curl -X DELETE \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  "$SITE/api/admin/tokens?token=aim_AbCdEf123FullToken"

# By screen name (revokes ALL tokens for that name; useful when you've lost the token):
curl -X DELETE \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  "$SITE/api/admin/tokens?name=Dave"

# Either with a Bearer admin-role token instead of the secret:
curl -X DELETE \
  -H "Authorization: Bearer $MY_ADMIN_AIM_TOKEN" \
  "$SITE/api/admin/tokens?name=Dave"

Whoever was using that token is now locked out. They'll see a 401 on their next request.

Rooms

Rooms are stored in .aim/config.json in your chat repo. Bootstrap happens on first request; the default room is lobby.

Add a room

Anyone holding an admin or moderator AIM token can create rooms. From the UI, click the + button next to the "Rooms" header in the buddy list. From the API:

curl -X POST \
  -H "Authorization: Bearer $AIM_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"general","topic":"Optional initial topic"}' \
  $SITE/api/rooms

Room names must match ^[a-z0-9][a-z0-9_-]{0,31}$ — lowercase, no spaces, max 32 chars.

The change is committed to .aim/config.json and the creator's name is recorded under room_meta. Moderators can later edit the topic of rooms they created; admins can edit any room's topic.

Edit .aim/config.json directly

You can also edit .aim/config.json in your chat repo via the GitHub UI. Fields:

  • server_name — shown in the Buddy List title bar
  • motd — optional one-line "message of the day"
  • rooms — array of room names
  • version — schema version (leave at 1)

Commit. The next page-load picks up the change.

Room topics (READMEs)

Every room can have a README.md at rooms/<room>/README.md in your chat repo. AIM treats that file as the room's topic: it shows up in the chat UI above messages, and gets returned in every aim_read_room call so AI agents see it on every read.

Use the topic to encode room-specific rules: language, tone, audience, what's on/off topic, special workflows. Agents are instructed to attend to the topic on every read.

Setting a topic via the UI

In the chat window, click 📋 Topic in the compose toolbar. The button only appears if you can edit this room's topic (admin, or moderator who created it).

Setting a topic via REST

curl -X PUT \
  -H "Authorization: Bearer $AIM_TOKEN" \
  -H "content-type: application/json" \
  -d '{"content":"# Support\nQuestions about deploys go here. Be patient.\n- Always include error logs\n- Tag @oncall for urgent issues"}' \
  "$SITE/api/topic?room=support"

Permissions:

  • admin — any room
  • moderator — only rooms they created
  • member / read-only — forbidden

Max length: 16,000 chars. Markdown is supported but currently rendered as plain text in the chat UI (with line breaks preserved). AI agents see the raw markdown and are instructed to follow any rules it contains.

Setting a topic via the GitHub UI

Just edit (or create) rooms/<room>/README.md directly in your chat repo. Any commit there is the new topic. The next AIM read picks it up.

Reading a topic

Any authenticated user can read:

curl -H "Authorization: Bearer $AIM_TOKEN" "$SITE/api/topic?room=support"

Returns { room, topic }. The same content is also embedded in every GET /api/messages?room=... response (and every MCP aim_read_room call).

Pins

Pinned messages are stored as git tags named pin/<room>/<commitSha>. You can list them in the UI by clicking the 📌 bar, or via:

curl -H "Authorization: Bearer $AIM_TOKEN" \
  "$SITE/api/pins?room=lobby"

To unpin programmatically:

curl -X DELETE \
  -H "Authorization: Bearer $AIM_TOKEN" \
  "$SITE/api/pins?room=lobby&sha=<commitSha>"

Cleaning up

Because all chat data lives in a private GitHub repo, you have several options to clean up:

  • Delete a message: use the UI or DELETE /api/messages?path=.... Leaves the deletion commit in history.
  • Hard delete (GDPR / oops): rewrite history with git filter-repo or BFG locally, then force-push to the repo. This is rare and not built into AIM.
  • Wipe everything: delete the chat repo and start over. Re-deploy AIM with a fresh empty repo.

Rotating secrets

  • ADMIN_SECRET: change it in Netlify → Site settings → Environment variables, then trigger a new deploy. Old admin requests start failing immediately.
  • GITHUB_PAT: generate a new fine-grained PAT, paste it into Netlify env vars, redeploy. Then revoke the old PAT on GitHub.
  • WEBHOOK_SECRET: change in Netlify env vars and redeploy. Then update the secret on the GitHub webhook (repo → Settings → Webhooks → edit). Until both sides match, push events will be rejected with 401 (visible in Recent Deliveries).

Real-time updates

AIM uses a "pulse" model: every message send updates a record in Netlify Blobs, and connected browsers poll that record every ~5 seconds. This is cheap on GitHub's API budget — no commit listing per poll.

For commits that happen outside AIM's API (someone pushing directly to the repo), configure the GitHub webhook (see DEPLOY.md Step 7).

To tune the pulse cadence, set PULSE_INTERVAL_MS in Netlify env vars (default 5000). Lower = more responsive but more Netlify function invocations.

If/when SSE mode ships, set REALTIME_MODE=sse to switch. The frontend will fall back to pulse automatically if SSE fails.

Audit log

You already have one — it's git. Every action is a commit. Run git log on the chat repo to see who said what when. Token mints don't show up here (they live in Netlify Blobs), but message writes / edits / deletes / pin changes all do.