Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / identity-and-access-control

Identity and access control

Identity and access control connect a signed-in person or an authenticated agent to the companies and resources that it may use. Better Auth provides browser identity and sessions. Paperclip then resolves that identity into an actor, applies company membership and permission rules, and enforces the result at each route. See Security and governance for the wider security model, Secrets and credentials for credential use, and Runtime and tool governance for access decisions around tools and runtimes.

Identity sources

Better Auth sessions

Better Auth is the browser identity system for authenticated deployments. It stores users, sessions, accounts, and verification records through the database adapter, while the server turns a valid session into a board actor with the user identity and active company memberships. The browser can then read or update its own profile through the Paperclip auth routes.

The auth boundary uses a deployment-scoped cookie name and a trusted-origin list. Auth rate limiting is enabled by default for authenticated deployments, and secure cookies are adjusted only for an explicitly supported local or managed loopback case. A managed workspace login handoff is exposed only when the process has a server-derived handoff identity, so request headers cannot retarget that exchange.

Each Better Auth account uses an issuer namespace together with its provider account ID. This keeps credential and social account identities distinct and gives sign-up and sign-in the same stable account key. Database upgrades backfill that namespace for all existing account rows before making it required, so an upgrade does not break authentication for users who already have accounts.

The same actor path also accepts a trusted Cloud tenant identity when the deployment is behind the Paperclip Cloud control plane. Local trusted deployments use an implicit board identity instead of a browser login. These modes change how an actor is established, but later company and route checks still use the actor's resolved scope.

This diagram shows how an inbound request becomes an actor before application routes handle it.

flowchart LR
    Request[Inbound request] --> Mode{Identity source}
    Mode -->|Browser cookie| Session[Better Auth session]
    Mode -->|Trusted Cloud headers| Cloud[Cloud tenant identity]
    Mode -->|Bearer token| Token[Board key or agent credential]
    Mode -->|Local trusted mode| Local[Implicit local board]
    Session --> Actor[Resolved actor]
    Cloud --> Actor
    Token --> Actor
    Local --> Actor
    Actor --> Scope[Company scope and role context]
    Scope --> Routes[Route-level authorization]

References: server/…/better-auth.ts• L49-123 server/…/better-auth.ts• L189-245 server/…/better-auth.ts• L246-373 server/…/auth.ts• L206-274 server/…/auth.ts• L492-667 server/…/auth.ts• L38-105 packages/…/auth.ts• L24-59 packages/…/0230_better_auth_account_issuer.sql• L1-23 packages/…/better-auth-account-issuer-migration.test.ts• L43-58

Board and agent actors

The access layer distinguishes a board actor from an agent actor. A board actor represents a human user or a local board. An agent actor represents an agent authenticated with an API key or signed local token and carries its company, credential scope, and optional responsible user.

Board API keys provide a durable non-browser path for a user. Agent credentials remain tied to the agent's company. When an agent acts for a responsible user, authorization can require the intersection of the agent's permissions and that user's active company access.

ActorMain scopeTypical use
Board sessionUser memberships and instance roleBrowser requests
Board API keyThe key owner's current memberships and instance roleCLI or service access for a user
Cloud tenant actorThe provisioned company plus other active membershipsCloud-managed requests
Agent API key or JWTOne agent and its companyAgent work and runtime calls
Local implicit boardThe local trusted instanceLocal trusted operation

References: server/…/auth.ts• L277-440 server/…/board-auth.ts• L69-107 server/…/authz.ts• L197-245

Instance ownership and claims

First-admin claim

The first-admin claim establishes the first instance administrator in an authenticated private deployment. It is an atomic, one-time operation: the first successful signed-in user receives the instance-admin role, while a concurrent or later claimant receives an already-claimed result.

The instance-admin role is an instance-level elevation. It is separate from company membership, although bootstrap flows can also create the company access needed by the new owner. Browser claiming is limited to the intended authenticated private deployment path.

References: server/…/first-admin-claim.ts• L7-54 server/…/access.ts• L2742-2765 server/…/access.ts• L3667-3711

Board ownership claim

