Cloud entitlements

The Cloud entitlement endpoint shows the committed product access projection for the signed-in user in one Space. Use it to inspect the active plan, enabled modules, capacity and revision in customer automation.

The response is an unsigned inspection projection. It is not an offline licence and must not be treated as proof that a local binary may enable a paid feature.

Authentication and scope

Use either a Cloud cabinet session or an API token with the exact billing:read scope. Always send an explicit Space UUID. A token limited to workspace:read cannot read entitlements.

curl -sS \
  -H "Authorization: Bearer $MOCKARTY_CLOUD_TOKEN" \
  "$MOCKARTY_CLOUD_URL/api/v1/cloud/entitlements?space_id=$MOCKARTY_SPACE_ID"

Successful responses include snapshot, revision and digest. Cloud also returns an ETag; responses use private, no-store caching.

CLI inspection

mockarty-cli cloud-entitlements get --space "$MOCKARTY_SPACE_ID"

The CLI wraps the result with source: "projection" and authoritative: false so it cannot be confused with the signed authority used by Desktop. The Cloud Spaces SDK clients manage collaboration separately; this inspection endpoint is not a signed Desktop grant.

Signed Desktop authority

A connected Desktop obtains a separate signer-verified signed-current envelope through its internal device channel. That request requires the exact short-lived access credential and matching Space, installation and profile. A cabinet session or API token cannot call it as Desktop authority.

Desktop credentials are rotated and stored in the operating-system credential vault. The signed envelope, not the cabinet projection and not the fact that a profile is connected, controls paid local capability. When Cloud is unavailable, Desktop can use only the validity and grace window already covered by the last verified envelope; an outage never extends that window.

For retail Free, Pro and Team accounts, Desktop separates the named person’s local grant from the selected Space’s shared grant. An active Team Seat gives its holder portable Pro local features. Team shared capabilities apply inside that person’s own Team Spaces. A Team member can use portable Pro work in another person’s Pro Space if invited with a suitable role; that other Space’s limits apply. A Pro person in a Free host Space keeps paid local tools, but does not unlock paid shared work there. A Free person in a Pro host Space cannot use the host’s paid tools as their own. Paid shared actions require both the actor’s grant and the host Space’s grant, as well as the Space role. Team A’s grant cannot be used in Team B, and a removed or suspended Seat stops granting Team access.

Response outcomes

200 — the committed projection is current.
400 — space_id is missing or is not a UUID.
403 — the caller is not an active member, or the API token lacks billing:read.
409 — a committed commercial change is waiting for its next entitlement revision. No stale snapshot is returned. Retry after the interval in Retry-After.
503 — the entitlement authority or its commercial signer is temporarily unavailable.

The embedded MCP server does not expose this operation yet. MCP access requires authenticated Cloud-principal delegation so the server can enforce the same user and Space boundary; an administrator identity or a raw pasted token is not a substitute.

See Cloud Spaces and collaboration for Space membership and role management.