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

# Authentication and API keys

> Use your signed-in Aspect desktop account, store an API key for a CLI-only machine, or authenticate headless jobs through the environment.

The CLI uses your Aspect identity and its existing permissions. On a workstation with the desktop app, sign in to the app. On a machine without it, use an API key.

## With the desktop app

Open Aspect and sign in, then run:

```bash theme={null}
aspect auth status
aspect ls
```

The CLI uses the signed-in desktop account automatically. You do not need to create a key for this workflow.

<Note>
  A signed-in desktop session takes precedence over both an environment API key and a stored key. `aspect auth status --json` reports the source as `desktop`, `env`, or `auth-file`, and reports a key that is set but ignored. An offline signed-in desktop session does not silently switch to the key's account.
</Note>

## Create an API key

Use a key for a Linux server, render worker, CI job, or another CLI-only installation.

1. Sign in to the [Aspect web app](https://app.aspect.inc).
2. Open **Settings → API Keys**.
3. Choose **Create new API Key** and give it a name that identifies its use.
4. Copy the key, which begins with `sk_`. The full key is shown once.

Each key acts as the user who created it and inherits that user's access. Key creation currently accepts a name; it does not let you restrict a key to a project, folder, or read-only role. Choose the account used for an automated workflow accordingly.

## Sign in on a CLI-only computer

Run this in an interactive terminal and paste the key at the hidden prompt:

```bash theme={null}
aspect auth login
aspect auth status
```

`auth login` validates and stores an API key. It is not a browser sign-in flow. The default stored-key file is `~/.aspect/cli/auth.json`; treat it as a credential file.

If the CLI asks you to open or sign in to the installed Aspect app, follow that instruction. The desktop app is the sign-in path on that workstation.

## Headless machines and CI

Set `ASPECT_API_KEY` through your job runner's secret or environment settings. Authenticated commands use it without a preceding `auth login`:

```bash theme={null}
# ASPECT_API_KEY is supplied by your job runner.
aspect auth status --json
aspect ls "aspect://Acme/Documentary" --json
```

On a machine without an active desktop session, the environment key overrides a stored key. Avoid embedding a real key in commands, checked-in scripts, logs, or prompts. `auth login` without a supplied key cannot prompt in `--json` mode; an environment key is the normal choice for scripts.

## Sign out or revoke a key

```bash theme={null}
aspect auth logout
```

This removes the CLI's stored key and clears its saved default workspace. It does **not** revoke that key in Aspect, remove `ASPECT_API_KEY` from your environment, or sign out the desktop app.

To revoke a key, delete it from **Settings → API Keys** in the web app. To change the desktop identity, sign out of the desktop app. Check `aspect auth status` after changing credentials so you know which identity the next command will use.

If a command reports `not_logged_in` or `invalid_api_key`, follow [Troubleshooting](/docs/cli/troubleshooting#authentication).