OrcaQubits Saleor Customer and Staff Management
Before writing code
Fetch live docs:
- Web-search
site:docs.saleor.io customers accounts registrationfor customer account model and registration flow - Web-search
site:docs.saleor.io staff users permissions groupsfor staff management and permission system - Web-search
site:docs.saleor.io authentication JWT tokensfor authentication flow and token handling - Fetch
https://docs.saleor.io/docs/developer/usersand review User model, addresses, and account operations - Web-search
site:docs.saleor.io permission groups MANAGE_PRODUCTS MANAGE_ORDERSfor the full list of available permissions
Customer Model
Saleor uses a single User entity for both customers and staff. The isStaff flag distinguishes between them.
| Field | Description |
|---|---|
id |
Unique user identifier |
email |
Email address (unique, used for login) |
firstName |
Customer first name |
lastName |
Customer last name |
isActive |
Whether the account is enabled |
isStaff |
Whether the user has dashboard access |
dateJoined |
Account creation timestamp |
lastLogin |
Most recent login timestamp |
metadata |
Public key-value metadata |
privateMetadata |
Staff-only key-value metadata |
languageCode |
Preferred language |
defaultShippingAddress |
Default shipping address |
defaultBillingAddress |
Default billing address |
Customer Registration and Login
Registration Flow
| Step | Mutation | Description |
|---|---|---|
| 1. Register | accountRegister |
Create account with email and password |
| 2. Confirm email | confirmAccount |
Verify email with token from confirmation email |
| 3. Active account | -- | Account is active after confirmation |
Registration Input
| Field | Required | Description |
|---|---|---|
email |
Yes | Customer email address |
password |
Yes | Account password |
firstName |
No | First name |
lastName |
No | Last name |
redirectUrl |
Yes | URL for email confirmation link |
channel |
Yes | Channel slug for channel-specific registration |
languageCode |
No | Preferred language for communications |
metadata |
No | Initial metadata key-value pairs |
Login Flow
| Step | Mutation | Description |
|---|---|---|
| 1. Obtain tokens | tokenCreate |
Provide email + password; returns JWT access and refresh tokens |
| 2. Use access token | -- | Include in Authorization: Bearer <token> header |
| 3. Refresh token | tokenRefresh |
Exchange refresh token for new access token |
| 4. Verify token | tokenVerify |
Check if a token is still valid |
JWT Authentication Flow
| Token Type | Lifetime | Purpose |
|---|---|---|
| Access token | Short-lived (configurable, default ~5 min) | Authenticate API requests |
| Refresh token | Long-lived (configurable) | Obtain new access tokens |
| CSRF token | Per-session | Protect against cross-site request forgery |
Token Mutations
| Operation | Mutation | Notes |
|---|---|---|
| Login | tokenCreate |
Returns token, refreshToken, csrfToken |
| Refresh | tokenRefresh |
Requires refreshToken; returns new token |
| Verify | tokenVerify |
Returns isValid and decoded payload |
| Deactivate all | tokensDeactivateAll |
Invalidate all tokens for the user |
Fetch live docs for token expiration configuration and any changes to the JWT authentication model.
Customer Addresses
Each customer can store multiple addresses with defaults for shipping and billing:
| Field | Description |
|---|---|
firstName |
Address first name |
lastName |
Address last name |
companyName |
Optional company name |
streetAddress1 |
Primary street address |
streetAddress2 |
Additional address line |
city |
City name |
postalCode |
Postal or ZIP code |
country |
ISO 3166-1 alpha-2 country code |
countryArea |
State or province |
phone |
Phone number |
isDefaultShippingAddress |
Default for shipping |
isDefaultBillingAddress |
Default for billing |
Address Mutations
| Operation | Mutation | Notes |
|---|---|---|
| Create address | accountAddressCreate |
Customer self-service |
| Update address | accountAddressUpdate |
Customer self-service |
| Delete address | accountAddressDelete |
Customer self-service |
| Set default | accountSetDefaultAddress |
Set shipping or billing default |
| Admin create | addressCreate |
Staff creating address for a customer |
| Admin update | addressUpdate |
Staff updating customer address |
| Admin delete | addressDelete |
Staff deleting customer address |
Staff Users vs Customers
| Aspect | Customer | Staff |
|---|---|---|
isStaff |
false |
true |
| Dashboard access | No | Yes |
| API scope | Storefront queries, own account | Admin queries, assigned permissions |
| Creation | accountRegister or customerCreate |
staffCreate |
| Permissions | None (implicit storefront access) | Assigned via permission groups |
Staff Management Mutations
| Operation | Mutation | Notes |
|---|---|---|
| Create staff | staffCreate |
Set email, permissions, groups |
| Update staff | staffUpdate |
Modify details and permissions |
| Delete staff | staffDelete |
Remove staff user |
Permission Groups
Permission groups bundle permissions and assign them to staff users:
| Operation | Mutation |
|---|---|
| Create group | permissionGroupCreate |
| Update group | permissionGroupUpdate |
| Delete group | permissionGroupDelete |
Key Permissions
| Permission | Grants Access To |
|---|---|
MANAGE_PRODUCTS |
Products, categories, collections, product types |
MANAGE_ORDERS |
Orders, fulfillments, draft orders |
MANAGE_USERS |
Customer accounts and staff users |
MANAGE_STAFF |
Staff accounts and permission groups |
MANAGE_DISCOUNTS |
Vouchers and promotions |
MANAGE_SHIPPING |
Shipping zones and methods |
MANAGE_CHANNELS |
Channel configuration |
MANAGE_CHECKOUTS |
Checkout operations |
MANAGE_APPS |
App installation and configuration |
MANAGE_SETTINGS |
Site-wide settings |
MANAGE_TRANSLATIONS |
Content translations |
HANDLE_PAYMENTS |
Payment processing and transactions |
MANAGE_GIFT_CARD |
Gift card creation and management |
MANAGE_PAGE_TYPES_AND_ATTRIBUTES |
Page types and attributes |
Fetch live docs for the complete
PermissionEnum-- additional permissions may exist for plugins and newer features.
Account Management Mutations
| Operation | Mutation | Actor |
|---|---|---|
| Request password reset | requestPasswordReset |
Customer |
| Set new password | setPassword |
Customer (with token) |
| Change password | passwordChange |
Customer (authenticated) |
| Request email change | requestEmailChange |
Customer |
| Confirm email change | confirmEmailChange |
Customer (with token) |
| Update account | accountUpdate |
Customer (own profile) |
| Delete account | accountDelete |
Customer (with token) |
| Admin create customer | customerCreate |
Staff |
| Admin update customer | customerUpdate |
Staff |
| Admin delete customer | customerDelete |
Staff |
| Admin bulk delete | customerBulkDelete |
Staff |
Best Practices
- Use
accountRegisterfor self-service registration andcustomerCreatefor staff-created accounts - Always configure
redirectUrlfor email confirmation and password reset to point to your storefront - Store custom customer data in
metadata(public) orprivateMetadata(staff-only) - Use permission groups to organize staff access -- avoid assigning permissions directly to users
- Implement token refresh logic in your storefront to maintain sessions without re-authentication
- Validate email confirmation before allowing customers to place orders
- Use
channelparameter in registration to send channel-specific confirmation emails - Handle
tokensDeactivateAllfor security-sensitive operations like password changes - Prefer
accountAddressCreatefor customer-facing flows andaddressCreatefor admin flows
Fetch the Saleor authentication and user management documentation for exact mutation inputs, permission enums, and token handling patterns before implementing.