WebCodex has several ways to authenticate because Server administration, model/API access, and Runner connectivity are different trust boundaries. Ordinary users do not need to learn WebCodex's internal identifier vocabulary to use it safely.
For normal daily use, follow Full Setup: redeem a one-time login code, let webcodex login create the local user and Runner credentials, and use the connection values it reports for ChatGPT.
If you are using an existing hosted shared-key Server, use the shared key supplied by its operator with webcodex connect. If you are only trying one repository temporarily, use the credential printed by webcodex share for that run.
Do not copy the Server bootstrap token to a client, and do not use a Runner token as an MCP/API token.
| Credential | Typical form | Used for |
|---|---|---|
| Server bootstrap token | WEBCODEX_TOKEN in the Server env |
Initial administration and emergency recovery |
| Pairing code | wc_pair_... |
One-time device/user enrollment |
| Personal API token (PAT) | wc_pat_... |
MCP and runtime API access for a managed user |
| Runner token | wc_agent_... |
webcodex-runner transport only |
| Shared key | wck_... |
Hosted shared-key MCP/runtime access and the matching Runner group |
| Project Credential | protected project-private file | One ProjectGrant's ordinary runtime API/MCP access |
| OAuth access token | wc_oat_... |
Delegated MCP/GPT access when OAuth is enabled |
| Account credential | wc_acct_... |
Advanced managed-account token creation only |
The prefixes are useful for diagnosing configuration mistakes. They are not a reason to expose every internal identifier to users.
WebCodex also uses non-secret IDs and opaque tool state internally. Users normally do not need to learn their formats.
| Kind | Examples | Meaning |
|---|---|---|
| Credential | PAT, Runner token, shared key, OAuth token | Authenticates a caller |
| Resource ID | Project, Job, Workflow Session, task | Identifies an object; does not grant access to it |
| Opaque tool state | continuation/recovery values returned by a tool | Helps continue or safely retry a specific workflow; not authentication |
The rule is simple: knowing an ID or opaque tool value never substitutes for authentication and authorization. Exact internal identity and continuity formats belong in maintainer contracts and code, not in this user guide.
- Do not print, log, commit, or paste whole credential files into chat.
- Prefer
--token-file <path>over command-line plaintext tokens. - Let an AI agent point to the exact protected file or field; the human should copy the secret when necessary.
- Status, diagnostics, and normal API responses intentionally avoid returning plaintext credentials.
- If a credential may have leaked, rotate or replace the credential according to the flow that created it.
WEBCODEX_TOKEN is the Server's bootstrap/admin credential. webcodex server init stores it in the Server environment. Use it for initial administration, user creation/pairing, and emergency recovery. Do not manually supply it to external MCP/GPT clients or reuse it as a Runner token.
The same-owner Desktop/local Server Tunnel is an intentional exception: its protected local authorization file uses bootstrap internally, while the ChatGPT connection contains no WebCodex secret. This trusted self-hosted connection carries that owner's authority; it is not a restricted delegated user. No additional Tunnel token is needed. Use the existing delegated credentials when connecting a different trust domain. Personal deployment lifecycle.
webcodex pairing create produces a short-lived wc_pair_* code. A repository machine redeems it with webcodex login <server-url> --code <code>. Login then creates the ordinary local files needed for user/API access and Runner connectivity.
The pairing code is temporary; it is not a long-lived API credential.
A PAT represents a managed user on MCP and the runtime API. The Server stores only its hash. webcodex login normally writes the user's token to webcodex-user-token under that Server/user's local configuration directory.
Use the smallest scopes needed for the workflow. A PAT used by an MCP coding client normally needs runtime/project scopes appropriate to the actions that client will perform. Account-management authority is separate and should not be added to ordinary coding clients.
A Runner token authenticates webcodex-runner and is bound to the configured Runner client_id. It is rejected on MCP/runtime/account surfaces.
The wc_agent_* prefix is a compatibility-facing historical name. In current product terminology this is a Runner token, not a Durable Agent identity. The same rule applies to other retained agent_* wire/storage names: do not infer the Durable Agent domain from the compatibility name.
A shared key is the simple hosted connection credential used by webcodex connect. The same key can authenticate the MCP/runtime client and the matching Runner group. Different shared keys remain isolated from each other.
The protected profile stores the key after creation; repeated connect reuses it rather than printing it again. Shared-key mode is intended for simple trusted deployments, not as a replacement for managed multi-user IAM.
webcodex setup and temporary project-first flows use a protected Project Credential tied to one ProjectGrant. It is not a general user/admin token and must not be reused for unrelated projects. ProjectGrant Runner visibility plus canonical Project resolution prevents a credential from listing, resolving, or calling Projects from another grant. Direct Adaptive tools and call_runtime_tool use the same authority boundary.
Project-scoped credentials also cannot expand the Runner Project registry with ordinary register_project, create_project, or unregister_project operations. Path-based coding may reuse only an exact caller-visible registered Project; work_on_project(mode=worktree) is the canonical exception that may derive a managed worktree Project from that already-authorized source Project.
After verification, WebCodex keeps the non-secret authorization metadata it needs internally. It is not another credential the user needs to copy or manage.
Authentication identifies the user. Ownership limits whose resources may be managed. Credential scopes carry authority: admin is the credential-level super-scope, while account:manage grants narrower account, token, pairing and OAuth-client management within ownership boundaries. Bootstrap retains full authority. user.role remains legacy metadata and does not grant runtime/admin authority. PAT, Runner token, OAuth, shared-key and Project Credential kinds/audiences remain isolated.
OAuth lets MCP/GPT clients use the authorization-code flow instead of storing a long-lived PAT in the client. Register the exact callback URL required by the client and follow the connection output from webcodex share --auth oauth or webcodex connect --auth oauth.
The user-facing OAuth concepts are:
- client id — public identifier for the OAuth client;
- client secret — secret returned when the client is created;
- access token — delegated credential used by the client;
- refresh token — protocol credential used to refresh access;
offline_accessadds no WebCodex permission by itself; - allowed scopes — the maximum WebCodex permissions that client may request.
WebCodex never silently expands an existing OAuth client's allowed permissions when new scopes are introduced. Changing the allow-list is an explicit administrative action and invalidates old grants so the client must authorize again.
For ordinary hosted shared-key OAuth, webcodex connect ... --auth oauth keeps the Runner on its shared key and gives the MCP client a separate OAuth credential. --oauth-computer-permissions explicitly enables the additional Computer permissions offered by that flow; --oauth-local-mcp explicitly enables access to configured Runner-owned local MCP providers. Managed-user OAuth remains a separate advanced flow (--auth managed-oauth).
Shared-key OAuth delegation for Browser Use requires explicit --oauth-browser-permissions on connect --auth oauth. It adds only browser:read, browser:control, and browser:launch. The baseline excludes Browser scopes. Browser authority is independent of --oauth-computer-permissions and its consent checkboxes. Existing clients never expand automatically; narrow historical profiles gain only the explicitly selected class. Scope ceiling changes revoke old grants and require reauthorization. Reusing a Browser-enabled profile requires the flag again.
Managed-user OAuth snapshots credential authority when a first-party PAT authorizes the grant. Ordinary requested scopes must be supported globally, allowed by the client, and held by the PAT (admin satisfies every ordinary scope). offline_access is only an OAuth refresh capability and does not need to be held by the PAT. Browser login retains only user identity, credential scopes and expiry; it never retains the PAT secret or hash.
An admin PAT authorizing its own managed-user client also grants internal admin authority. An admin PAT authorizing another user's client delegates only ordinary scopes. admin is never a requestable OAuth scope, a client allowed_scopes entry, or part of the public token-response scope. Shared-key and project-share OAuth never inherit admin authority.
The grant is an independent credential after issuance: revoking or expiring the PAT, or changing its scopes, does not change the grant. Code exchange and refresh rotation preserve internal authority. Existing OAuth revocation and disabled-user checks still apply. Pre-upgrade grants default to no admin authority because their authorizing PAT authority was not recorded; no role or current PAT is used to guess it. Existing ChatGPT/NewWebCodex connections need one reauthorization using an admin PAT for its own managed client to acquire admin authority. Subsequent refreshes preserve it without another login until normal expiry or revocation.
Server configuration is in Deployment; MCP client setup is in MCP.
Authentication answers who the caller is. Scopes answer which classes of operation that caller may request. Project/path checks, Session guards, Runner capabilities, and the Server's authority mode remain separate checks.
A token having a scope does not bypass project boundaries or native safety checks. Conversely, knowing a Project/Session/Job identifier does not create the missing scope.
The Server's WEBCODEX_AUTHORITY_MODE is also separate from authentication.
trusted_agent auto-authorizes consequential operations after hard safety checks;
restricted denies them and does not create an approval queue. Invalid settings
fail closed. The mode does not change credential identity or scope membership,
and does not grant permission to publish or deploy outside the user's authorized
task. See Authority model for maintainer-level detail.
Computer Use permissions are intentionally separate from ordinary project/runtime access. Read-only Computer observation requires computer:read; effectful control requires computer:control; launching applications uses computer:launch. Full-display, pointer, and global clipboard operations have additional explicit scopes and are not silently inherited by older credentials.
OAuth clients receive these optional permissions only through explicit operator/user opt-in. The runtime still rechecks the current Runner capability and native OS permission at the moment of the call. See Computer Use for the product-facing feature overview.
Some compatibility-facing names remain because changing them would break stored configuration or wire compatibility:
wc_agent_*— Runner token;agent:<client_id>:<project_id>— runtime Project address;
These do not refer to WebCodex's separate Durable Agent / Conversation / Agent Task domain. Other process/protocol compatibility fields remain implementation details. New documentation should say Runner unless it is quoting one of the public compatibility-facing names above.
| Credential | Typical location |
|---|---|
WEBCODEX_TOKEN |
Server env file, commonly /etc/webcodex/webcodex.env |
| Managed user PAT | ~/.config/webcodex/<server-slug>/<user>/webcodex-user-token |
| Managed Runner token | inline in the matching runner.toml |
| Hosted shared key | protected hosted profile runner.toml |
| Project Credential | protected project-private state |
| OAuth client secret | returned at client creation; store it in the client/operator's secret store |
For command-specific setup and recovery paths, use CLI and Troubleshooting. Internal identity and continuity formats are intentionally omitted from this user-facing reference.