The board ownership claim moves a local board's initial ownership to a signed-in browser user. A short-lived challenge proves that the user reached the intended local board flow. A successful claim replaces the local board administrator with the signed-in user and gives that user owner access to the companies already on the instance.

The challenge is available only when the instance is in authenticated mode and still has the initial local-board administrator. This keeps the handoff useful for onboarding without leaving a permanent ownership bypass after the board has an external owner.

References: server/…/board-claim.ts• L44-67 server/…/board-claim.ts• L86-160 server/…/access.ts• L2694-2740

Company access lifecycle

Invitations and join requests

Company invitations provide a controlled path for a human or an agent to request access to a company. An invitation has a limited lifetime and a high-entropy public token. The stored record keeps only the token hash, and the public invite routes hide revoked and expired invitations. Public invite-token routes also have a per-client request limit so token lookup cannot become an online search tool.

Creating or revoking a company invitation requires the users:invite company permission. An accepted invitation creates or reuses a join request. Human requests can receive membership and grants at acceptance. Agent requests remain pending until an authorized company user approves them, at which point the system creates the agent membership and applies the invitation defaults.

Invitation defaults can define the human role, explicit human grants, agent grants, and onboarding data. When explicit human grants are absent, the human role supplies the initial permission set. Explicit grants take precedence over those role defaults. Agent invitation grants are preserved and always include tasks:assign, so changing invitation defaults changes the access granted at the join boundary rather than only changing the invitation's display data. Agent onboarding also validates the selected runtime's connection data before it creates a join request, which keeps unusable or unsafe runtime credentials out of the access flow.

An accepted invite is not a general access bypass. A matching human join can replay the request, and an OpenClaw gateway agent can replay a pending or approved request to refresh its join defaults. Other attempts to reuse an accepted invite are rejected. An approved agent can use its one-time claim secret to receive its initial API key; the secret expires and cannot be used twice.

When the system processes an invitation, it follows this sequence:

  1. Resolve the public token and reject an invalid, expired, revoked, or unsupported replay.
  2. Check that the requested join type is allowed.
  3. Require a signed-in board user for a human join.
  4. Create or replay the join request.
  5. Approve the human request directly or wait for approval of the agent request.
  6. Create the membership and apply the role or grant defaults.
  7. For an approved agent, accept one valid claim secret and issue its initial key.

References: packages/…/invites.ts• L4-28 server/…/access.ts• L2656-2685 server/…/access.ts• L3059-3122 server/…/access.ts• L3317-3426 server/…/access.ts• L3643-4133 server/…/access.ts• L4136-4478 server/…/invite-grants.ts• L40-68 server/…/company-member-roles.ts• L21-73 server/…/invite-join-grants.test.ts• L12-144

Company memberships and roles

Company membership is the main boundary between a user or agent and a company. A membership identifies the principal type and principal ID, records whether access is active, and may carry a human role such as owner, admin, operator, or viewer.

Human roles provide default grants. Owner and admin roles cover company administration, invitations, and approval work. Operators receive a narrower task assignment capability. Viewers have no role-derived write grant and are treated as read-only where route rules permit visibility.

The membership row and the permission grants work together. An explicit grant cannot replace the need for active membership, and a role change must keep the grants that represent that role in step with the membership.

Company member management also protects the access hierarchy. A user cannot remove itself, an instance admin, or a member at the same or higher company role. Company owners and admins cannot be archived through the ordinary company member flow. This prevents a lower-level company action from removing the control needed to manage access.

References: packages/…/company_memberships.ts• L4-28 server/…/company-member-roles.ts• L4-65 server/…/authorization.ts• L929-1122 server/…/access.ts• L1290-1375 server/…/access.ts• L4501-4655

User profiles

Current user profile

The current-user profile is the identity surface used by the signed-in board. The session and profile routes expose the user's ID, email, display name, and image. The session response also carries the browser-facing session identity, optional company bootstrap data, and front-end observability settings needed by the board. Bootstrap data is limited to companies in the actor's resolved access set and includes instance-admin status without turning directory visibility into company entry. It exposes only the front-end Sentry DSN and never the backend DSN. The user can update the display name and image without changing the membership or authorization records.

