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

# Authentication

> How API keys, environments, and profiles fit together in the Flexprice CLI

## One key, one environment

An API key belongs to exactly one environment. There is no `--environment` flag, because the key itself already determines it. Switching environments means switching **profiles**.

A profile bundles three things: a stored API key, the region it belongs to, and an optional label you choose.

<Warning>
  The API does not report which environment a key belongs to, so the CLI cannot tell you either. Label your profiles yourself with `--label`, and check with `flexprice whoami` before doing anything destructive.
</Warning>

## Getting set up

`flexprice init` is the guided path: it prompts for a region and key, verifies the key against the API, and stores it as the `default` profile.

```sh theme={null}
flexprice init
```

To add more environments later, use `login`:

```sh theme={null}
flexprice login --label "production"
```

## Working with multiple profiles

```sh theme={null}
flexprice config list                    # every stored profile
flexprice -p production customers list   # use one for a single command
flexprice config use production          # change the default
flexprice logout -p production           # remove a profile and its key
```

`flexprice env list` shows every environment in your tenant, which is useful for orientation — but remember it cannot tell you which one your active key maps to.

## Credential precedence

When more than one source could supply a key, the CLI resolves in this order and stops at the first match:

<Steps>
  <Step title="The --api-key flag">
    Highest precedence. Intended for CI and one-off commands.
  </Step>

  <Step title="The FLEXPRICE_API_KEY environment variable">
    Overrides any stored profile. The usual choice for CI, since it keeps the key out of your shell history and process list.
  </Step>

  <Step title="The stored profile">
    Either the one named by `-p/--profile`, or your default profile.
  </Step>
</Steps>

The API base URL resolves separately, on the same first-match basis: `--base-url`, then `--region`, then the region stored on the active profile.

<Note>
  A key on its own does not identify a region. If you pass `--api-key` without a stored profile, you must also pass `--region` or `--base-url` — otherwise the CLI stops and tells you so rather than guessing.
</Note>

## Where keys are stored

Keys go in your operating system's keychain when one is available. Where it is not — inside a container, or a CI runner — the CLI falls back to an encrypted file at `~/.flexprice/keys`.

`flexprice whoami` reports which backend is in use:

```sh theme={null}
flexprice whoami
```

```
Profile:      default
Label:        production
Region:       us
Base URL:     https://us.api.flexprice.io/v1
Key backend:  encrypted file (~/.flexprice/keys)
Key:          sk_test_…4b
```

Non-secret settings live in `~/.flexprice/config.toml`. **Keys are never written there.**

## In CI

Set the key through the environment and pin the region explicitly:

```sh theme={null}
export FLEXPRICE_API_KEY=sk_...
flexprice --region us customers list --output json
```

No `init` or `login` step is needed — the environment variable takes precedence over stored profiles, so nothing has to be configured on the runner.

## Next steps

<CardGroup cols={2}>
  <Card icon="flag" title="Global flags" href="/docs/cli/global-flags">
    Every flag the CLI accepts, grouped by purpose.
  </Card>

  <Card icon="code" title="Output & scripting" href="/docs/cli/output-and-scripting">
    Exit codes and non-interactive behaviour.
  </Card>
</CardGroup>