Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Users
description: How Spree models customer and admin users — Devise authentication, account data, roles, abilities, and access permissions across stores.
canonical: "https://spreecommerce.org/docs/v5/developer/core-concepts/users"
---
## Overview
Spree has two separate user types:
- **Customers** — users who browse your store, manage their account, and purchase products via the Store API
- **Admins** — users who manage the store via the Admin Panel
| User type | Class | Default |
|-----------|-------|---------|
| Customers | `Spree.user_class` | `Spree::User` |
| Admins | `Spree.admin_user_class` | `Spree::AdminUser` |
<Info>
You can use your own user classes. See the [Customize Authentication guide](/v5/developer/customization/authentication) for details.
</Info>
## Customers
Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
```mermaid
erDiagram
Customer ||--o{ Order : "places"
Customer ||--o{ Address : "has many"
Customer ||--o{ Wishlist : "has many"
Customer ||--o{ StoreCredit : "has many"
Customer ||--o{ PaymentSource : "has many"
Customer {
string id
string email
string first_name
string last_name
}
Order {
string number
string state
}
Address {
string firstname
string lastname
string address1
string city
}
Wishlist {
string name
boolean is_default
}
```
### Registration
<CodeGroup>
```typescript Store SDK
const { token, user } = await client.customers.create({
email: '[email protected]',
password: 'password123',
password_confirmation: 'password123',
first_name: 'John',
last_name: 'Doe',
})
// token => JWT token for subsequent authenticated requests
// user => { id: "usr_xxx", email: "[email protected]", first_name: "John", ... }
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
-H 'X-Spree-Api-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "password123",
"password_confirmation": "password123",
"first_name": "John",
"last_name": "Doe"
}'
```
</CodeGroup>
### Login
<CodeGroup>
```typescript Store SDK
const { token, user } = await client.auth.login({
email: '[email protected]',
password: 'password123',
})
// Use the token for authenticated requests
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "password123"
}'
```
</CodeGroup>
The response includes a [JWT token](/api-reference/store-api/authentication) and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header. See the [account SDK guide](/v5/developer/sdk/store/account) for the full `auth.login`, refresh, and profile flows.
### Token Refresh
Refresh an expiring token to keep the session alive:
<CodeGroup>
```typescript Store SDK
const { token } = await client.auth.refresh({
refresh_token: existingRefreshToken,
})
```
```bash cURL
curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
-H 'X-Spree-API-Key: pk_xxx' \
-H 'Content-Type: application/json' \
-d '{ "refresh_token": "rt_xxx" }'
```
</CodeGroup>
### Customer Profile
<CodeGroup>
```typescript Store SDK
// Get current customer
const customer = await client.customer.get()
// {
// id: "usr_xxx",
// email: "[email protected]",
// first_name: "John",
// last_name: "Doe",
// default_shipping_address: { ... },
// default_billing_address: { ... },
// addresses: [{ ... }, { ... }],
// }
// Update profile
const updated = await client.customer.update({
first_name: 'Jonathan',
accepts_email_marketing: true,
})
```
```bash cURL
# Get current customer
curl 'https://api.mystore.com/api/v3/store/customers/me' \
-H 'Authorization: Bearer <jwt_token>'
# Update profile
curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me' \
-H 'Authorization: Bearer <jwt_token>' \
-H 'Content-Type: application/json' \
-d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
```
</CodeGroup>
### Customer Resources
Authenticated customers have access to these resources:
| Resource | Description |
|----------|-------------|
| [**Addresses**](/v5/developer/core-concepts/addresses#customer-address-book) | Billing and shipping addresses with default selection |
| [**Orders**](/v5/developer/core-concepts/orders#order-history) | Past order history |
| **Credit Cards** | Saved credit cards for checkout |
| **Payment Sources** | Other saved payment methods (PayPal, Klarna, etc.) |
| **Store Credits** | Balance assigned by the store, usable at checkout |
| **Gift Cards** | Gift cards owned by or assigned to the customer |
| **Wishlists** | Saved product lists |
### Guest Checkout
Customers don't need to register to purchase. Guest checkout uses an order token (`X-Spree-Token`) to identify the cart. See [Orders — Cart](/v5/developer/core-concepts/orders#cart) for details.
## Admin Users
Admin users manage the store via the Admin Panel. They have roles that control what they can access.
```mermaid
erDiagram
AdminUser ||--o{ RoleUser : "has many"
RoleUser }o--|| Role : "belongs to"
RoleUser }o--|| Store : "scoped to"
AdminUser ||--o{ Invitation : "invites"
AdminUser {
string id
string email
}
RoleUser {
string role_id
string resource_type
string resource_id
}
Role {
string name
}
Invitation {
string email
string status
string token
datetime expires_at
}
```
### Roles
Admin users can have different roles that control their permissions:
| Role | Description |
|------|-------------|
| `admin` | Full access to all Admin Panel features |
<Info>
You can create custom roles with specific permissions. See the [Customize Permissions guide](/v5/developer/customization/permissions) for details.
</Info>
### Creating Admin Users
Use the Spree CLI to create admin users:
```bash
spree user create
```
The CLI will prompt you for the email and password. You can also pass them directly:
```bash
spree user create --email [email protected] --password secret123
```
The created user gets the `admin` role on the default store.
### Inviting Admin Users
You can invite new admins through the Admin Panel or programmatically.
**Via Admin Panel:**
1. Navigate to **Settings → Users**
2. Click **Invite User**
3. Enter the email address and select a role
4. Click **Send Invitation**
The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
```mermaid
flowchart TB
A[Admin creates invitation] --> B[Invitation email sent]
B --> C[Invitee clicks link]
C --> D{Has account?}
D -->|Yes| E[Log in]
D -->|No| F[Create account]
E --> G[Accept invitation]
F --> G
G --> H[Role assigned to store]
```
#### Invitation Details
| Attribute | Description |
|-----------|-------------|
| `email` | Invitee's email address |
| `token` | Secure token for the invitation link |
| `status` | `pending` or `accepted` |
| `expires_at` | Expiration date (default: 2 weeks) |
| `resource` | The store being granted access to |
| `role` | The role to assign upon acceptance |
#### Invitation Events
The invitation system publishes [events](/v5/developer/core-concepts/events) you can subscribe to:
| Event | Description |
|-------|-------------|
| `invitation.created` | Invitation was created (triggers email) |
| `invitation.accepted` | Invitation was accepted and role assigned |
| `invitation.resent` | Invitation was resent to the invitee |
## Permissions
Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. Permissions apply to both customers (Store API access) and admins (Admin Panel access).
See the [Customize Permissions guide](/v5/developer/customization/permissions) for details on creating custom roles and permission sets.
## Related Documentation
- [Addresses](/v5/developer/core-concepts/addresses) — Customer address management
- [Orders](/v5/developer/core-concepts/orders) — Order history and checkout
- [Authentication](/v5/developer/customization/authentication) — Custom authentication setup
- [Permissions](/v5/developer/customization/permissions) — Roles and authorization
- [Events](/v5/developer/core-concepts/events) — Subscribe to user and invitation events
- [Store API Authentication](/api-reference/store-api/authentication) — Customer JWT auth flow
- [Admin API Authentication](/api-reference/admin-api/authentication) — Staff JWT + scopes auth flow