> ## Documentation Index > Fetch the complete documentation index at: https://docs.sidecars.ai/llms.txt > Use this file to discover all available pages before exploring further. # Authentication and access > What access a connected agent receives: the OAuth scopes, the one workspace a token names, the document roles that gate each call, and how every action is attributed to you. ## Scopes | Scope | Granted on first connect | What it unlocks | | ---------------------------- | ------------------------ | --------------------------------------------------------------------------------- | | `openid`, `profile`, `email` | Yes | Identify the signed-in person | | `user:org:read` | Yes | Show the workspace picker on consent and stamp `org_id` on the token | | `knowledge:read` | Yes | Search and ask your workspace's connected knowledge | | `documents:read` | Step-up | List and read shared documents, pages, versions and comments; export files | | `documents:write` | Step-up | Create and write into shared documents and pages as you; add and resolve comments | | `pods:read` | Step-up | See the pods you belong to | | `conversations:read` | Step-up | Read conversations in your pods | | `conversations:write` | Step-up | Post messages as you | **Step-up** means the scope is not requested on the initial connect. When a tool that needs it is called, the server answers `403` with `error="insufficient_scope"` and `scope=""` in the `WWW-Authenticate` header. MCP hosts treat that as a signal to re-run consent for the one extra scope and retry. `conversations:read` unlocks [`list_conversations`](/reference/conversations) (rooms and pods by name; never a room's messages). `pods:read` and `conversations:write` are part of the advertised catalogue, but **no tool currently exposed on the MCP server requires them**. They are reserved for tools that are not yet shipped. Granting them today has no effect. Which scope each tool needs is listed on its reference page and summarised on [Available tools](/tools). ## Workspace access A token names exactly one workspace. Every tool acts in that workspace and only that workspace; a document or conversation id from another workspace behaves exactly like an id that does not exist. The active workspace is chosen on the consent screen. A token without one, or for a workspace the person is not a member of, gets a tool error naming the fix; see [Workspace errors](/troubleshooting#workspace-errors). To act in a different workspace, re-authenticate the connection and choose the other workspace on consent. ## Document roles Documents, pages and tables ("artifacts") each have a **scope** and a set of roles. The token's person holds one effective role per artifact, resolved by the same rules the web app uses. | Scope | Who can reach it | | ------ | ------------------------------------------------------------------------- | | `user` | Private to its owner, plus anyone the owner has explicitly shared it with | | `pod` | Members of one pod | | `org` | Every member of the workspace | | Role | Read | Comment | Edit | | ----------- | ---- | ------- | ---- | | `viewer` | ✓ | | | | `commenter` | ✓ | ✓ | | | `editor` | ✓ | ✓ | ✓ | | `owner` | ✓ | ✓ | ✓ | `list_documents` and `read_comments` report your role on each artifact so an agent can decide what to attempt before it tries. ### Refusals Refusals use the app's own wording and never reveal whether an artifact exists: an artifact you cannot see is `Artifact not found`, a viewer's write is `This document is read-only for you`, a commenter's edit is `You can comment on this document but not edit it`. The full table is in [Permission refusals](/troubleshooting#permission-refusals). ### What an agent can never do There is deliberately **no share, grant, move, link, restore or delete tool**. An agent connected over MCP can never widen who sees an artifact, and cannot restore an earlier version; those stay human actions in the app. ## How sign-in works Sidecars uses **OAuth 2.1** with the MCP authorization flow. There are no personal access tokens and no static bearer keys. * The MCP server is the **resource server**. It advertises its authorization server at `/.well-known/oauth-protected-resource/mcp`. * The host registers itself dynamically (Dynamic Client Registration or Client ID Metadata Documents), runs PKCE, and exchanges a code for a **JWT access token**. * Every request carries `Authorization: Bearer `. The server verifies the signature, issuer, expiry and, when present, audience. Opaque tokens are refused. * A presented-but-invalid token is refused on **every** method, including public ones, so a stale credential fails immediately rather than at first use. Access tokens carry the person (`sub`), the active workspace (`org_id`), the OAuth client that obtained the token (`client_id`), the granted scopes and a 24-hour expiry. ## Auditing and attribution * Every tool call is recorded in the workspace's agent activity history (tool name, argument digest, sizes, latency, outcome). Arguments themselves are not stored. * Everything an agent writes lands **as you, via the host**. Version rows, comments and cards show a "via" badge such as "Thomas · via Claude Code". The host name is the host's own claim (its `User-Agent` product token); the verified fact behind the badge is the OAuth client id. * Every document and page write checkpoints first. Checkpoints are undoable in the app for a short period and restorable for longer; named versions are kept indefinitely. See [`get_document_versions`](/reference/documents#get_document_versions). An MCP session runs in the **host's** context. Text inside a document that reads like an instruction ("edit the Budget doc") is the host's trust boundary to handle, not the server's. The compensating controls are the audit trail, undo, and the loud "via" attribution on everything written.