Manage users and access keys

Create people and agents, choose what each key may do, and replace a lost key or revoke a leaked one.

Create the people and agents who use your server, decide what each one’s key may do, and deal with a key that is lost or leaked. Everyone and everything that reaches your server is a user holding an access key. There is no sign-in, no password and no session: the key is the whole credential.

Prerequisites

A running server. See Manage a server.

List the users

Run:
```
commentware users list
```

That prints ids, names, what each key may do, how many keys each holds and when they were created. It never prints a key.

Create a user

Run one of:

commentware users new alex
commentware users new my-agent --permissions can_collaborate

Leave --permissions off and it asks: an arrow-key list you tick with space and confirm with enter. In a script, where there is no terminal to ask in, it refuses and tells you the flag rather than choosing for you.

Each prints a connection string and, under it, the bare access key. Same secret, same screen, same moment — the string is the form the extension takes, an agent’s sign-in page takes either, and the bare key is what an agent with no browser needs.

It prints once. Keys are stored hashed, so nothing can print one again.

Choose what a key may do

Permission	May
`can_collaborate`	Read, comment, reply and resolve. Not delete anything.
`can_admin`	Delete comments, threads, sites, projects and users.

In new’s picker only can_collaborate is ticked to begin with, so an admin key is something you ask for rather than something everybody silently gets. can_admin deletes anybody’s comment, so correcting somebody else’s mistake is a thing an admin does — and an author correcting their own edits it instead. They describe the key, not the person: a person can hold a key that may not delete, and an agent can hold one that may.

Run permissions with the user’s id. With no list it asks; with one it sets it outright:

commentware users permissions <id>
commentware users permissions <id> can_collaborate
commentware users permissions <id> can_admin,can_collaborate

can_admin on its own is refused. Every request needs can_collaborate first, so a key holding only can_admin would sign in and reach nothing — which is the shape of a key somebody believes works. The extension knows the rule too: a control your key may not use is drawn disabled rather than failing when you press it.

Switch a user off

When somebody leaves, take their permissions away rather than deleting them.

Grant nothing:
```
commentware users permissions <id> ""
```

Their key still signs in and can do nothing at all. They stay in the list, their comments stay, and their name stays on everything they wrote — which deleting them does not keep.

Rename a user

Run edit with the user’s id and the new name:

commentware users edit <id> "Alex Moreno"

Mentions are stored as a reference to the person rather than as the text of their name, so renaming somebody leaves every comment that mentions them working. The displayed name changes everywhere at once.

Give a user another key

Run:
```
commentware users generate <id>
```

That mints one more key for a user who already exists and prints the new connection string. Every key they already hold goes on working — a second browser, a laptop as well as a desktop, and an agent with a credential of its own are all the same command. It tells you how many keys that user now holds, so you can see that you added one rather than replaced one.

Pasting the new connection string into a browser that already holds that server replaces the key on that entry rather than adding a second server — after asking, because the key it replaces is the one that browser was using and nothing brings it back.

Revoke a leaked key

Revoking a key also revokes every agent that user authorized in a browser, and anything using what you revoked stops working immediately. Minting a new key with generate revokes nothing.

List the user’s keys by name:
```
commentware users keys <id>
```
Revoke the one that leaked:
```
commentware users revoke <id> <name>
```
Optional: to revoke every key the user holds at once, run commentware users clear <id> instead.
If the user needs a working key again, run commentware users generate <id>.

Delete a user

Run:
```
commentware users delete <id>
```

This deletes the user and every key they hold. What they wrote stays where it is: their comments and threads are filed under (deleted user), so a conversation is still readable after somebody leaves. The command prints how much it moved. Their name is not recoverable from those rows afterwards — nothing records it — so to stop somebody using the server and keep their name, switch them off instead.

Keep a key where it belongs

Nowhere, for an agent that signs in through a browser — you type the key once into a page on your server; see Work with an AI agent. An agent with no browser takes it in the environment, as COMMENTWARE_ACCESS_KEY.
In the browser for a person, which is what pasting the connection string does. It is stored on that machine, not synced through a Google account.
Never on a command line, where it lands in shell history and in ps.
Never in commentware.config.json, which is a file meant to be committed. There is no field for one.

Check that it worked

commentware users list shows the user, what their key may do, and how many keys they hold. A connection string pasted into the extension connects as that user.

Next steps

Connect to a server: paste a connection string, and hold more than one server in a browser.
Work with an AI agent: point an agent at the server with its own key.