These routes require a board actor with a user ID. This prevents agent credentials and anonymous requests from being treated as human profile updates. If the signed-in user no longer exists, the routes reject the request rather than returning an incomplete identity.

References: server/…/auth.ts• L14-40 server/…/auth.ts• L42-82 server/…/auth.ts• L84-126 server/…/board-bootstrap.ts• L6-26 packages/…/auth.ts• L3-22

Company user profile

The company user profile presents a member's identity together with work activity inside one company. It resolves a stable user-facing slug from the member's name or email, then reports membership state, role, recent issue involvement, activity, and usage summaries.

The profile is company-scoped. The route checks company access before it resolves the member and only counts visible work in that company. This makes a profile a view of participation within an allowed company rather than a global directory of user activity.

References: server/…/user-profiles.ts• L64-92 server/…/user-profiles.ts• L301-434

Authorization services

Authorization decisions

The authorization service converts an actor, an action, and a resource into an allow or deny decision. A resource is company-scoped and can represent a company, agent, project, or issue. The decision includes a reason so callers and audit records can distinguish missing membership, missing grants, a scope mismatch, or a policy boundary. Scoped grants can limit an action to selected projects, agents, users, or reporting subtrees instead of granting it across the full company.

Authorization evaluates the actor's company boundary before it applies resource rules. It then combines role behavior, explicit grants, credential scope, trust boundaries, resource policy, and privacy. Unknown or blocked policy data fails closed, and a final interaction policy can deny an agent operation that would otherwise be allowed.

Board decisions use local trust, instance-admin elevation, active company membership, role behavior, and explicit grants. Cloud tenant decisions use the trusted tenant scope and active membership for the permitted read and non-viewer work surface. Agent decisions first keep the agent inside its company. They then apply credential scope, trust boundaries, resource policies, and agent grants. Some actions use bounded rules instead of a single grant, such as an agent acting on its own issue or a user with a non-viewer company role changing an issue.

Issue comments and mutations in standard trust contexts share the issue visibility decision. A write is rejected when the target issue, or the parent issue for a new child, is not visible to the actor. Task assignment also evaluates the target agent, project, issue, and parent policies. Private or protected targets require a matching scoped assignment grant rather than simple company-wide access.

Project and issue privacy also controls reads. A private project or issue is visible only to its allowed principals, such as the responsible user, creator, assignee, an active project member, or an explicit issue grantee. The same read predicates are pushed into list and search queries so a hidden resource is not exposed through a different read path. Task-derived workspaces and approvals apply the linked project and issue checks as well. Private task output can leave through a direct message only when each known recipient remains allowed to read the task.

Narrow execution contexts do not become broad company access. Low-trust agents stay inside their allowed agent, project, or issue boundary. Task-bridge credentials use only their declared project, parent-issue, and assignee limits. Skill-test credentials use only their harness issue. These checks make the action decision depend on the actor's current resource context, not only on the actor's general role.

Protected configuration changes also separate direct authority from a suggestion. A direct grant can apply the change. A suggestion grant needs accepted consent before it can do so. Inbox management adds a target-user policy, while an explicitly scoped grant can override that policy for the named user. Connection management applies the same company and principal checks to connection setup, profiles, gateways, and tests.

Authorization can also block an agent interaction after the normal decision allows it. This final check covers actions such as assignment, comments, edits, and configuration changes when company interaction policy disables the agent's operation against the target. This keeps a broad permission grant from bypassing a more specific human-controlled interaction rule.

References: server/…/authorization.ts• L65-184 server/…/authorization.ts• L362-447 server/…/authorization.ts• L488-582 server/…/authorization.ts• L626-764 server/…/authorization.ts• L1359-1514 server/…/authorization.ts• L1572-1690 server/…/authorization.ts• L1708-1752 server/…/authorization.ts• L1845-2054 server/…/authorization.ts• L2056-2802 server/…/authorization.ts• L2804-3063 server/…/authorization.ts• L3094-3172

