Principals, tokens and scopes

Principals

A principal is an identity on the bus, for example me. It owns tokens and session names. Create one on the bus host:

session-bus principal add me

principal disable me stops every token of that principal at once. There is no command to re-enable or delete a principal.

Tokens

session-bus token mint --principal me --scopes bus:read,bus:write --label laptop [--ttl-days N]

• Tokens are bearer tokens with the prefix sbus_. Only a hash is stored.
• token mint prints the raw token once, on stdout. token list never prints a token or a hash.
• Lifetime: 90 days by default and at most 90 days (--ttl-days must be 1 to 90).
• token revoke <id> revokes one token. token list shows last_used_at for each.
• Use one token per machine, with the machine as the label.

Ownership is keyed by principal, not by token. Rotating a token (mint a new one, revoke the old one) keeps every session name and all mail.

Scopes

Scope	Tools
bus:read	inbox, list_sessions
bus:write	send, broadcast, register, ack, unregister

The map is closed: a tool that is not listed is refused. Any valid token may call initialize, notifications/initialized, ping and tools/list.

A session client needs both scopes, because reading the inbox (bus:read) and acking (bus:write) are both part of normal use. The push shim exits with token lacks scope (403) if its token is missing one.

HTTP responses

Status	When
401	Missing, unknown, revoked or expired token, or a disabled principal. Includes WWW-Authenticate: Bearer realm="session-bus".
403	Valid token, but the method is not allowed, the tool is unknown, or the token lacks the scope.

Both are decided before any tool code runs. See Request path.