> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codezero.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Tokens

> How Cordon authenticates local clients before injecting credentials.

Cordon can require a token for requests to configured route hosts. Full route matches still decide whether a request receives upstream credentials. This prevents an unrelated same-user process from connecting to the loopback proxy and receiving injected API credentials.

## How it works

* `tokens.toml` enables token enforcement for a scope.
* Authenticated proxy URLs use HTTP Basic proxy auth: `http://<audience>:<token>@127.0.0.1:<port>`.
* The Basic username is Cordon's local token audience: `user` for the user scope or a project namespace such as `myapp-a1b2c3d4`. This is not an OAuth/OIDC `aud` claim and does not provide third-party token attestation.
* Configured HTTP route hosts and CONNECT routes require a valid `Proxy-Authorization` token when enforcement is active. Path and method filters still decide whether an inner request receives injected credentials.
* Unmatched forwarding does not require a token, but malformed, duplicate, or invalid `Proxy-Authorization` is still rejected while enforcement is active.
* Missing `tokens.toml` preserves legacy behavior: configured route hosts remain unauthenticated and `cordon start` logs a warning.
* If a running daemon has already observed `tokens.toml`, deleting the file does not silently reopen token-protected route-host access. Restart Cordon without `tokens.toml` if you intentionally want legacy unauthenticated mode.

## Enable tokens

`cordon setup` creates tokens automatically — both base setup and integration setup (`cordon setup claude-code`, `cordon setup codex`, etc.) generate a `tokens.toml` with a default token. Integration setup additionally creates a client token and wires it into the tool's proxy URL.

The default token is the general-purpose proxy credential for a Cordon instance. Client tokens are named proxy credentials managed for configured clients such as Claude Code, Codex, Hermes, and OpenClaw. In the current token model, all valid tokens grant the same proxy access inside their local token audience; client tokens exist for independent rotation, revocation, setup/remove cleanup, and logging. Workload identity is verified separately.

For existing setups created before token enforcement, re-run setup:

```bash theme={null}
# Re-run for a specific integration
cordon setup claude-code --yes
cordon setup codex --yes
cordon setup hermes --yes

# Or base setup for standalone usage
cordon setup --yes
eval "$(cordon env --config ./cordon.toml)"
```

Setup output redacts tokenized URLs. `cordon env` is the command intended to print full authenticated values for shells, dotenv files, direnv, or mise.

Running daemons watch `tokens.toml` and pick up new, rotated, or revoked tokens on the next configured-route-host request. Restarting the daemon is still safe, but is not required for token-only changes.

## Rotate tokens

```bash theme={null}
cordon token rotate
cordon token rotate default
cordon token rotate claude-code
cordon token rotate --all
```

Omitting the token name rotates the default token. For supported clients (`claude-code`, `codex`, `hermes`, and `openclaw`), rotation updates the tool's tokenized proxy URL before writing the new token file. Restart any already-running tool process that inherited the old URL. The daemon picks up the new token file automatically.

## Revoke client tokens

```bash theme={null}
cordon token revoke codex
```

For supported clients, revoke removes matching tokenized proxy settings after removing the token from `tokens.toml`. The daemon picks up the revocation automatically.

## JSON output

`cordon env --format json` remains a flat object of environment variable names to string values. Existing scripts that read `.HTTPS_PROXY` or export every top-level entry continue to work; when token enforcement is active, proxy values include `<audience>:<token>@`.

## Handling tokenized URLs

Proxy tokens are not upstream API credentials, but they grant access to Cordon's token-protected route-host proxy path for that scope while the daemon is running. Path and method filters still decide whether any request receives injected credentials. Treat tokenized proxy URLs as sensitive local configuration:

* Do not commit token-bearing integration files.
* Do not paste tokenized URLs into issues, logs, or shared chat.
* Use `cordon token rotate <name>` if a tokenized URL is exposed.
* Use `cordon doctor` to verify token enforcement status.

Cordon setup refuses to write token-bearing files inside a Git repository unless both the final target and its atomic temp-file pattern are untracked and covered by `.gitignore`; merely untracked is not enough. For example, project Claude Code setup needs both `.claude/settings.local.json` and `.claude/.settings.json.tmp.*` ignored.

Audience binding prevents accidental cross-scope proxy mixups, such as a project token being presented to a user-scope daemon or another project's daemon. It does not bind the token to a process, working directory, binary, user session, OAuth/OIDC issuer, or remote verifier. A complete proxy URL remains a bearer credential for the matching local daemon until the token is rotated or revoked.