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

# Authentication and credential storage

> Use browser authorization interactively and explicit, non-persistent token inputs in CI.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Authenticate without putting tokens in command arguments or plaintext profile files.

## Prerequisites

* An active StackShift account
* Access to the account authorization page

## Workflow

<Steps>
  <Step>
    Authorize the active profile with the browser/device flow.
  </Step>

  <Step>
    Confirm the active identity.
  </Step>

  <Step>
    Use an environment, stdin, or protected token file only for CI.
  </Step>

  <Step>
    Revoke credentials when they are no longer needed.
  </Step>
</Steps>

## Interactive login

* The CLI prints the verification URL and user code.
* Without `--no-browser`, it also tries to open the complete verification URL.
* The code expires and can be exchanged only once.
* The CLI waits using the server-provided polling interval and honors cancellation.

```bash theme={null}
stackshift auth login
stackshift auth status
stackshift auth login --no-browser
```

## Where credentials are stored

Interactive tokens are stored under the `stackshift-cli` service in the operating-system credential manager, keyed by profile name. The YAML profile file contains only the API URL and optional default project, application, and environment.

There is no plaintext credential fallback. If the credential manager cannot store a token, login fails instead of writing it to configuration.

## CI token inputs and precedence

For an individual command, token lookup uses this order: `STACKSHIFT_TOKEN`, `--token-file`, `--token-stdin`, then the active profile credential.

* On Unix, a token file must not be accessible by group or other users; mode `0600` works.
* A token is never accepted as a positional argument.
* `--token-stdin` reads one trimmed line and reuses it within that process.

```bash theme={null}
STACKSHIFT_TOKEN="$CI_STACKSHIFT_TOKEN" stackshift project list -o json
printf '%s\n' "$CI_STACKSHIFT_TOKEN" | \
  stackshift --token-stdin project list -o json
stackshift --token-file ./stackshift.token project list -o json
```

## Revoke and remove credentials

Normal logout finds and revokes the active API token before deleting the local credential. `--local-only` removes only the local credential and leaves the server token active.

```bash theme={null}
stackshift auth token list
stackshift auth token revoke TOKEN_ID
stackshift auth logout
stackshift auth logout --local-only
```

## Expected result

<Check>
  Interactive credentials live in the operating-system credential manager, not the profile file.
</Check>

## Common failures

<Warning>
  * The device code expired or authorization was denied.
  * The active token lacks the customer CLI read/write scope required by the operation.
  * A Unix token file has group or other permission bits.
  * The credential manager is unavailable in a headless session.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Profiles, defaults, and global options" href="/cli/profiles-and-global-options">
    Use profiles for API and resource defaults, then override them explicitly for one command.
  </Card>

  <Card title="Output, pagination, errors, and automation" href="/cli/output-and-automation">
    Select stable machine output, fetch paginated results, and handle documented exit codes.
  </Card>

  <Card title="Diagnostics, completion, and troubleshooting" href="/cli/diagnostics-and-troubleshooting">
    Check version compatibility, produce sanitized diagnostics, install completion, and resolve common failures.
  </Card>
</CardGroup>