reference_browserhand_auth_pattern - EyevinnOSC/community GitHub Wiki
name: reference-browserhand-auth-pattern description: Verified pattern for authenticating to birme-browserhand (and similarly-gated service instances) from an OSC agent task, documented on the wiki metadata: type: reference
Verified end-to-end (2026-08-13) and documented on the wiki: birme-browserhand instances have no working direct-HTTP auth path. The public ingress returns a bare HTTP 401 (no WWW-Authenticate) for every direct call, including Authorization: Bearer <PAT>, x-pat-jwt, x-jwt, and osc-access-token headers, all confirmed to give the identical 401. The only mechanism that works is the OSC MCP tool call-service-endpoint, which authenticates server-side and needs no token from the caller. This requires the agent task to run in Managed mode (default OSC Access Token field on create-agent-task) to get MCP access to mcp.osaas.io and the mcp__OSC__-prefixed toolset.
Full worked example (create Browserhand instance -> agent task -> create session -> navigate -> read content -> assert text present -> close session) is documented in Feature:-My-Agent-Tasks.md under "Example: Verifying a Deployed Change with Browserhand", with the corrected endpoint reference on Service:-Browserhand.md.
Also documented as a known current limitation: create-agent-task's live schema has no scheduleType: "manual" field despite the wiki page describing one; every task (including one-off verification runs) requires a cronExpression. Workaround: use a cron expression unlikely to fire soon (e.g. 0 3 1 1 *), trigger once with run-agent-task, delete with delete-agent-task after use.
How to apply: When documenting or troubleshooting any service instance that returns unexplained 401s from direct HTTP/curl calls from within an agent task context, check whether call-service-endpoint (Managed-mode MCP) resolves it before assuming the service itself is misconfigured. This may be a general ingress-auth pattern beyond just Browserhand, worth re-verifying per-service since it hasn't been confirmed platform-wide.