Reading your own direct messages with a user token (chat.dm.read)
What it is
An explicit, off-by-default ability on a user token. A request made with such a token can list the direct and group direct conversations its owner is a current member of, read their messages and list their files. Nothing else changes.
Rules
- Granted only when the token is created, by the signed-in owner (step-up). Never by a token, an API key or the operator script. PATCH can only remove it; an existing token is never upgraded (a copied secret stays what it was).
- The token holds exactly
readandchat.dm.read, names its organizations, and ends within 30 days (the UI default is 7). The shape is re-checked on every request, not only at mint. - Honoured only for
GET/HEADon/v1/chat/conversations/:id/messages,/v1/chat/conversations/:id/attachments,/v1/orgs/:orgId/chat/dmsand/v1/orgs/:orgId/dm/:userId, and only for conversations the owner is a current member of. Every other route, method and credential behaves exactly as before. Every refusal is the same 404. - A read writes nothing the other people can see: no delivered or read markers move.
- Messages that exist only in the legacy
direct_messagesarchive are not readable by a token. - Other participants are not told that an agent reads their messages.
- Platform setting
userTokens.dmReaddefaults OFF; missing or unreadable means off. While off no such token can be minted, every holder answers as if it did not hold the ability, and the three MCP tools are not registered. Only a signed-in platform admin changes it. - Audit, on the platform scope (no org column), ids and route only, never message text, file names or the token:
user_token.dm_read: one row per successful (2xx) read the ability allowed, per conversation (or per list call), written before the reply leaves; if that write fails the request fails. A refused (404) or invalid (400) read leaves no use row.user_token.dm_read_denied: one row for each 404 on an admitted request (unknown id, someone else's conversation, not a member, off the token's org list or conversation scope). An org-named route (/v1/orgs/:orgId/...) for an org off the token's list is refused by the token gate before the ability is considered: it gets the gate's usual refusal handling and nodm_readrow.
- A read authorised by a valid AI invocation is not a use of the ability: it keeps the invocation's own behaviour (the delivered marker moves as before) and writes no use row.
MCP tools (registered only for a holder, switch on; annotated read-only)
list_direct_conversations(orgId, limit?, cursor?, unreadOnly?): the preview is message content, untrusted.get_direct_conversation_messages(conversationId, limit?, before?).list_direct_conversation_files(conversationId, q?, offset?): names, sizes and senders; no content URLs.- The existing
get_direct_messagesandfile_listalso work for a holder.
Rollout and rollback
Deploy with the switch off (default). After a staging rehearsal a platform admin turns it on and the owner mints the token. Rollback: switch off, revoke any holder, then revert the code. A revert with rows still holding the ability is tolerated.
Mint a token (owner)
Account > User tokens > New user token > "Read my private messages": organizations only, 7 days by default (30 at most).