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

# Getting started

`anaconda-auth` is a client library and CLI for authenticating with Anaconda APIs and securely storing API keys. This package provides centralized authentication for the Anaconda ecosystem.

## Installation

```bash theme={null}
conda install anaconda-auth
```

## Basic usage

### Log in to Anaconda

This command opens your browser to authenticate your Anaconda account. Once completed, an API key is stored securely in your `/.anaconda/keyring`.

```bash theme={null}
anaconda auth login
```

### Check authentication status

This command displays information about the currently signed-in user.

```bash theme={null}
anaconda auth whoami
```

### Display your API key

This command prints the API key for the signed-in user (useful for non-interactive environments).

```bash theme={null}
anaconda auth api-key
```

### Logout

This command removes the stored API key from your keyring.

```bash theme={null}
anaconda auth logout
```

## Configuration

Configuration comes from multiple sources. When the same setting appears in more than one place, the highest-priority source wins:

1. `ANACONDA_AUTH_*` environment variables (highest priority)
2. `.env` file in the current working directory
3. Site settings (`[sites.<NAME>]`) in `/.anaconda/config.toml`
4. Global plugin settings (`[plugin.auth]`) in `/.anaconda/config.toml`
5. Conda context (proxy servers, SSL settings) from `.condarc`

### Site configuration

Use `anaconda sites add` to register the Anaconda domain you want to authenticate against:

```bash theme={null}
anaconda sites add --domain <FQDN> --default
```

Comments

Replace \<FQDN> with the fully qualified domain name (FQDN) you want to authenticate against.

This writes a `[sites]` entry to `.anaconda/config.toml` and sets it as the default site. To verify, run `anaconda sites list`. For the full list of site management commands, see [sites](https://anaconda.com/docs/cli-reference/anaconda-auth/commands/sites).

> [!NOTE]
>
> If you are using anaconda.com, no site configuration is needed.

All of the parameters in the table below can be set per-site in a `[sites.<name>]` section. When a parameter is not set on the site, the value from `[plugin.auth]` is used as a fallback. For more information on site configuration, see the [sites command reference](https://anaconda.com/docs/cli-reference/anaconda-auth/commands/sites).

### Global options

The `[plugin.auth]` section of `/.anaconda/config.toml` sets defaults that apply across all sites.

> [!TIP]
>
> Every parameter can also be set via an `ANACONDA_AUTH_` environment variable or a `.env` file.

Parameter

Environment Variable

Description

Default

`domain`

`ANACONDA_AUTH_DOMAIN`

Default domain when no site is configured. Use `anaconda sites add` to specify site.

`anaconda.com`

`ssl_verify`

`ANACONDA_AUTH_SSL_VERIFY`

Enable SSL verification for all requests

`True`

`api_key`

`ANACONDA_AUTH_API_KEY`

API key (overrides keyring lookup)

`None`

`preferred_token_storage`

`ANACONDA_AUTH_PREFERRED_TOKEN_STORAGE`

Where to store the login token. `anaconda-keyring` uses a file-based keyring at `/.anaconda/keyring`. `system` uses the OS keyring if available, falling back to `anaconda-keyring`.

`anaconda-keyring`

`extra_headers`

`ANACONDA_AUTH_EXTRA_HEADERS`

Extra request headers in JSON format

`None`

`use_device_flow`

`ANACONDA_AUTH_USE_DEVICE_FLOW`

Use the OAuth device code flow for login instead of a browser redirect

`False`

`use_unified_repo_api_key`

`ANACONDA_AUTH_USE_UNIFIED_REPO_API_KEY`

Use a unified API key for conda repository access instead of a separate repo token

`False`

`disable_conda_auto_config`

`ANACONDA_AUTH_DISABLE_CONDA_AUTO_CONFIG`

Disable automatic configuration of conda's `channel_settings` on login

`False`

### Example configuration

```toml theme={null}
# /.anaconda/config.toml
default_site = "my-platform"

[sites."my-platform"]
domain = "platform.example.com"
ssl_verify = false

[plugin.auth]
ssl_verify = true
preferred_token_storage = "anaconda-keyring"
```

In this example, SSL verification is disabled for the `my-platform` site but remains enabled as the default for any other site.

## Non-interactive usage

API keys issued by `anaconda auth login` are valid for one year. On systems without interactive browser access, there are several ways to authenticate:

> [tab] Environment variable
>
> 1. On a system with browser access, run `anaconda auth api-key` to get your API key.
> 2. On the non-interactive system, set the `ANACONDA_AUTH_API_KEY` environment variable (or add it to a `.env` file in your working directory).
>
> ```bash theme={null}
> export ANACONDA_AUTH_API_KEY=$(anaconda auth api-key)
> ```

> [tab] Copy the keyring file
>
> When `preferred_token_storage` is set to `anaconda-keyring` (the default), credentials are stored in `/.anaconda/keyring`. You can copy this file to another machine:
>
> 1. On a system with browser access, run `anaconda auth login`.
> 2. Copy `/.anaconda/keyring` to the same path on the target system.

> [tab] Device flow
>
> If the site supports it, configure the device code flow so that `login` displays a URL and code instead of opening a browser:
>
> ```bash theme={null}
> anaconda sites add --domain platform.example.com --use-device-flow --default
> anaconda auth login
> ```
>
> The CLI will print a verification URL and a one-time code. Open that URL on any device with a browser and enter the code. The login completes on the headless system.