Publish this session to the organisation's home
Copies this session, already redacted, to the organisation’s home, where the team reads it. The developer’s home is where the work happens and the organisation’s is where it is read, so this is a one-way copy addressed by a share id and never a synchronisation of two equal stores.
Read GET /v1/sessions/{sessionId}/share/preview first and show a person the document: it is the last moment before the bytes leave their machine.
THE MODE IS WHERE THE PUBLISH STOPS, and there are two. once copies the entries that exist and is finished. sync leaves the share subscribed, so entries said afterwards ride the same queue — one road with two stopping rules rather than a streaming mechanism beside a batch one.
THE SHARE ID IS DRAWN AND CARRIES NOTHING. It is unrelated to the session id by construction, so a share link that leaks says nothing about the machine it came from.
Publishing the same session twice creates a second share with its own id; a revoked share is never resumed, and re-sharing after a revocation is always a new one.
AN UNREACHABLE ORGANISATION’S HOME IS 503 NRY-0029 AND IS NOT A FAILURE. The share is recorded and every entry is owed on disk before anything is sent, so an unreachable organisation’s home means the work is queued: a later drain carries it, complete and in order, and the message names the share. Nothing about local work is blocked by it.
Authorizations
Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.
Path Parameters
The session's id.
Body
One person asking for one session to be published to the organisation's home. THERE IS NO ORGANISATION FIELD AND NO OWNER FIELD, and their absence is the design rather than an omission. One organisation is one home, so which organisation this is arrives with the token and the home refuses a token for any other before a handler runs; and the person publishing is the verified actor, so an owner a caller could name would be an owner a caller could get wrong.
Where this publish stops. once copies the entries that exist and is finished. sync leaves the share subscribed, so entries said afterwards ride the same queue to the same place.
There is no third value, because the difference between these two is a stopping rule and not a mechanism.
once, sync When this share stops. Absent takes the host's configured window, which is the point rather than a convenience: a share nobody thought about still stops, so there is no way to ask for one that never does. An instant already past is refused rather than accepted, because a person told their session is shared, whose copy is deleted a moment later, has been told something false.
The colleagues this share is for, each named by the subject their sign-in reports. ABSENT OR EMPTY IS THE WHOLE ORGANISATION, and that is the default rather than a special case: a person publishing to their team names nobody, and narrowing is what somebody has to ask for. Naming colleagues is also what makes a session its owner marked PRIVATE readable — by them, bounded to the entries the share has actually delivered. A value no sign-in could ever report — a blank, an address with a space in it, a pasted line — is refused by name, since a share written for a mistyped colleague is a share readable by nobody with a 201 in front of it. Whether a well-formed subject belongs to this organisation is not checked here: that is a directory call this home cannot make, and a grant it cannot exercise anyway.
Response
The share this publish created.
One session published to the organisation's home, as this home records it.
The share's id, which addresses it everywhere outside this home — a URL, the organisation's home, whatever a colleague pastes into a chat. Drawn from a cryptographic source and unrelated to sessionId by construction, so it discloses nothing about the session or the machine it came from.
26^[A-Z2-7]{26}$The session in THIS home that was published. It is provenance: at the organisation's home the same share is addressed by shareId and that session does not exist there.
Where this publish stops.
once, sync How far it has got. pending is a share whose first entry has not reached the organisation's home — which is what a 503 NRY-0029 leaves behind. active is a share the organisation's home holds: complete for once, still following for sync. revoked is terminal.
Whether a share has EXPIRED is deliberately not a state here: that is a comparison against a clock, and a stored copy of it would go stale on its own.
pending, active, revoked When the person asked for it.
When this share stops: the instant the publish named, or the host's configured window from when it was asked for. It is the host's answer and never a client's calculation.
A share whose expiry has passed is closed whether or not the sweep that deletes it has run yet — which is why state carries no expired value. Once the sweep HAS run, the copied entries are deleted and the state reads revoked, because that is what happened to it.
Who this share is for, as the host now holds it: the subjects named on it, or ABSENT for the whole organisation. It is the host's record and never a client's copy of what it asked for.