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

# Sign-ins and API keys

Most providers connect with either a sign-in or an API key. Do it once and the provider's models
appear in the model picker for every project.

## Sign in with a subscription

ChatGPT Plus or Pro, GitHub Copilot and SuperGrok work without an API key.

```sh
haarness auth login openai           # ChatGPT, in your browser
haarness auth login github-copilot   # GitHub, with a device code
haarness auth login xai              # SuperGrok, with a device code
```

The browser opens and, for GitHub and xAI, Haarness shows a code to enter. When you finish, the
terminal says you are connected. Sign-ins renew themselves.

On a machine without a browser, such as over SSH, add `--method headless`. Haarness prints a link
and a code to use on any other device. In the terminal UI and Desktop this is
**Sign in with a code**.

In the terminal UI, `/connect` offers the same choices; in Desktop, use
**Settings → Providers → Connect a provider**. Both also work when you are connected to a remote
Haarness server; the sign-in is then kept on that server.

## Use an API key

```sh
haarness auth set anthropic
```

Paste the key at the hidden prompt. You see `Stored anthropic credential in owner-only auth.json`.

In the terminal UI (`/connect`) and in Desktop, Haarness asks the provider about a new key before
it saves it:

- **A key the provider refuses is not saved.** The error names the provider and gives its reason,
  for example `Anthropic rejected this API key (invalid x-api-key)`. Check that you copied all of
  it.
- **If the provider cannot be reached,** the key is saved with a warning that it could not be
  checked. Replace it if chats then fail to sign in.

`haarness auth set` saves the key without checking it.

Or set the provider's environment variable before you start Haarness:

| Provider | Id | Environment variable |
| --- | --- | --- |
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
| Google Gemini | `gemini` | `GOOGLE_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_GENERATIVE_AI_API_KEY` |
| GitHub Copilot | `github-copilot` | `GITHUB_COPILOT_TOKEN`, `GH_TOKEN` or `GITHUB_TOKEN` |
| xAI | `xai` | `XAI_API_KEY` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
| Groq | `groq` | `GROQ_API_KEY` |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
| Mistral | `mistral` | `MISTRAL_API_KEY` |

