> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

# Authentication

Agdi supports OAuth and API keys for model providers. For always-on gateway
hosts, API keys are usually the most predictable option. Subscription/OAuth
flows are also supported when they match your provider account model.

See [/concepts/oauth](https://agdiai-597e782f.mintlify.site/concepts/oauth.md) for the full OAuth flow and storage
layout.
For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](https://agdiai-597e782f.mintlify.site/gateway/secrets.md).
For credential eligibility/reason-code rules used by `models status --probe`, see
[Auth Credential Semantics](https://agdiai-597e782f.mintlify.site/auth-credential-semantics.md).

## Recommended setup (API key, any provider)

If you’re running a long-lived gateway, start with an API key for your chosen
provider.
For Anthropic specifically, API key auth is the safe path and is recommended
over subscription setup-token auth.

1. Create an API key in your provider console.
2. Put it on the **gateway host** (the machine running `agdi gateway`).

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export <PROVIDER>_API_KEY="..."
agdi models status
```

3. If the Gateway runs under systemd/launchd, prefer putting the key in
   `~/.agdi/.env` so the daemon can read it:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cat >> ~/.agdi/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF
```

Then restart the daemon (or restart your Gateway process) and re-check:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models status
agdi doctor
```

If you’d rather not manage env vars yourself, onboarding can store
API keys for daemon use: `agdi onboard`.

See [Help](https://agdiai-597e782f.mintlify.site/help.md) for details on env inheritance (`env.shellEnv`,
`~/.agdi/.env`, systemd/launchd).

## Anthropic: setup-token (subscription auth)

If you’re using a Claude subscription, the setup-token flow is supported. Run
it on the **gateway host**:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
claude setup-token
```

Then paste it into Agdi:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models auth setup-token --provider anthropic
```

If the token was created on another machine, paste it manually:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models auth paste-token --provider anthropic
```

If you see an Anthropic error like:

```
This credential is only authorized for use with Claude Code and cannot be used for other API requests.
```

…use an Anthropic API key instead.

> [!WARNING]
>
> Anthropic setup-token support is technical compatibility only. Anthropic has blocked
> some subscription usage outside Claude Code in the past. Use it only if you decide
> the policy risk is acceptable, and verify Anthropic's current terms yourself.

Manual token entry (any provider; writes `auth-profiles.json` + updates config):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models auth paste-token --provider anthropic
agdi models auth paste-token --provider openrouter
```

Auth profile refs are also supported for static credentials:

* `api_key` credentials can use `keyRef: { source, provider, id }`
* `token` credentials can use `tokenRef: { source, provider, id }`

Automation-friendly check (exit `1` when expired/missing, `2` when expiring):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models status --check
```

Optional ops scripts (systemd/Termux) are documented here:
[/automation/auth-monitoring](https://agdiai-597e782f.mintlify.site/automation/auth-monitoring.md)

> `claude setup-token` requires an interactive TTY.

## Checking model auth status

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models status
agdi doctor
```

## API key rotation behavior (gateway)

Some providers support retrying a request with alternative keys when an API call
hits a provider rate limit.

* Priority order:
  * `OPENCLAW_LIVE_<PROVIDER>_KEY` (single override)
  * `<PROVIDER>_API_KEYS`
  * `<PROVIDER>_API_KEY`
  * `<PROVIDER>_API_KEY_*`
* Google providers also include `GOOGLE_API_KEY` as an additional fallback.
* The same key list is deduplicated before use.
* Agdi retries with the next key only for rate-limit errors (for example
  `429`, `rate_limit`, `quota`, `resource exhausted`).
* Non-rate-limit errors are not retried with alternate keys.
* If all keys fail, the final error from the last attempt is returned.

## Controlling which credential is used

### Per-session (chat command)

Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).

Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).

### Per-agent (CLI override)

Set an explicit auth profile order override for an agent (stored in that agent’s `auth-profiles.json`):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models auth order get --provider anthropic
agdi models auth order set --provider anthropic anthropic:default
agdi models auth order clear --provider anthropic
```

Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.

## Troubleshooting

### "No credentials found"

If the Anthropic token profile is missing, run `claude setup-token` on the
**gateway host**, then re-check:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi models status
```

### Token expiring/expired

Run `agdi models status` to confirm which profile is expiring. If the profile
is missing, rerun `claude setup-token` and paste the token again.

## Requirements

* Anthropic subscription account (for `claude setup-token`)
* Claude Code CLI installed (`claude` command available)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.