Responsible-user and authorizing-user intersections

An agent credential can carry a responsible user. For actions that need a human authority, the authorization service checks that user's existence, active membership, and ability to perform the same action. The effective result is therefore bounded by both the agent's authority and the responsible user's company access.

Some integrations also carry a server-derived authorizing user. This identity is checked against current company membership as a separate intersection, without letting an agent select the user that supplies the authority. The two checks keep delegated work tied to the people who are allowed to authorize it.

The responsible-user intersection denies unavailable or unauthorized responsible users in enforcement mode. A shadow mode can record the denial while preserving the prior agent result during a controlled transition. This mode affects the intersection check only; it does not grant a missing identity or cross-company access. Some issue actions use the active non-viewer membership as the human ceiling. An agent's explicit skill-change grant can satisfy the grant side of a skill configuration change without duplicating that grant on the responsible user's board account. Inbox access remains separate because it has its own target-user policy and explicit grant rules.

References: server/…/auth.ts• L359-380 server/…/authorization.ts• L592-605 server/…/authorization.ts• L766-815 server/…/authorization.ts• L2804-2941

Resource memberships

Personal resource memberships

Resource memberships let a board user keep personal joined and starred state for projects, agents, and documents inside a company. They are a navigation and view preference layer. They do not replace company membership or permission grants.

The service limits changes to the signed-in user's own resource memberships. It checks active company access and can apply a policy hook before it writes a change. A failed policy hook denies the change. The API returns the user's combined resource state and records changed state for activity tracking.

References: server/…/resource-memberships.ts• L107-170 server/…/resource-memberships.ts• L175-250 server/…/resource-memberships.ts• L11-165 packages/…/resource-memberships.ts• L1-29

Route-level enforcement

Authentication and company gates

Route enforcement starts after actor middleware has resolved the request. Shared guards then separate authentication from authorization: authentication asks whether an actor exists, while company access asks whether that actor can reach the requested company. Company-scoped access routes add the required permission after this boundary, so a valid identity alone does not grant member management, invitation, or join approval access.

Company write checks also enforce active membership and viewer read-only behavior. Agent requests cannot cross the agent's company boundary. Local implicit access is the deliberate exception for trusted local operation, and instance-admin elevation is checked separately from ordinary company membership. Instance user administration can also be hidden when the hosting operator owns that control surface, while company invitations and membership routes remain company-scoped.

References: server/…/authz.ts• L26-72 server/…/authz.ts• L75-121 server/…/authorization.ts• L2056-2334 server/…/authorization.ts• L2336-2364 server/…/access.ts• L62-75 server/…/access.ts• L3017-3042 server/…/access.ts• L4136-4655

Resource existence protection

Company-scoped routes must avoid revealing whether a resource exists in another company. The preferred access helper returns the same not-found response for a missing resource and a cross-company resource, then applies the normal company checks only after the resource passes that boundary.

This rule protects tenant isolation at the response level. A route that first loads an object and returns different errors for missing and cross-company objects becomes an existence oracle even if later writes are blocked.

References: server/…/authz.ts• L123-195

Route registration

The application installs actor middleware before auth and application routes. It mounts the Better Auth handler for auth protocol requests and mounts the Paperclip auth, access, profile, and resource-membership routes under the API. Individual route groups add the guards and permission checks needed for their resource type.

The result is a layered boundary: request identity is resolved once, common company checks prevent tenant crossing, route permissions protect access administration, and resource-specific services decide whether the requested action is allowed.

