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

# Authentication

> CLI login flows, credential precedence, and session storage.

This page is the reference for how the `amika` CLI authenticates to the
hosted platform. For a task-oriented walkthrough, see the
[Manage secrets](https://docs.amika.dev/guides/manage-secrets.md) guide.

> [!NOTE]
>
> 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](https://docs.amika.dev/sdks/typescript/token-sources.md). The HTTP API takes an API key
> as a bearer token. See the [HTTP API overview](https://docs.amika.dev/reference/http-api-overview.md).

## Login modes

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

## Browser login

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

```bash theme={null}
# Log in (opens browser)
amika auth login

# Check login status
amika auth status

# Log out
amika auth logout
```

### How it works

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

## API key login

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](https://app.amika.dev/settings/api-keys) in the
**API Keys** section.

Or create one from the CLI with
[`amika auth api-key create`](https://docs.amika.dev/reference/cli#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.

```bash theme={null}
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):

```bash theme={null}
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`:

```bash theme={null}
# 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:

1. `AMIKA_API_KEY` environment variable
2. Stored API key file (`${XDG_STATE_HOME}/amika/api-key.json`)
3. 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](https://docs.amika.dev/guides/manage-secrets.md).

```bash theme={null}
# 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 |

## Related docs

* [Manage secrets](https://docs.amika.dev/guides/manage-secrets.md): push and inject credentials
* [Secrets reference](https://docs.amika.dev/reference/secrets.md): scope model and provider secrets
* [Storage paths](https://docs.amika.dev/reference/storage.md): where sessions and caches live


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.