> ## Documentation Index
> Fetch the complete documentation index at: https://help.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand Workspaces Access and Sessions

> Understand human sessions, API keys, guest links, raw links, and the access errors Workspaces returns.

For app, API, and live collaboration requests tied to a workspace, access may
come from ownership, organization membership, a guest link, or workspace
visibility. Changing one source does not cancel the others. Raw file URLs
follow separate rules.

## How Workspaces decides access

Workspaces checks grants in this order:

1. Workspace owner.
2. Member of the workspace's organization.
3. View or edit guest link.
4. Workspace visibility.

Changing a workspace to **Only you** does not revoke active guest links. Revoke
those links too. A view guest link also cannot limit access that an open
workspace already grants.

## Human sessions

Hosted Workspaces uses WorkOS for human sign-in. Self-hosted Workspaces uses
OIDC or Cloudflare Access. Workspaces does not provide a development sign-in
bypass.

Hosted and OIDC sessions use secure cookies limited to the app host. Browser
scripts cannot read them. Signing out clears the Workspaces session and CSRF
cookies.

A WorkOS session can end when WorkOS expires or revokes it and Workspaces cannot
refresh it. The self-hosted deployment sets the OIDC session length.

With Cloudflare Access, Workspaces checks the assertion's issuer and app
audience before accepting the user.

For browser changes made with a human session, Workspaces also checks a CSRF
token. API-key and anonymous requests do not use that browser token.

## API keys

An API key acts with its owner's access. Workspaces shows the full key once and
stores only its SHA-256 hash. New API, MCP, and Git requests fail after the
owner revokes the key.

API-key access normally reflects hosted organization membership changes within
60 seconds. If WorkOS returns an error, Workspaces may use the prior membership
for up to 10 minutes.

When an admin removes a member, Workspaces gives that member's organization
workspaces to the removing admin. The member's keys then lose owner access to
those workspaces and access from the removed membership. The keys remain active
for any other access the owner still has.

Only the key owner can list or revoke it. Blocking sign-in does not revoke an
existing key, and administrators cannot revoke another user's key. See
[Create and revoke Workspaces API keys](/workspaces/agents/api-keys).

## Guest links and raw links

A guest link contains a secret `?share=` token. Anyone who has the whole URL can
use its view or edit grant. Guest links do not expire on their own. The owner
can revoke one from **Workspace settings** > **Share links**.

Revocation removes that token's grant from new requests and asks active
collaboration sessions that rely on it to disconnect. A recipient may still
have access through workspace visibility, organization membership, or
ownership. Revocation cannot recall content that a recipient already
downloaded.

A frozen raw URL ending in `@<version>` is a different URL credential. Revoking
an app guest link or changing workspace visibility does not revoke that frozen
raw URL while the workspace still exists. Share frozen raw URLs only with
people who should keep access to that exact file version.

## Access errors

| Result | Meaning                                                                                                                                                                                                                            |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Workspaces cannot grant access from the request as sent. The requester may need to sign in or use a valid API key or guest link. Workspaces treats an invalid guest token as absent; the remaining access rules decide the result. |
| `403`  | The requester can view the resource but cannot make the requested change. A missing or mismatched browser CSRF token or an organization billing rule can also cause `403`.                                                         |
| `404`  | The resource does not exist, the signed-in requester cannot view it, or an owner-only management route hides it from a non-owner.                                                                                                  |

*Reviewed July 22, 2026. Maintained by the Plannotator documentation team.*