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 read and chat.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/HEAD on /v1/chat/conversations/:id/messages, /v1/chat/conversations/:id/attachments, /v1/orgs/:orgId/chat/dms and /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_messages archive are not readable by a token.
  • Other participants are not told that an agent reads their messages.
  • Platform setting userTokens.dmRead defaults 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 no dm_read row.
  • 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_messages and file_list also 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).

We use essential cookies to keep you signed in. See our Privacy Policy for details.