---
title: amp auth
description: "Reference for amp auth login, including agent-oriented start and poll, plus profile, token, status, and logout commands."
product: general
token_estimate: 1122
---
# amp auth

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

These commands authenticate `amp` and manage its stored credential profiles. For how profiles, regions, and credential precedence work conceptually, go to [Authentication](https://amplitude.com/docs/developers/cli/authentication).

## `amp auth login`

Authenticates through the interactive OAuth device flow and saves the result as a profile. Pass `--region us` or `--region eu` when you create a profile. Omit `--profile` to use the implicit `default` profile.

```bash
amp auth login --region us
```

A bare `amp auth login`, with no `--profile` or `--region`, re-authenticates the active profile against its recorded region.

| Flag | Purpose |
| --- | --- |
| `--region <us|eu>` | Select the region for a new profile |
| `--profile <name>` | Name the profile; defaults to `default` |
| `--force` | Retarget an existing profile without an interactive confirmation |

The CLI also accepts the development-oriented `--env` and `--base-url` options, but omits them from standard help. Go to [Configuration](https://amplitude.com/docs/developers/cli/configuration#base-url) for details.

## `amp auth login start`

Starts the device flow for an agent or script and always returns a JSON envelope. It records the pending authorization locally but doesn't expose the device code.

```bash
amp auth login start --region us --json
```

| Flag | Purpose |
| --- | --- |
| `--region <us|eu>` | Select the region for a new profile |
| `--profile <name>` | Name the profile; defaults to `default` |
| `--force` | Retarget an existing profile to the selected region |

The response includes a verification URL, user code, expiry, and the `login poll` command to run after the user approves the request.

## `amp auth login poll`

Checks the device flow that `login start` created. Each call waits up to 25 seconds by default.

```bash
amp auth login poll --json
amp auth login poll --timeout 0 --json
```

Use `--profile <name>` to poll a named profile and `--timeout <seconds>` to change the wait. A pending authorization returns `status: "pending"` and exit code `75`. An approved authorization saves the credential and returns `status: "authorized"`; expired and failed authorizations return error envelopes.

## `amp auth status`

Reports the active credential's type, base URL, and expiry, and announces when `AMP_TOKEN` is overriding profile selection.

```bash
amp auth status
amp auth status --json
```

## `amp auth use`

Switches the active profile without re-authenticating.

```bash
amp auth use default
```

## `amp auth list`

Lists stored profiles. An asterisk (`*`) marks the active one.

```bash
amp auth list
amp auth list --json
```

## `amp auth pat`

Saves a Personal Access Token as a profile instead of running the device flow. `--with-token` is mandatory: it makes the supply-an-existing-PAT path explicit and keeps the bare `amp auth pat` verb reserved. It reads the PAT from stdin when piped, or shows a masked prompt at a terminal.

```bash
echo "$PAT" | amp auth pat --with-token --profile ci --region us
```

| Flag | Purpose |
| --- | --- |
| `--with-token` | Required. Supply an existing PAT instead of running the device flow |
| `--region <us|eu>` | Select the region for a new profile |
| `--profile <name>` | Name the profile; defaults to `default` |
| `--force` | Retarget an existing profile to the selected region |

## `amp auth token`

Prints the active access token to stdout.

```bash
TOKEN=$(amp auth token)
```

## `amp logout`

Removes one stored profile, or every stored profile. Unlike the other commands on this page, `logout` is a top-level command, not a subcommand of `amp auth`.

```bash
amp logout --profile staging   # remove one profile
amp logout --profile staging --json
amp logout --all               # remove every profile
amp logout --all --yes         # remove every profile without a prompt
```

At a terminal, `amp logout --all` asks for confirmation. In a script or other non-interactive process, pass `--yes` or the command stops without deleting profiles. Logout also cancels a pending device login for the selected profile.

For credential precedence (`--token` > `AMP_TOKEN` > `--profile` > `AMP_PROFILE` > the active profile) and the scopes each command family needs, go to [Authentication](https://amplitude.com/docs/developers/cli/authentication).