paperclipai/paperclip · error · Error

Board access is required to resolve companies across the ins

Error message

Board access is required to resolve companies across the instance. Use a company ID/prefix for your current company, or run with board authentication.

What it means

Thrown when the fallback board-wide GET /api/companies fails with a 403 whose message contains 'Board access required'. This path is reached only after company-scoped lookups failed to find a target, so the CLI attempted an instance-wide listing that agent-scoped credentials cannot access. The error message tells the caller board auth is needed for cross-instance resolution.

Source

Thrown at cli/src/commands/client/company.ts:1968

          if (!target && ctx.companyId) {
            const scoped = await ctx.api.get<Company>(apiPath`/api/companies/${ctx.companyId}`, { ignoreNotFound: true });
            if (scoped) {
              try {
                target = resolveCompanyForDeletion([scoped], normalizedSelector, by);
              } catch {
                // Fallback to board-wide lookup below.
              }
            }
          }

          if (!target) {
            try {
              const companies = (await ctx.api.get<Company[]>("/api/companies")) ?? [];
              target = resolveCompanyForDeletion(companies, normalizedSelector, by);
            } catch (error) {
              if (error instanceof ApiRequestError && error.status === 403 && error.message.includes("Board access required")) {
                throw new Error(
                  "Board access is required to resolve companies across the instance. Use a company ID/prefix for your current company, or run with board authentication.",
                );
              }
              throw error;
            }
          }

          if (!target) {
            throw new Error(`No company found for selector '${normalizedSelector}'.`);
          }

          assertDeleteConfirmation(target, opts);

          await ctx.api.delete<{ ok: true }>(apiPath`/api/companies/${target.id}`);

          printOutput(
            {
              ok: true,

View on GitHub (pinned to 67001ec6eb)

Solutions

Use a board/instance-admin token: run `paperclipai connect` as a board persona or set a board API key.
Restrict the selector to the agent's own company (use its ID or prefix) so the board-wide lookup is never needed.
Resolve the company ID first via `paperclipai company current --json` and pass `--by id`.

Example fix

# before (agent key, cross-company selector)
export PAPERCLIP_API_KEY=$AGENT_KEY
paperclipai company delete otherco --yes --confirm OTHER
# after (board token)
export PAPERCLIP_API_KEY=$BOARD_KEY
paperclipai company delete otherco --yes --confirm OTHER

Defensive patterns

Strategy: try-catch

Validate before calling

// Detect board-access requirement before triggering the board-wide lookup.
function tokenIsBoardScoped(profile: { persona?: string }): boolean {
  return profile.persona === "board";
}
// If not board-scoped, restrict the selector to the agent's own company to avoid the fallback.

Type guard

import { ApiRequestError } from "../../client/http.js";

function isBoardAccess403(err: unknown): boolean {
  return err instanceof ApiRequestError && err.status === 403 && err.message.toLowerCase().includes("board access required");
}

Try / catch

try {
  const companies = await ctx.api.get<Company[]>("/api/companies");
} catch (err) {
  if (isBoardAccess403(err)) {
    throw new Error("Switch to a board token or restrict the selector to the agent's own company.");
  }
  throw err;
}

Prevention

Use board tokens for cross-company operations; agent keys for scoped ones.
For agent automation, always pass an explicit company-scoped selector to avoid the board fallback.
Document which commands require board auth.

When it happens

Trigger: Authenticated with an agent API key (scoped to one company), selector did not match the scoped company, and the CLI fell back to GET /api/companies which returns 403 for non-board tokens.

Common situations: Agent automation running `company delete` with a selector outside its own company; CI using an agent key to clean up companies created by other agents; no board token configured.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/625edf9f1074cf73. Report an issue: GitHub.