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

# Authentication

> Log in to the S2 CLI, manage access tokens, and switch between authentication methods.

The CLI can authenticate through browser login or with an S2 access token. Both can remain configured at the same time, and you can choose which one the CLI uses.

## Browser login

To sign in through your browser:

```bash theme={null}
s2 login # or s2 auth login
```

The CLI opens the S2 sign-in page in your default browser. After you sign in and approve access, it saves the browser-login credentials to your system keyring.

If the CLI cannot open a browser, use `s2 login --no-open` to print the URL. The browser must still be able to reach the loopback callback on the machine running the CLI.

The CLI does not silently fall back to plaintext if the keyring is unavailable. To explicitly store the browser-login credentials in a private plaintext file, run `s2 login --insecure-storage`.

### Check your authentication

```bash theme={null}
s2 auth status
```

This verifies the active credential with S2 and reports the selected authentication method, other configured methods, and any storage warnings. It exits successfully when S2 authenticates the credential and exits with a non-zero status when authentication cannot be verified.

For loopback endpoints, such as a local S2 Lite server, the command verifies connectivity instead. Credentials are not verified for those endpoints.

### Log out

```bash theme={null}
s2 logout # or s2 auth logout
```

This removes the local browser login and attempts to revoke it with the OAuth provider. It does not remove a separately stored S2 access token.

## S2 access tokens

Generate an access token from the [dashboard](https://s2.dev/dashboard), then store it with:

```bash theme={null}
s2 auth access-token set
```

Paste the token when prompted. The token is saved to your system credential manager.

### Environment override

Set `S2_ACCESS_TOKEN` to use a token without storing it:

```bash theme={null}
S2_ACCESS_TOKEN="$S2_ACCESS_TOKEN" s2 ls
```

The environment variable takes precedence over browser login and a stored access token.

### Standard input

To persist a token supplied by a secret manager or script, pass it through standard input explicitly:

```bash theme={null}
op read 'op://S2/access-token' | s2 auth access-token set --stdin
```

### Private file storage

The CLI does not silently fall back to plaintext when an OS credential store is unavailable. To explicitly use a private local file, add `--insecure-storage`:

```bash theme={null}
printf '%s\n' "$S2_ACCESS_TOKEN" | \
  s2 auth access-token set --stdin --insecure-storage
```

### Migrate an existing token

Access tokens previously saved as `access_token` in `config.toml` remain readable but are deprecated. Move one into the OS credential store with:

```bash theme={null}
s2 auth access-token migrate
```

If an OS credential store is unavailable, migrate it into the private local file instead:

```bash theme={null}
s2 auth access-token migrate --insecure-storage
```

### Remove a stored token

```bash theme={null}
s2 auth access-token remove
```

This removes the local credential but does not revoke the access token on S2. Use [`s2 revoke-access-token`](/docs/cli/access-tokens#revoke-an-access-token) when the token must stop working everywhere.

## Switch authentication methods

Browser login and a stored access token can coexist. Choose which persistent credential the CLI uses:

```bash theme={null}
s2 auth use browser-login
s2 auth use access-token
```

Switching does not delete either credential.

| Action                     | Credential used afterward                                         |
| -------------------------- | ----------------------------------------------------------------- |
| `s2 login`                 | Browser login                                                     |
| `s2 auth access-token set` | Stored access token                                               |
| `s2 auth use <method>`     | The selected persistent method                                    |
| Set `S2_ACCESS_TOKEN`      | Environment token for that process; overrides the selected method |