Authentication

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 uses 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. At an interactive terminal it first asks for any store or business domains you didn't pass
2. The CLI prints an authorization URL — open it in your browser to authorize the CLI
3. After granting consent, the CLI receives and stores your credentials, and the store becomes your current profile
4. Credentials are encrypted and saved in the CLI's config directory (shoplazza-cli/ under your OS user config directory, e.g. ~/Library/Application Support/shoplazza-cli/ on macOS)

Without --store-domain, auth login logs in to your account only. Selecting a store requires at least one scope: pass --domain or --scope, or pick domains when prompted.

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

Each login replaces the scopes granted to your account. To add scopes and keep the ones you already have, add --merge-scopes:

shell

shoplazza auth login --store-domain my-store.myshoplaza.com --domain discounts --merge-scopes

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 SHOPLAZZA_UAT, which auth login reads in place of --uat:

shell

export SHOPLAZZA_UAT=your-token
shoplazza auth login --store-domain my-store.myshoplaza.com
shoplazza products +search --keyword "shirt"

tip

Get a UAT by running shoplazza auth login once on a machine with a browser — the login output includes it (uat). 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:

• Whether you are logged in, and the current account
• Granted OAuth scopes
• UAT expiration
• Every configured profile, with its store, scopes, token status, and which one is current

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, creating or reusing that store's profile. To manage profiles directly, or run one command against another store with --profile <name>, see profile.

Log out

Remove all profiles and stored credentials (at an interactive terminal, the CLI asks you to confirm):

shell

shoplazza auth logout

caution

Logging out removes all stored tokens and profiles from this machine. You will need to re-authenticate for your next CLI session.

Scope mapping

Each CLI module requires specific OAuth scopes. --domain <module> expands into these scopes:

Module	Required scopes
products	read_product, write_product, read_collection, write_collection, read_inventory, write_inventory, read_comments, write_comments, read_gift_cards, write_gift_cards
orders	read_order, write_order
customers	read_customer, write_customer
discounts	read_price_rules, write_price_rules
shop	read_shop, write_shop, read_shop_navigation, write_shop_navigation, read_collection, write_collection, read_product, write_product
themes	read_themes, write_themes, read_shop
checkout	read_themes, write_themes
app	read_themes, write_themes, read_shop
billing	None
webhook	None
all	Every scope above

billing and webhook add no scopes, so a store login with only --domain billing or --domain webhook (and no UAT) is refused for having no scope.

If your token lacks the required scope, the API rejects the call (HTTP 403) and the CLI returns an auth error (exit code 3) with a hint on how to re-authenticate with the correct scopes.

Security best practices

• Encrypted storage — Credentials are encrypted in the CLI's config directory, not stored 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