# OpenAny Agent Authentication

This is the authentication and key-management summary for the latest published OpenAny CLI (Node.js **>=22**). Start with [AGENT.md](https://openany.si/AGENT.md); use [SKILL.md](https://openany.si/SKILL.md) for the full command reference and recovery rules.

Before guiding or executing authentication, you **must read** SKILL.md's **Missing Configuration: Required User Guidance** and **Interactive Configuration Walkthrough**. The local setup steps below are required guidance when settings are missing; listing variable names alone is insufficient.

The CLI uses **https://openany.si** for the service and signing domain and **https://api.openany.si** for the API gateway. These addresses are built in and cannot be overridden at runtime. Use CLI commands rather than guessing authentication endpoints.

## Choose the required access

- Model, data, and tool calls: only `OPENANY_API_KEY` or the current key saved in the CLI. Check with `openany status --scenario call -j`.
- Wallet login and key creation/rotation: `OPENANY_WALLET_ADDRESS`, `OPENANY_WALLET_PRIVATE_KEY` or an authorized signing tool, and a stable `OPENANY_AGENT_ID`. Check with `openany status --scenario wallet -j`.
- Email login and key management: `OPENANY_EMAIL` and authorized access to that mailbox. Check with `openany status --scenario email -j`; select the user's target workspace if several exist.
- Autonomous top-ups: API key, target identity, authorized payment wallet/signing capability, and user-approved network, limits, scope, and expiration. Complete login and record existing approval with `topups authorize`, then check with `openany status --scenario payment --identity wallet --scope TASK_SCOPE -j` (use email for email identity). Follow SKILL.md for the full workflow.

Use `--prepare` on configuration checks when using an external signer; a local private key is not required, but the signing tool must be available and authorized. A successful local check is not proof of working authentication or payment access. Inspect `configured` and `missing` from the relevant check. If local settings are missing, give the setup steps below and wait for completion; request only missing tools or authorization details. Missing `wallet_session` or `email_session` requires the corresponding authorized login flow below; missing `payment_policy` requires `topups authorize` with already approved limits, scope, network, and expiration. These are CLI-managed records, not external secrets to enter manually. After setup, repeat the payment check with the target identity and task scope before creating or paying for an order.

## Missing local configuration

If the user needs a new API key, ask them to choose wallet or email only if no method has been selected. Do not ask them to configure an API key they do not have. Reuse existing settings and authorization. If the CLI is missing or lacks `setup`, give the latest installation/update command from AGENT.md and check `openany --help`.

Give the applicable ordered walkthrough in the user's language:

1. Open the user's own terminal on the same machine/account where the CLI runs. For wallet setup, run `openany setup --scenario wallet`: enter the private key at the hidden prompt, review the automatically derived wallet address, then enter a stable Agent ID such as `agent-main` (6–128 letters, digits, dots, underscores, colons, or hyphens). No manual address entry is needed. For email setup, run `openany setup --scenario email` and enter only the email address, never a password or verification code.
2. Explain that setup saves to `~/.config/openany/credentials.json` or `OPENANY_CONFIG_DIR`, with directory 0700/file 0600 permissions. The file is not additionally encrypted. Do not open, print, edit, or upload it. Setup only saves configuration; it does not log in, send email, create keys, or authorize payments.
3. Explicitly warn: **Do not send API keys, wallet private keys, seed phrases, passwords, verification codes, access/refresh tokens, cookies, or credentials file contents in any AI/model conversation, including screenshots or attachments.** Enter private keys only in the hidden terminal prompt or use an already authorized secure secret-injection mechanism.
4. Ask the user to reply only that configuration is complete. Then run `openany status --scenario wallet -j` or `openany status --scenario email -j` in the agent's execution environment. Require `configured: true` and no missing settings before login. If settings are still missing, explain the names and check that the user and agent use the same execution environment and configuration directory. Nonempty environment variables override saved settings; never request their secret values.

Use interactive setup by default. Do not replace this walkthrough with instructions to export private keys or write secrets into `~/.zshrc`, other shell profiles, or `.env` files. Do not run a hidden-input wizard on the user's behalf or ask them to send its answers. Do not add `-j`, `--non-interactive`, or `--prepare` to the interactive setup command: those modes and execution without a TTY only check configuration and do not save it. If an external signer is already available and authorized, use the external-signing flow below instead of requesting a private key; setup does not configure external signers.

## Existing API key

Use only credentials the user supplied or explicitly designated. Never scan repositories, `.env*` files, user directories, or credential stores. Store private keys and API keys in secure credential settings; never put them in chat, command text, public documents, or logs.

`OPENANY_API_KEY` overrides the current local key. To save a key from a securely injected environment variable:

```bash
openany keys add --label main --activate
openany keys list -j
```

Without that variable, use hidden input in an interactive terminal, or `keys add --label main --activate --stdin` with controlled secret input for unattended use. Local credentials are stored in `~/.config/openany/credentials.json` or the directory set by `OPENANY_CONFIG_DIR`, with file permissions 0600 and directory permissions 0700. Do not print or upload this file. `keys list` exposes only metadata; `keys remove` removes only the local record.

## Wallet login and keys

If wallet settings are missing, first give the `openany setup --scenario wallet` walkthrough above. After the user confirms completion and the wallet status check passes, continue within the user's existing authorization:

Use `openany keys list -j` and the user's confirmed account/key information to select the flow. Check that existing key metadata or the user's confirmation associates the key with the configured wallet. An empty local list does not prove the wallet is unregistered; clarify unknown account/key history before creating a key.

**First-time wallet without a key:** create the key first, then log in:

```bash
openany keys create --identity wallet --label agent-main -j
openany auth wallet -j
```

The first successful key creation automatically registers the wallet account and shared balance account without a login session. Wait for the key to be saved before login. `auth wallet` itself does not register accounts. Registration is part of the authorized onboarding flow; do not ask again for authorization already given.

**Existing key for this wallet:** reuse it and run only:

```bash
openany auth wallet -j
```

Do not create or rotate a key just to log in. Keep the configured wallet and stable Agent ID. A login failure or generic 401 does not prove the wallet is unregistered. If creation returns a recovery file, recover the original result before login; resolve uncertain outcomes before creating again. Do not change the label or Agent ID to bypass an existing-key conflict.

Run each command only after the previous step succeeds. The created key is saved locally for subsequent CLI calls; report only metadata. `openany keys list -j` lists local labels and metadata, never the API key value. Do not ask the user to copy the generated key into chat. If registration, login, or key creation is not yet authorized, request only that missing authorization; setup completion alone is not authorization.

The CLI validates the signing message's service domain, identity, operation, and expiration before signing. Preserve the original message title and body. EVM private keys use 32 bytes with a `0x` prefix; Solana uses a Base58-encoded 64-byte secret key. The CLI checks that the address matches the private key. Keep the user- or runtime-supplied agent ID stable.

For external signing, add `--prepare` to the wallet authentication or key command, sign with an authorized tool, and submit using the same command with `--challenge-id ID --signature-file FILE`. The file must contain the raw signature text corresponding to that challenge. Do not modify the message or switch service domains if validation fails.

Rotation uses `openany keys rotate --identity wallet --label agent-next --expected-key-id CURRENT_KEY_ID -j` and invalidates the old key. Obtain explicit authorization, identify affected applications, and prepare to update their secrets. Update any old `OPENANY_API_KEY` environment value as well, since it overrides the newly saved key. Verify the state before retrying an unclear outcome.

## Email login and keys

If the email address is missing, first guide `openany setup --scenario email` as described above. Use the authorized mailbox connection to obtain the current six-digit code, retaining leading zeros. The CLI does not require an email password. If the mailbox connection is unavailable, ask the user to connect an authorized mailbox tool or run the following send/verify commands in their own terminal, replacing the code placeholder locally. Never ask them to send the code or mailbox password into chat; ask only for confirmation that login is complete. Avoid repeatedly sending codes.

```bash
openany auth email send -j
openany auth email verify --code SIX_DIGITS -j
```

A single workspace is selected automatically. If several exist, select the user's authorized target using `openany auth email workspace --workspace WORKSPACE_ID -j`; relevant commands also accept `--workspace ID`. The CLI saves login state but does not automatically refresh it. Explicitly run `openany auth email refresh -j` for an expired session. If refresh is denied, log in again through the authorized mailbox. If the outcome is uncertain or a recovery file is returned, follow the recovery instructions before retrying. Email-session refresh does not replace or repair an API key.

Use `keys remote list --limit 100 --offset 0 -j`, `keys remote create --label NAME -j`, `keys remote get --id KEY_ID -j`, and `keys remote revoke --id KEY_ID -j` through `openany`. To replace an email-based key: create a new key, update applications, verify it, then revoke the specified old key within the user's authorization. Keep the old key until verification succeeds.

## Verification, recovery, and payment boundaries

- After configuration, `openany balance -j` checks the current key's ability to access the balance. It does not verify wallet signing, mailbox connectivity, or payment authorization.
- On an API-key 401, pause and ask the user to check the key; on an email-session 401, use the explicit refresh flow above. Retain the original authentication method and service URL. Do not send invalid keys as a test. Service availability also depends on deployment configuration; a disabled or unavailable authentication endpoint is not proof of a bad credential.
- If a remote login or key operation succeeds but local saving fails, use `openany auth recover --file RETURNED_PATH` with the verified recovery file instead of creating duplicate keys. Do not print its contents or automatically delete configuration locks.
- Report actual outcomes and retain error codes and request IDs without secrets. A sent email, signing prompt, installed skill, or successful local configuration check is not verified login.
- Authentication does not authorize spending. The authorized agent policy triggers below 5 USD available balance and uses `--amount-usd 10`; exactly 5 USD does not trigger it. Actual payment, fees, and net credit follow the locked quote, within approved limits. This policy is executed by the agent, not by a CLI background monitor. Follow the explicit top-up authorization and `topups authorize/create/pay/get` workflow in SKILL.md. After a submitted or uncertain payment, check status only; never repeat payment. Report funds credited only when `paymentStatus=paid` and `creditStatus=credited` are confirmed, plus `accountUsable=true` for wallet identity.