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.
| Actor | Main scope | Typical use |
|---|---|---|
| Board session | User memberships and instance role | Browser requests |
| Board API key | The key owner's current memberships and instance role | CLI or service access for a user |
| Cloud tenant actor | The provisioned company plus other active memberships | Cloud-managed requests |
| Agent API key or JWT | One agent and its company | Agent work and runtime calls |
| Local implicit board | The local trusted instance | Local 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:
- Resolve the public token and reject an invalid, expired, revoked, or unsupported replay.
- Check that the requested join type is allowed.
- Require a signed-in board user for a human join.
- Create or replay the join request.
- Approve the human request directly or wait for approval of the agent request.
- Create the membership and apply the role or grant defaults.
- 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:managegrants 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
| Trigger | Consequence | Guard |
|---|---|---|
| A request has no valid session, board key, agent credential, or trusted identity | The request is unauthenticated and protected routes reject it | Actor middleware and assertAuthenticated |
| Auth cookies are issued for an untrusted origin or with the wrong deployment security mode | Sign-in can fail or a cookie can be exposed outside the intended deployment path | Deployment-scoped cookie prefix, trusted origins, and secure-cookie selection |
| A managed workspace handoff is attempted without the server-derived workspace identity | The password-independent exchange is unavailable rather than accepting a spoofed request target | Conditional handoff plugin registration and persisted identity resolution |
| An account issuer backfill misses an existing Better Auth account | The required account schema upgrade fails and authentication remains unavailable after the upgrade | Total issuer backfill before the NOT NULL constraint and unique issuer/account key |
| A board user requests a company outside its active membership set | The route denies the request rather than treating the user as instance-wide | assertCompanyAccess and hasCompanyAccess |
| A viewer sends a write request | The route rejects the write while preserving permitted read access | Active membership role checks in assertCompanyAccess and authorization decisions |
| An agent credential targets another company | The agent request is denied | Agent company binding in actor middleware and the authorization service |
| An invitation is expired, revoked, or reused outside an allowed replay | The invitation is hidden or cannot create another join request | Invite state checks, replay rules, and the invite token rate limiter |
| Two users try to claim the first admin at the same time | Only one claim succeeds | Transactional lock in claimFirstInstanceAdmin |
| A resource exists in another company | The caller receives the same not-found result as for a missing resource | getAccessibleResource and hasCompanyAccess |
| An issue write targets an issue or parent outside the actor's visible scope | The comment, mutation, or child assignment is denied | Shared visible-issue write decision in the authorization service |
| A private project or issue is read without an allowed principal | The resource and related task data are denied, including through list or search paths | Privacy predicates in authorization decisions and SQL read conditions |
| A workspace or approval links to an unreadable project or issue | The derived record is hidden instead of exposing task metadata | executionWorkspaceReadSqlCondition and approvalReadSqlCondition |
| Private task content is sent to a shared channel or to an unknown recipient | Publication is blocked | Direct-message requirement and current recipient identity and issue-read checks |
| An agent's responsible or authorizing user is missing or lacks authority | Protected agent action is denied, or responsible-user denial can be recorded in shadow mode during rollout | Responsible-user and authorizing-user intersections in the authorization service |
| A resource-membership policy hook fails | The personal membership change is rejected | Fail-closed policy evaluation |
| A task target has a blocked or unknown assignment policy | Assignment is denied unless a matching scoped grant applies | Assignment policy evaluation and scoped task grants |
| A private or protected task target has no matching scoped grant | Simple company-wide assignment is denied | Restricted assignment policy check |
| A scoped grant does not cover the requested project, target, user, or subtree | The action is denied even when the principal has the grant name | Structured scope checks in the authorization service |
| A low-trust, task-bridge, or skill-test credential requests an action outside its boundary | The narrow credential cannot use broad company, peer-agent, runtime, secret, or unrelated issue APIs | Trust-boundary and key-scope decisions in the authorization service |
| Company interaction policy blocks an otherwise allowed agent operation | Assignment, comment, edit, or configuration work is denied | Final agent interaction policy check |
| A public invite endpoint receives repeated token guesses | The client is rate limited before unlimited token lookup can occur | Router-level invite rate limiter keyed by the request address |
| Instance access is managed by the hosting operator | Instance-admin user routes reject access while company-scoped access routes remain available | assertAccessAdminVisible and company permission guards |
| A board actor has a missing user record | Session and profile responses are rejected instead of returning a partial identity | Current-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 role | Company access remains in place and the archive is rejected | Protected member checks in server/…/access.ts |
| An agent reuses an expired or consumed join claim secret | No second initial API key is issued | Claim-secret expiry, hash comparison, and atomic consumption |
Key files
| File | Why to read it |
|---|---|
| server/…/better-auth.ts | Defines the Better Auth boundary, deployment trust settings, session integration, and managed workspace handoff |
| server/…/auth.ts | Shows how requests become board or agent actors |
| server/…/authz.ts | Defines shared authentication, company, and not-found guards |
| server/…/authorization.ts | Centralizes action decisions, membership and grants, privacy, delegated-user intersections, scoped credentials, trust boundaries, assignment policy, interaction policy, and derived-record read filters |
| server/…/access.ts | Covers invitations, join requests, board claims, access administration, invite-token protection, and agent key claims |
| server/…/first-admin-claim.ts | Defines the one-time first instance-admin claim |
| server/…/board-claim.ts | Defines local board ownership transfer |
| server/…/auth.ts | Exposes the current session, optional board bootstrap, and editable user profile |
| server/…/board-bootstrap.ts | Limits session bootstrap company data to the actor's resolved access set and reports board access |
| packages/…/auth.ts | Defines the Better Auth account identity key and user/session records |
| packages/…/0230_better_auth_account_issuer.sql | Preserves existing Better Auth account identities during the issuer schema upgrade |
| packages/…/better-auth-account-issuer-migration.test.ts | Verifies that account issuer backfill covers credential and social account rows |
| server/…/user-profiles.ts | Builds company-scoped member profiles and activity summaries |
| server/…/resource-memberships.ts | Owns personal project, agent, and document membership state |
| server/…/app.ts | Shows middleware order and route registration |
| packages/…/company_memberships.ts | Defines the company principal boundary |
| packages/…/invites.ts | Defines invitation lifetime and consumption state |