Authentication & Keys
Use publishable keys, secret keys, CORS, and user access with the right trust boundary.
Use this page before connecting a project, server, vendor, or AI agent to a workspace.
Key Types
| Credential | Use for | Keep out of |
|---|---|---|
| Publishable Key | public reads and capability/customer-authorized operations; paired with a Secret Key for Agent CLI 0.20.1 in trusted shells | privileged writes |
| Secret Key | server-side SDK writes; Agent CLI in trusted shells | browser code, command arguments, logs, screenshots, commits |
| user access | human-scoped Console, OAuth, and Human CLI actions | shared agent automation |
| MCP OAuth access | hosted, shell-less discovery through three read-only tools | collection CRUD or commerce workflows |
The greenfield app creator keeps user and application identities separate. Its
browser authorization may issue one development-purpose sk01_ only after the
secret-free scaffold is installed; a Human CLI pat01_ is never valid app
environment input. Production service credentials remain an explicit Console
operation, not a scaffolder option.
Administrator MFA
Once the platform activates the tenant-admin MFA policy, an administrator role in any workspace requires MFA for the whole account, regardless of workspace state or current selection. If you have not enrolled, your next password or Google sign-in guides you through authenticator setup. Save the recovery codes shown once, then sign in again. Required accounts cannot disable MFA themselves. Promotion to administrator requires signing in again. If this happens during onboarding, follow the sign-in notice, enroll MFA, and return to the API key step. If you have not enrolled yet, password reset changes only your password and returns you to sign-in for enrollment. Enrolled accounts still require MFA to reset.
Activation and tenant-admin promotion revoke PATs issued without verified MFA provenance. PATs issued after MFA verification and service keys remain valid. Super-admin promotion continues to revoke all PATs. Use dedicated service keys for automation instead of sharing a person's PAT.
If you lose both your authenticator and recovery codes, contact platform support for manual recovery. Another super-admin verifies your identity by video call or in person and delivers a one-time enrollment grant. Enrollment still requires a fresh sign-in proof and a code from the new authenticator. Never put the grant in email, URLs or issues.
Service-Key Approval
When operator MFA enforcement is active, enrolled or MFA-required operators must enter a new six-digit TOTP to create or reissue a service key, including onboarding and browser app approval. Recovery codes cannot approve issuance. A required account without an enrolled factor must complete MFA enrollment first. Inactive installations keep existing issuance; non-required, unenrolled accounts retain baseline compatibility until the required-role policy applies. The account-wide tenant-admin policy makes all tenant-admin issuers required once activated.
The operator-session HTTP request accepts code; Console decides whether it is required. Published SDKs use issued keys and expose no key-mint API. Revoking a key does not require an action code.
CORS And Origins
- Add only the browser origins that should read workspace data.
- Treat staging, preview, and production origins as separate approvals.
- Remove old origins after domain changes or vendor offboarding.
Server Boundary
- Put privileged work behind a trusted server route, server action, worker, or backend service.
- Load Secret Key values from environment storage, not from checked-in code.
- For Agent CLI automation, prefer
SOFTWARE_PUBLISHABLE_KEYandSOFTWARE_SECRET_KEY; do not pass secrets as command arguments. - Rotate Secret Key ownership when the operator changes.
If a credential is unclear, stop and return to Integrations & Keys before implementation continues.
Customer sessions
Customer access/refresh tokens identify an end user, not a Console operator or a server credential. New apps use hosted OAuth/PKCE with an enabled registered client, exact origin/redirect, state validation and a trusted server token store. Keep tokens in HttpOnly cookies or a server-owned session; never browser JavaScript or localStorage. Browser API origins and hosted OAuth origins/redirects are separate registrations. Follow the Customers guide for current-customer lookup with me(), rotation and logout; Customers SDK describes the method boundaries.
A publishable key resolves the workspace and admits public reads plus specifically capability/customer-authorized operations. It does not authorize arbitrary writes. Secret keys and pat01_ operator credentials stay in trusted environments; PATs are not application service keys.
Optional handle password login
A workspace administrator can enable customerAuth.handleLoginEnabled in the existing Admin Panel customer-authentication settings. It is off by default. The setting is for the current account handle, not a separate private login ID. Enable it after the handle migration and server rollout finish.
Existing direct email/password requests keep working. With opt-in, direct client.customer.auth.login({ handle, password }) accepts one handle instead of email; sending both or neither is a validation error. CustomerLoginData keeps its existing email interface, and CustomerPasswordLoginData adds the handle branch. Handle login requires a stored email and local password; accounts without a stored email cannot use it. Turning it off leaves email login, public handles and existing sessions intact.
Hosted OAuth remains the recommended integration for new storefronts. Its server password endpoint also accepts the handle branch, but the hosted sign-in screen does not yet offer handle input. Passwordless codes and password reset remain email-based. A renamed or cleared handle stops matching; the old handle is not a login alias. Login errors and lockout rules stay the same for email and handle.