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

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# unkey login

> Sign in from the terminal and store a CLI session with the permissions you select.

`unkey login` starts a device login. You confirm the code in the dashboard, narrow the permissions if you want, and the CLI stores a session. Humans use `unkey login`. CI uses a root key.

`unkey auth login` runs the same command.

## Usage

```bash theme={"system"}
unkey login
```

The command prints a confirmation code and a URL, then opens that URL in your browser. Sign in, check that the code matches the terminal, and select the permissions this key should have. Click **Allow**. The CLI finishes from that approval.

The approval page shows the device name, the IP address and client that started the login, and when it started. Only allow a login you started yourself. Anyone who gets you to approve their code receives a CLI session, so deny any code that someone sent you.

The CLI keeps polling until the login finishes. On success it stores one session for that workspace and prints where it was saved. It does not print the tokens. `unkey logout` revokes the session. `unkey workspace switch` changes the active workspace.

A denied or expired login stops with the reason. Run `unkey login` again to start over.

The CLI retries network errors and server errors while it waits. If the CLI receives a session but cannot store it, it revokes that session on the server and exits with an error. Run `unkey login` again once the keychain or `~/.unkey` is writable.

Starting and polling logins is rate limited per IP address. When you hit the limit, the API answers [ip\_rate\_limited](https://www.unkey.com/docs/errors/user/too_many_requests/ip_rate_limited.md).

## Flags

**--api-url** `string`

API origin to call. Falls back to `UNKEY_API_BASE_URL`. Defaults to `https://api.unkey.com`.

**--no-browser** `boolean`

Print the verification URL and do not open a browser.

**--root-key** `string`

Store a root key and skip the browser. Pass `-` to read the key from stdin, with a hidden prompt when stdin is a terminal, so the key stays out of your shell history and process list. The command does not check the key with the API, and it does not read `UNKEY_ROOT_KEY`.

## Where the key is stored

The root key goes in the operating system secret store:

* macOS Keychain, as a generic password with service `unkey` and account `root_key`
* Windows Credential Manager, as a generic credential named `unkey/root_key`
* Linux Secret Service, through `secret-tool`, with attributes `service=unkey` and `account=root_key`

On macOS, the CLI passes the key to the `security` tool on stdin, so it does not appear in the process list, and reads it back to confirm the save.

If that store is unavailable (no `secret-tool` binary, or no Secret Service session on Linux), the CLI writes `~/.unkey/config.toml` instead and prints that path. Only your user can read the file (mode `0600`, in a `0700` directory):

```toml ~/.unkey/config.toml theme={"system"}
root_key = "unkey_xxx"
```

A key that is already in `~/.unkey/config.toml` is copied into the secret store the next time the CLI reads or writes the default config, and the file is removed. That key replaces any older key in the secret store, because the file only holds a key when the last save could not reach the secret store. `--config` or `UNKEY_CONFIG` pointing at a different file is read as a file and is not copied into the keychain.

`unkey login --root-key` uses this same storage. Running the command again replaces the stored key.

The session has exactly the permissions you selected. It does not inherit every permission your user has. Any role can approve a login, limited to the permissions that role can grant.

`unkey api` and `unkey deploy` use a stored CLI session when neither `--root-key` nor `UNKEY_ROOT_KEY` is set, and the session's API URL matches the command. An explicit `--config` on `unkey api` is used instead of the session. A root key saved with `--root-key` is the next fallback. See [CLI authentication](https://www.unkey.com/docs/platform/cli/authentication.md).

## Examples

Sign in, then call the API without a key flag:

```bash theme={"system"}
unkey login
unkey api apis list-keys --api-id=api_1234abcd
```

Sign in on a machine without a browser:

```bash theme={"system"}
unkey login --no-browser
```

Store a key you already created. The CLI prompts for it without echoing:

```bash theme={"system"}
unkey login --root-key=-
```

Store a key from a script or secret manager:

```bash theme={"system"}
printf '%s' "$UNKEY_ROOT_KEY" | unkey login --root-key=-
```

Point the command at a local API:

```bash theme={"system"}
unkey login --api-url=http://localhost:7070
```


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