Authentication

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

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

   Copy

   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

   Copy

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

A request whose token lacks a required scope returns a 403 error. For the shared error format, refer to 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.

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:

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:

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:

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:

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.

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:

For the full per-subcommand reference, including split login, status, use, list, pat, token, and logout, go to the auth command reference.