References: server/…/app.ts• L350-367 server/…/app.ts• L400-423 server/…/app.ts• L524-540 server/…/app.ts• L647-657 server/…/access.ts• L2636-2787 server/…/access.ts• L4177-4765

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep every actor source aligned with the fields used by assertCompanyAccess, hasCompanyAccess, and the authorization service. A new identity path that omits company IDs or membership status can silently widen or remove access.
  • Keep Better Auth cookie prefix, trusted origins, secure-cookie selection, rate limiting, and managed workspace handoff tied to the deployment identity. A new public URL or proxy path must not create an untrusted auth origin or a header-controlled handoff target.
  • Keep Better Auth account identity changes aligned with the issuer and provider-account key used by sign-in. Account migrations must give every existing row a valid issuer before the required schema constraint is applied.
  • Keep human role defaults, invitation defaults, membership creation, and principal grants in step. A new role or grant must work for both direct membership creation and invitation acceptance.
  • Preserve the distinction between instance-admin elevation and company membership. Cloud tenant identity must not gain persistent instance-admin rows as a side effect of request authentication.
  • Apply the same company boundary before loading a resource and after loading it. Use the not-found path for cross-company resources so route changes do not restore an existence oracle.
  • Keep issue write visibility aligned with issue reads. New issue-write paths must resolve a child-create parent before they allow comments, mutations, or assignment.
  • Keep project and issue privacy predicates aligned across direct reads, list and search queries, execution workspaces, approvals, and chat publication. A new derived read path must not reveal task data that the source resource hides.
  • Keep responsible-user and server-derived authorizing-user checks aligned between actor construction and authorization intersection. Missing or inactive users must remain a visible denial for protected actions.
  • Treat invitation tokens, board claim challenges, board API keys, and agent join claim secrets as separate credentials with separate lifetimes and replay rules.
  • Keep scoped grant shapes aligned with the resource scope passed to authorization. A grant that names a project, target, user, or subtree must not silently become a company-wide grant when a route changes its input shape.
  • Keep assignment policy evaluation aligned with the task-assignment paths for board users and agents. Unknown or protected target policy must fail closed unless an explicit scoped grant allows the action.
  • Keep direct and suggested protected changes aligned with consent checks. A suggestion grant must not become a direct mutation when a route changes its action or scope.
  • Keep inbox target-user policy and scoped inbox:manage grants aligned. A grant override must remain limited to the named user and must not become a company-wide inbox permission.
  • Keep connection-management actions behind their company, principal, and credential-scope checks. Scoped test and task-bridge credentials must not gain connection administration through a new route.
  • Keep public invite routes behind the same token-state checks and rate limit. New onboarding or invite replay routes must not expose revoked, expired, or consumed invite state.
  • Keep operator-managed instance access distinct from company-scoped member administration. Hiding instance user administration must not hide company invite and membership controls.
  • Keep low-trust, task-bridge, and skill-test boundaries ahead of broad agent permissions. A new action must declare whether each narrow credential type can use it.
  • Keep agent interaction policy checks after the normal authorization decision for every supported interaction operation. A broad grant must not bypass a company-level interaction block.
  • Keep member-management hierarchy checks aligned with role rank and instance-admin protection. A route that adds a new archive or role-change path must not allow self-removal or removal of an equal or higher authority.

Important failure modes

