Skip to content

armgit / spree

Public Imported from GitHub
0

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.

8.7 KB
Raw Blame
---
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