Authentication

This page is the reference for how the amika CLI authenticates to the hosted platform. For a task-oriented walkthrough, see the Manage secrets guide.

The TypeScript SDK does not use any of the stored credentials below. It requires you to pass an apiKey, an accessToken, or a tokenSource. See Token sources. The HTTP API takes an API key as a bearer token. See the HTTP API overview.

amika auth login has two modes:

Browser login: interactive device authorization flow. Best for local development.
API key login: non-interactive, for CI and automation.

The default amika auth login authenticates with Amika using a device authorization flow.

# Log in (opens browser)
amika auth login

# Check login status
amika auth status

# Log out
amika auth logout

How it works

The CLI requests a device code from Amika.
A user code is displayed and the browser opens for you to authorize.
The CLI polls Amika until you complete authorization.
The session (access token, refresh token, email, org) is saved to ${XDG_STATE_HOME}/amika/workos-session.json.
Access tokens are automatically refreshed when within 60 seconds of expiry.

Use an Amika API key when you need to authenticate without a browser, for example from CI jobs or automated scripts.

Create a key

Generate API keys in the web UI at app.amika.dev/settings/api-keys in the API Keys section. Or create one from the CLI with amika auth api-key create. It writes the key to a file and never prints it. This command ships in the next CLI release, so use the web UI until then.

amika auth api-key create --name ci --out ./amika-key
amika auth login --api-key-file ./amika-key

Keys are scoped to your organization by default. Pass --scope user for a key that acts as you.

Use the key

Environment variable (highest priority):

export AMIKA_API_KEY=<key>
amika auth status

When AMIKA_API_KEY is set, it overrides any stored API key or browser session. Good for ephemeral CI runs. Store on disk with amika auth login --api-key-file:

# From a file
amika auth login --api-key-file ./key.txt

# From stdin, which pairs well with secret managers
vault kv get -field=key secret/amika | amika auth login --api-key-file -

The key is written to ${XDG_STATE_HOME}/amika/api-key.json with 0600 permissions.

Credential precedence

When multiple credentials are present, amika picks the first one that is set, in this order:

AMIKA_API_KEY environment variable
Stored API key file (${XDG_STATE_HOME}/amika/api-key.json)
Browser login session (${XDG_STATE_HOME}/amika/workos-session.json)

amika auth status prints the active source and warns if a lower-priority credential is being shadowed. amika auth logout clears both the stored API key and the browser session.

Local credential discovery

amika secret extract discovers API credentials that coding agent tools store on your machine, shows them masked, and with --push uploads them to the Amika secrets store. See Manage secrets.

# Show detected credentials
amika secret extract

# Push them to the secrets store after confirmation
amika secret extract --push

# Skip OAuth sources
amika secret extract --no-oauth

Supported sources

Amika reads sources in priority order. Higher-priority sources win when multiple files provide the same provider key.

Priority	Source	Files	Providers
500	Claude API key	`~/.claude.json.api`, `~/.claude.json`	Anthropic
400	Claude OAuth	`~/.claude/.credentials.json`, `~/.claude-oauth-credentials.json`	Anthropic
300	Codex	`~/.codex/auth.json`	OpenAI
290	Amika env cache	`${XDG_CACHE_HOME}/amika/env-cache.json`	Any
280	Amika keychain	`${XDG_DATA_HOME}/amika/keychain.json`	Any
270	Amika OAuth	`${XDG_STATE_HOME}/amika/oauth.json`	Any
200	OpenCode	`~/.local/share/opencode/auth.json`	Any
100	Amp	`~/.amp/config.json`	Anthropic

Secret names

Amika normalizes provider names and uses common aliases as secret names:

Anthropic keys become both ANTHROPIC_API_KEY and CLAUDE_API_KEY.
OpenAI keys become both OPENAI_API_KEY and CODEX_API_KEY.

Provider names are canonicalized before deduplication: claude and anthropic become anthropic, codex and openai become openai, and other providers are lowercased with separators normalized to hyphens. OAuth tokens with an expiresAt or expires timestamp are skipped if expired.

`secret extract` flags

Flag	Default	Description
`--push`	`false`	Push discovered secrets to the remote store after confirmation
`--only <keys>`		Comma-separated list of secret names to include
`--scope <scope>`	`user`	Secret scope for pushed secrets: `user` or `org`
`--homedir <path>`	`$HOME`	Override home directory for discovery
`--no-oauth`	`false`	Skip OAuth credential sources

Environment variables

Variable	Default	Description
`AMIKA_API_KEY`		Amika API key used to authenticate CLI requests. Overrides any stored API key or browser session when set
`AMIKA_API_URL`	`https://app.amika.dev`	Override the remote API base URL.
`AMIKA_WORKOS_CLIENT_ID`		Override the default WorkOS client ID. If you change `AMIKA_API_URL`, you likely need to update this too

Manage secrets: push and inject credentials
Secrets reference: scope model and provider secrets
Storage paths: where sessions and caches live

CLI and platform

Repository configuration

HTTP API

Authentication

How it works

Create a key

Use the key

Credential precedence

Local credential discovery

Supported sources

Secret names

`secret extract` flags

Environment variables

​Login modes

​Browser login

​How it works

​API key login

​Create a key

​Use the key

​Credential precedence

​Local credential discovery

​Supported sources

​Secret names

​secret extract flags

​Environment variables

​Related docs

Login modes

Browser login

How it works

API key login

Create a key

Use the key

Credential precedence

Local credential discovery

Supported sources

Secret names

`secret extract` flags

Environment variables

Related docs