# Authentication

> Authenticate Shoplazza CLI with OAuth 2.0 and PKCE: browser login, token login for CI, scope selection, multi-store switching, and where credentials are stored.

Shoplazza CLI v2 uses OAuth 2.0 with PKCE for secure authentication. This guide covers interactive login, non-interactive authentication for CI/CD, scope management, and multi-store workflows.

## Interactive login (browser)

The standard authentication flow opens your browser for OAuth consent:

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com
```

**What happens:**

1. The CLI starts an OAuth session with the Shoplazza partner platform
2. A browser window opens for you to authorize the CLI
3. After granting consent, the CLI receives and stores your credentials
4. Credentials are saved in your OS-native keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service)

### Specifying scopes at login

Use `--domain` to request access to specific business domains:

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
```

Or use `--scope` for fine-grained OAuth scope control:

```shell
shoplazza auth login --store-domain my-store.myshoplaza.com --scope read_product,write_product,read_order
```

### Check available scopes

```shell
shoplazza auth scopes
```

## Non-interactive login (CI/CD)

For CI/CD pipelines and automated environments, use a User Access Token (UAT):

```shell
shoplazza auth login --uat <your-token> --store-domain my-store.myshoplaza.com
```

Or set the environment variable:

```shell
export SHOPLAZZA_UAT=your-token
export SHOPLAZZA_STORE=my-store.myshoplaza.com
shoplazza products +search --keyword "shirt"
```

:::tip
Generate a UAT from the Shoplazza partner dashboard. Store it as a secret in your CI/CD system — never commit it to source control.
:::

## Check authentication status

```shell
shoplazza auth status
```

This displays:

* Current account
* Connected store
* Granted OAuth scopes
* Token expiration

## Switch stores

Switch to a different store without logging out:

```shell
shoplazza auth store use --store-domain another-store.myshoplaza.com
```

This reuses your existing account credentials and requests a store-specific token for the new store.

## Log out

Remove all stored credentials:

```shell
shoplazza auth logout
```

:::caution
Logging out removes all stored tokens from your OS keychain. You will need to re-authenticate for your next CLI session.
:::

## Scope mapping

Each CLI module requires specific OAuth scopes. The CLI automatically checks whether your token has the required scopes before making API calls.

| Module | Required scopes |
|--------|----------------|
| `products` | `read_product`, `write_product` |
| `orders` | `read_order`, `write_order` |
| `customers` | `read_customer`, `write_customer` |
| `discounts` | `read_discount`, `write_discount` |
| `shop` | `read_shop`, `write_shop` |
| `billing` | `read_billing`, `write_billing` |
| `webhook` | `read_webhook`, `write_webhook` |
| `themes` | `read_theme`, `write_theme` |

If your token lacks the required scope, the CLI returns a clear error with a hint on how to re-authenticate with the correct scopes.

## Security best practices

* **Use OS keychain** — Credentials are stored in your OS-native secure storage, not in plain-text config files
* **Rotate tokens** — Periodically re-authenticate to refresh your tokens
* **Minimal scopes** — Only request the scopes you need for your workflow
* **CI/CD secrets** — Store UAT tokens as encrypted secrets in your CI/CD system
* **Never commit tokens** — Add `.shoplazza/` to your `.gitignore`