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

# Provider Authentication

# Provider authentication

Fased supports OAuth and API keys for model providers. For Anthropic
accounts, we recommend using an **API key**. For Claude subscription access,
use the long‑lived token created by `claude setup-token`.

<Note>
  This page covers model-provider authentication. Gateway and Control UI login
  are separate: use `gateway.auth` for the Gateway token/password/trusted-proxy
  mode, and see [Gateway security](/gateway/security) for page and API protection.
</Note>

For normal browser setup, open the selected Agent and use **Agent > Models**.
That page owns provider sign-in, API-key entry, per-Agent model roles, and model
selection. The CLI commands below are for automation, repair, or advanced setup
workflows.

See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
layout.
For SecretRef-based auth (`env`/`file`/`exec` providers), see
[Secrets Management](/gateway/secrets).

## Recommended Anthropic setup (API key)

If you’re using Anthropic directly, use an API key.

1. Create an API key in the Anthropic Console.
2. Put it on the **gateway host** (the machine running `fased gateway`).

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export ANTHROPIC_API_KEY="..."
fased models status
```

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

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

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

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

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

The Control UI can also store provider credentials from **Agent > Models**.

See [Help](/help) for details on env inheritance (`env.shellEnv`,
`~/.fased/.env`, systemd/launchd).

## Anthropic: setup-token (subscription auth)

For Anthropic, the recommended path is an **API key**. If you’re using a Claude
subscription, the setup-token flow is also supported. Generate the token in an
interactive terminal:

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

Then paste it into Fased on the gateway host:

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

If the token was copied from another machine or automation flow, paste it
manually:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased 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.

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased models auth paste-token --provider anthropic
fased 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"}}
fased models status --check
```

Optional ops scripts (systemd/Termux) are documented here:
[/automation/auth-monitoring](/automation/auth-monitoring)

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

## Checking model auth status

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased models status
fased 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:
  * `FASED_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.
* Fased 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` and
`anthropic:work`.

Use `/model` or `/model list` for a compact picker. Use `/model status` for the
full view: candidates, next auth profile, and provider endpoint details when
configured.

### Per-agent (CLI override)

Set an explicit auth profile order override for an agent. Fased stores it in that
agent's `auth-profiles.json`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased models auth order get --provider anthropic
fased models auth order set --provider anthropic anthropic:default
fased 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"}}
fased models status
```

### Token expiring/expired

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

## Requirements for setup-token

* Claude Max or Pro subscription (for `claude setup-token`)
* Claude Code CLI installed (`claude` command available)