For GitHub Copilot, a key is a GitHub personal access token with Copilot access. Every other
built-in provider is in [All built-in providers](https://haarness.ai/docs/providers/native-providers.md#all-built-in-providers);
`/connect` in the terminal UI also shows each one's variable and where to get a key.

## Use Azure OpenAI, Google Vertex AI or Amazon Bedrock

These use your cloud account's own credentials. Tell Haarness where your account is, then give it
a credential; the first one found is used.

**Azure OpenAI** (`azure`)

- Where: `AZURE_RESOURCE_NAME`, or the full `AZURE_OPENAI_BASE_URL`.
- Credential: `AZURE_OPENAI_API_KEY` (or `AZURE_API_KEY`), then a key stored with
  `haarness auth set azure`, then `az login`.

**Google Vertex AI** (`google-vertex`)

- Where: `GOOGLE_VERTEX_PROJECT` (or `GOOGLE_CLOUD_PROJECT`), and `GOOGLE_VERTEX_LOCATION` if not
  `us-central1`.
- Credential: `GOOGLE_OAUTH_ACCESS_TOKEN` (or `GOOGLE_ACCESS_TOKEN`), then a token stored with
  `haarness auth set google-vertex`, then `gcloud`.

**Amazon Bedrock** (`amazon-bedrock`)

- Where: `AWS_REGION` (or `AWS_DEFAULT_REGION`), if not `us-east-1`.
- Credential: a Bedrock API key in `AWS_BEARER_TOKEN_BEDROCK` or stored with
  `haarness auth set amazon-bedrock`, then `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (with
  `AWS_SESSION_TOKEN` if you have one), then the `AWS_PROFILE` in your shared credentials file.

Haarness falls back to `az` or `gcloud` only when it sends a request. Azure and Vertex then show
as not connected, and the model pickers do not offer them, so set a key or token if you want to
pick their models in the apps.

Haarness never contacts cloud metadata endpoints on its own. For SSO, instance roles or role
assumption, use a tool that exports credentials into the environment.

Each platform starts with two example models. To use your own Azure deployments, other Vertex
models or other Bedrock model ids, add them as a
[custom provider](https://haarness.ai/docs/providers/custom-providers.md#use-your-own-azure-deployments-or-bedrock-models).

## Which credential is used

- **An environment variable wins over a stored key or sign-in.** If `OPENAI_API_KEY` is set,
  Haarness uses it even when you signed in with ChatGPT. Unset it to use your subscription.
- **Environment variables are read when the Haarness server starts.** Haarness starts one in the
  background the first time you use a project. If you set a variable later, stop that server with
  `haarness serve --stop` (this interrupts running work) and start Haarness again.
- **Desktop opened from the Dock or an app launcher** usually does not see variables exported in
  your shell profile. Store the key with `haarness auth set` or in Desktop instead.
- **Stored keys and sign-ins apply at once.** `auth set`, `auth login` and `auth logout` take
  effect in a running server without a restart.

## See, change or remove credentials

```sh
haarness auth list              # stored credentials and their kind
haarness providers              # every provider and whether it is connected
haarness auth logout anthropic  # remove a stored credential
```

Stored credentials live in an owner-only `auth.json` in your Haarness data folder, never in project
configuration. They stay on the machine that runs the Haarness server. Who else can read them is in
[Data and storage](https://haarness.ai/docs/security/data-and-storage.md#who-can-read-my-keys).

## Troubleshooting

**`haarness models` lists a model but the app does not.** The command checks with your current
shell's environment, while the app uses the server's. See the second point under
[Which credential is used](https://haarness.ai/docs/providers/native-providers.md#which-credential-is-used).

**"is not available on this ChatGPT account".** Your plan does not include that model. The error
lists the ones it does; pick one of those, or connect an OpenAI API key instead.

**"rejected this API key".** The provider refused the key you pasted, and nothing was saved. Copy
the whole key again; some providers show it only once, so create a new one if you need to.

## All built-in providers

Every provider here connects with an API key, stored with `haarness auth set ID` or read from its
environment variable.

| Provider | Id | Environment variable |
| --- | --- | --- |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` |
| Chutes | `chutes` | `CHUTES_API_KEY` |
| DeepInfra | `deepinfra` | `DEEPINFRA_TOKEN` or `DEEPINFRA_API_KEY` |
| DigitalOcean Gradient AI | `digitalocean` | `DIGITALOCEAN_ACCESS_TOKEN` |
| Fireworks AI | `fireworks-ai` | `FIREWORKS_API_KEY` |
| Hugging Face Inference | `huggingface` | `HF_TOKEN` |
| Llama API | `llama` | `LLAMA_API_KEY` |
| ModelScope | `modelscope` | `MODELSCOPE_API_KEY` |
| Moonshot AI | `moonshotai` | `MOONSHOT_API_KEY` |
| Nebius Token Factory | `nebius` | `NEBIUS_API_KEY` |
| NovitaAI | `novita-ai` | `NOVITA_API_KEY` |
| NVIDIA NIM | `nvidia` | `NVIDIA_API_KEY` |
| Ollama Cloud | `ollama-cloud` | `OLLAMA_API_KEY` |
| Perplexity Sonar | `perplexity` | `PERPLEXITY_API_KEY` |
| Requesty | `requesty` | `REQUESTY_API_KEY` |
| SambaNova | `sambanova` | `SAMBANOVA_API_KEY` |
| SiliconFlow | `siliconflow` | `SILICONFLOW_API_KEY` |
| SiliconFlow (China) | `siliconflow-cn` | `SILICONFLOW_CN_API_KEY` |
| Together AI | `togetherai` | `TOGETHER_API_KEY` |
| Upstage | `upstage` | `UPSTAGE_API_KEY` |
| Weights & Biases | `wandb` | `WANDB_API_KEY` |
| Z.AI | `zai` | `ZAI_API_KEY` or `ZHIPU_API_KEY` |

Ollama and LM Studio on your own computer need no key; see
[Local models](https://haarness.ai/docs/providers/custom-providers.md#ollama-and-lm-studio).

## Next

- [Local models and custom endpoints](https://haarness.ai/docs/providers/custom-providers.md)
- [Haarness Cloud models](https://haarness.ai/docs/cloud/models-and-routers.md) — no provider account needed