TriggerConsequenceGuard
A request has no valid session, board key, agent credential, or trusted identityThe request is unauthenticated and protected routes reject itActor middleware and assertAuthenticated
Auth cookies are issued for an untrusted origin or with the wrong deployment security modeSign-in can fail or a cookie can be exposed outside the intended deployment pathDeployment-scoped cookie prefix, trusted origins, and secure-cookie selection
A managed workspace handoff is attempted without the server-derived workspace identityThe password-independent exchange is unavailable rather than accepting a spoofed request targetConditional handoff plugin registration and persisted identity resolution
An account issuer backfill misses an existing Better Auth accountThe required account schema upgrade fails and authentication remains unavailable after the upgradeTotal issuer backfill before the NOT NULL constraint and unique issuer/account key
A board user requests a company outside its active membership setThe route denies the request rather than treating the user as instance-wideassertCompanyAccess and hasCompanyAccess
A viewer sends a write requestThe route rejects the write while preserving permitted read accessActive membership role checks in assertCompanyAccess and authorization decisions
An agent credential targets another companyThe agent request is deniedAgent company binding in actor middleware and the authorization service
An invitation is expired, revoked, or reused outside an allowed replayThe invitation is hidden or cannot create another join requestInvite state checks, replay rules, and the invite token rate limiter
Two users try to claim the first admin at the same timeOnly one claim succeedsTransactional lock in claimFirstInstanceAdmin
A resource exists in another companyThe caller receives the same not-found result as for a missing resourcegetAccessibleResource and hasCompanyAccess
An issue write targets an issue or parent outside the actor's visible scopeThe comment, mutation, or child assignment is deniedShared visible-issue write decision in the authorization service
A private project or issue is read without an allowed principalThe resource and related task data are denied, including through list or search pathsPrivacy predicates in authorization decisions and SQL read conditions
A workspace or approval links to an unreadable project or issueThe derived record is hidden instead of exposing task metadataexecutionWorkspaceReadSqlCondition and approvalReadSqlCondition
Private task content is sent to a shared channel or to an unknown recipientPublication is blockedDirect-message requirement and current recipient identity and issue-read checks
An agent's responsible or authorizing user is missing or lacks authorityProtected agent action is denied, or responsible-user denial can be recorded in shadow mode during rolloutResponsible-user and authorizing-user intersections in the authorization service
A resource-membership policy hook failsThe personal membership change is rejectedFail-closed policy evaluation
A task target has a blocked or unknown assignment policyAssignment is denied unless a matching scoped grant appliesAssignment policy evaluation and scoped task grants
A private or protected task target has no matching scoped grantSimple company-wide assignment is deniedRestricted assignment policy check
A scoped grant does not cover the requested project, target, user, or subtreeThe action is denied even when the principal has the grant nameStructured scope checks in the authorization service
A low-trust, task-bridge, or skill-test credential requests an action outside its boundaryThe narrow credential cannot use broad company, peer-agent, runtime, secret, or unrelated issue APIsTrust-boundary and key-scope decisions in the authorization service
Company interaction policy blocks an otherwise allowed agent operationAssignment, comment, edit, or configuration work is deniedFinal agent interaction policy check
A public invite endpoint receives repeated token guessesThe client is rate limited before unlimited token lookup can occurRouter-level invite rate limiter keyed by the request address
Instance access is managed by the hosting operatorInstance-admin user routes reject access while company-scoped access routes remain availableassertAccessAdminVisible and company permission guards
A board actor has a missing user recordSession and profile responses are rejected instead of returning a partial identityCurrent-user lookup and signed-in board checks in server/…/auth.ts
A user tries to archive itself, an instance admin, or a member at the same or higher roleCompany access remains in place and the archive is rejectedProtected member checks in server/…/access.ts
An agent reuses an expired or consumed join claim secretNo second initial API key is issuedClaim-secret expiry, hash comparison, and atomic consumption

Key files

FileWhy to read it
server/…/better-auth.tsDefines the Better Auth boundary, deployment trust settings, session integration, and managed workspace handoff
server/…/auth.tsShows how requests become board or agent actors
server/…/authz.tsDefines shared authentication, company, and not-found guards
server/…/authorization.tsCentralizes action decisions, membership and grants, privacy, delegated-user intersections, scoped credentials, trust boundaries, assignment policy, interaction policy, and derived-record read filters
server/…/access.tsCovers invitations, join requests, board claims, access administration, invite-token protection, and agent key claims
server/…/first-admin-claim.tsDefines the one-time first instance-admin claim
server/…/board-claim.tsDefines local board ownership transfer
server/…/auth.tsExposes the current session, optional board bootstrap, and editable user profile
server/…/board-bootstrap.tsLimits session bootstrap company data to the actor's resolved access set and reports board access
packages/…/auth.tsDefines the Better Auth account identity key and user/session records
packages/…/0230_better_auth_account_issuer.sqlPreserves existing Better Auth account identities during the issuer schema upgrade
packages/…/better-auth-account-issuer-migration.test.tsVerifies that account issuer backfill covers credential and social account rows
server/…/user-profiles.tsBuilds company-scoped member profiles and activity summaries
server/…/resource-memberships.tsOwns personal project, agent, and document membership state
server/…/app.tsShows middleware order and route registration
packages/…/company_memberships.tsDefines the company principal boundary
packages/…/invites.tsDefines invitation lifetime and consumption state