---
title: Authentication
description: "Authenticate the amp CLI with the OAuth device flow or a Personal Access Token, using region-scoped profiles."
product: general
token_estimate: 2051
---
# Authentication

> 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`.

Most Developer API requests require an HTTP `Bearer` token. Send it in the `Authorization` header:

```bash
Authorization: Bearer YOUR_ACCESS_TOKEN
```

A Bearer token is either an OAuth access token from the device flow or a Personal Access Token (PAT). Both use the same header and scope model, and either can call the endpoints its scopes allow. The device authorization, token exchange, and skills endpoints don't require a Bearer token.

Call [Get authenticated context](https://amplitude.com/docs/apis/developer/projects/get-authenticated-context) to check which credential type, scopes, and organization a token resolves to. Its `principal.auth_type` field returns `oauth`, `pat`, `service_account`, or `api_key`.

### OAuth device flow

Use the device flow to authorize a CLI, script, or other input-constrained client without embedding a client secret. The flow has two steps: start a device authorization request, then poll for a token.

1. **Start a device authorization request.** Send the space-delimited `scope` you need to the device-authorization endpoint. This endpoint doesn't require a Bearer token.

   ```bash
   curl -X POST https://developer-api.amplitude.com/v1/auth/device-authorization \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "projects:read analytics:read"
     }'
   ```

   The response includes `device_code`, `user_code`, `verification_uri` (and `verification_uri_complete`), `expires_in`, and a polling `interval`.
2. **Direct the user to approve the request.** Show the `user_code` and send the user to `verification_uri` (or open `verification_uri_complete` directly), where they approve the request in the browser.
3. **Poll for a token.** While the user approves the request, poll the token endpoint with the `device_code` grant:

   ```bash
   curl -X POST https://developer-api.amplitude.com/v1/auth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
       "device_code": "YOUR_DEVICE_CODE"
     }'
   ```

   Poll no more often than the `interval` from step 1. Once the user approves the request, the token endpoint returns `access_token`, `token_type`, `expires_in`, `refresh_token`, `scope`, and `id_token`. Send `access_token` as the Bearer token on subsequent requests.

### Personal access tokens

A Personal Access Token (PAT) is a long-lived Bearer credential for CI pipelines and other non-interactive environments where running the device flow isn't practical. Send a PAT in the `Authorization` header the same way as an OAuth access token. The [amp CLI](https://amplitude.com/docs/developers/cli) accepts an existing PAT non-interactively (for example, `amp auth pat --with-token`) as an alternative to `amp auth login`.

### Scopes

Request only the scopes an integration needs. The device-authorization request's `scope` field takes a space-delimited list; a PAT carries its own fixed set of scopes. `GET /v1/context` reports the active token's granted scopes in `principal.scopes`.

| Scope | Grants |
| --- | --- |
| `projects:read` | List projects and read the authenticated context. |
| `taxonomy:read` | Read event, event-property, and user-property taxonomy. |
| `taxonomy:write` | Create, update, and delete taxonomy entries. |
| `analytics:read` | List, get, and query saved charts. |
| `flags:read` | Read feature flag configuration. |
| `flags:write` | Create, update, and archive feature flags. |
| `destinations:read` | List and read event-streaming destinations. |
| `destinations:write` | Create and update event-streaming destinations. |

A request whose token lacks a required scope returns a `403` error. For the shared error format, refer to [Conventions](https://amplitude.com/docs/apis/developer#conventions).

## Profiles and regions

Run `amp auth login` to authenticate through the OAuth device flow. Choose the US or EU region when you create a profile. The profile name is optional and defaults to `default`.

```bash
amp auth login --region us                       # save and activate "default"
amp auth status                                  # active credential, type, base URL, expiry
amp context
```

A profile binds a credential to a region and its base URL, so `amp` doesn't send an EU profile's token to the US API. Add named profiles and switch between them without re-authenticating:

```bash
amp auth login --profile eu --region eu          # save and activate "eu"
amp auth use default                              # switch back (no re-auth)
amp auth list                                     # * marks the active profile
amp logout --profile eu                           # remove one profile
amp logout --all                                   # remove every profile
```

A bare `amp auth login`, with no `--profile` or `--region`, re-authenticates the active profile against its recorded region. If you change an existing profile's region, `amp` asks for confirmation in an interactive terminal. Pass `--force` to approve that change in a script.

`amp` saves profiles to `~/.amplitude/amp/credentials.json` with `0600` permissions.

### Personal access tokens

Prefer a Personal Access Token (PAT) over the device flow? `amp auth pat --with-token` reads a PAT from stdin (or a masked prompt at a terminal) and saves it as a profile, using the same force-explicit create rule and the same credential store as `login`:

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

`--with-token` is mandatory. It makes the supply-an-existing-PAT path explicit and keeps the bare `amp auth pat` verb reserved.

### Authenticate from an agent or script

Split the OAuth device flow into two commands when an agent or script can't hold one interactive process open:

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

`login start` returns a JSON envelope with the verification URL, user code, expiry, and the poll command. It stores the device code locally instead of printing it. After the user approves the request, `login poll` saves the credential and returns `authorized`.

Each poll waits up to 25 seconds by default. Use `--timeout <seconds>` to change the wait or `--timeout 0` to check once. A pending authorization returns a JSON envelope with `status: "pending"` and exit code `75`, so a caller can wait and retry. Expired and failed authorizations return error envelopes.

To print the active access token, for example to capture it in a variable:

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

## Credential selection precedence

`amp` resolves a credential from several possible sources. Highest precedence first:

1. `--token` flag
2. `AMP_TOKEN` environment variable
3. `--profile` flag
4. `AMP_PROFILE` environment variable
5. The active (default) profile

`AMP_TOKEN` outranks profile selection, so a stray stored profile can't shadow a CI-injected token. `amp auth status` announces when `AMP_TOKEN` is in effect.

```bash
export AMP_TOKEN=amp_...        # one-off / CI; overrides stored profiles
export AMP_PROFILE=staging      # select a stored profile by name
```

`--token` and `AMP_TOKEN` each accept:

- A raw PAT: `amp_...`. `amp` normalizes it to `Bearer PAT=amp_...`.
- A prefixed PAT: `PAT=amp_...`.
- A full bearer value: `Bearer PAT=amp_...` (or any `Bearer <jwt>`).

## Required scopes

`amp auth login` requests every scope the CLI can use by default, so all commands work immediately after login. If you authenticate with a narrowly-scoped PAT instead, match it to the command families you need:

| Command family | Scopes |
| --- | --- |
| `context`, `projects list` | `projects:read` |
| `events *`, property commands | `taxonomy:read`, `taxonomy:write` |
| `flags *` | `flags:read`, `flags:write` |
| `charts *` | `analytics:read` |

For the full per-subcommand reference, including split login, `status`, `use`, `list`, `pat`, `token`, and `logout`, go to the [`auth` command reference](https://amplitude.com/docs/developers/cli/commands/auth).