Skip to main content
Read Authority
Returns the caller’s resolved standing on a workspace: { reasons, capabilities, permissions, rank }, computed via the authority resolver (fast-path + bounded ancestor climb). This is the endpoint your authorization server reads (via the node SDK) to make its own app-level decisions. reasons is an array of structured entries{ type, viaWorkspaceId? } — distinguishing owner / ancestor-owner / member / reach-holder, so you always know why a user has what they have and which workspace grants it. It is the same object shape a roster entry’s reasons carries. viaWorkspaceId names the granting ancestor and is present on ancestor-owner / reach-holder only (owner / member are grants on the workspace itself). A user reaching in from several ancestors carries one entry per granting ancestor. This read is inherently a self read (or a privileged-key read of a named user), so capabilities / permissions / rank are always returned in full here — unlike the member-standing read, which fences them. (The fence exists to stop a caller reconstructing someone else’s rank; there is nobody else in this payload.)
There is no convenience ?permission= check and no can() middleware. Sublay never consumes your opaque permissions, so a permission check is a one-line .includes() on the returned record:

Path Parameters

string
required
The workspace UUID.

Query Parameters

string
required
Service/master keys only — the user to act as, whose standing is resolved. Required for a key: this route has no unbounded path (there is no such thing as “the app’s standing”), so a key that names nobody is refused with 400 workspace/missing-user-id.A client token omits it — the subject is the token’s own user. The field is not ignored for such a token: sending your own user id is a harmless no-op, but sending anyone else’s is a 403 workspace/unauthorized. See Acting on behalf of a user.

Response

  • reasons — structured standings; viaWorkspaceId is present on ancestor-owner / reach-holder only.
  • capabilities — the fully-resolved set (direct + reach + ownership). view is implied by every other capability — any user with standing on the workspace resolves with view, including a member whose stored capabilities array is empty. A user with no relation at all resolves to an empty set.
  • permissionsper-node (the direct membership on this workspace only; may be empty). Does not cascade.
  • rank — the direct-membership rank, or null for owners / ancestor-owners / reach-only holders.
  • There is no relativeRank on this read. It is an offset from the caller, and here the caller is the subject — so it could only ever be 0, a constant dressed as a coordinate. rank is the position this endpoint reports. relativeRank is meaningful on the roster and member-standing reads, where the subject is somebody else.

Error Responses

A service/master key called this route without naming an actingUserId. The read resolves a user’s standing, so there is nobody to resolve it for.
A plain user token sent an actingUserId naming a different user. Only a service/master key may resolve someone else’s standing.
Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain 400 rather than a 500 from the database.
See also: useFetchWorkspaceAuthority · fetchWorkspaceAuthority (node-sdk) · fetchWorkspaceAuthority (js-sdk)