paperclipai/paperclip · error

Agent authentication required

Error message

Agent authentication required

What it means

Authenticity sentinel in the agents routes: the caller attempted an agent-authenticated operation without valid agent credentials (missing/invalid agent API key on an endpoint that accepts agent actors), so the request is rejected rather than falling back to anonymous access.

Source

Thrown at server/src/routes/agents.ts:3288

  // nothing about that sandbox, so the route checks the environment's own
  // OPENAI_API_KEY binding instead and otherwise reports "unknown" -- never
  // "present" from a host login the sandbox does not share.
  async function evaluateCodexAuthSignal(
    req: Request,
    companyId: string,
    environmentId: string | null,
  ): Promise<AdapterAuthSignal> {
    if (environmentId) {
      const environment = await environmentsSvc.getById(environmentId);
      if (environment && environment.driver !== "local") {
        const environmentEnv = Object.fromEntries(
          Object.entries(parseObject(environment.envVars)).filter(
            ([key]) => !isForbiddenConfigEnvKey(key),
          ),
        );
        const apiKeyBinding = environmentEnv.OPENAI_API_KEY;
        if (apiKeyBinding !== undefined) {
          const resolution = await secretsSvc.resolveEnvBindings(
            companyId,
            { OPENAI_API_KEY: apiKeyBinding },
            buildActorSecretContext(req, { consumerType: "environment", consumerId: environmentId }),
          );
          if (asNonEmptyString(resolution.env.OPENAI_API_KEY)) {
            return "present";
          }
        }
        return "unknown";
      }
    }

    const readiness = await evaluateCodexCredentialReadiness({
      env: process.env,
      companyId,
      configuredCodexHome: null,
      configuredApiKey: null,
    });

View on GitHub (pinned to 01ad858492)

Solutions

1. Authenticate with a valid agent API key (Authorization: Bearer ...) and retry.

When it happens

Trigger: Thrown at server/src/routes/agents.ts:2864 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/4a754403db1359a5. Report an issue: GitHub.