Staff & Roles - Spree Commerce documentation

Overview

Staff manage a store through the dashboard and the Admin API. What each person can do is decided by the roles they hold. Two things about that shape matter: A role belongs to what it governs. Every role names its owner — a Store for back-office staff, a Seller for a marketplace seller’s own team. The owner is both who the role belongs to and who it applies to, so a role on a Store is a staff role by construction. Assigning someone a role therefore grants access to that owner and nothing else, which is what keeps one store’s staff out of another’s data. Because roles are scoped to their owner, two stores can each define a “Manager” without colliding. A role carries its permissions directly. The role holds a plain list of permission keys, so what a role can do is visible on the role itself rather than assembled from something else at runtime.

Roles and permissions

A permission key is a verb and a resource — read_orders, write_products. Roles hold a list of them:

const role = await adminClient.roles.create({
  name: 'Fulfillment staff',
  description: 'Can see orders and ship them, nothing else',
  permissions: ['read_orders', 'write_fulfillments', 'read_products'],
})

curl -X POST 'https://api.mystore.com/api/v3/admin/roles' \
  -H 'X-Spree-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Fulfillment staff",
    "description": "Can see orders and ship them, nothing else",
    "permissions": ["read_orders", "write_fulfillments", "read_products"]
  }'

Every grantable key is discoverable, so a permission picker never needs a hardcoded list:

const { data: permissions } = await adminClient.permissions.list()

curl 'https://api.mystore.com/api/v3/admin/permissions' \
  -H 'X-Spree-API-Key: sk_xxx'

Keys are grouped so they can be presented sensibly — orders, catalog, marketing, customers, settings, access and analytics.

Group	Covers
Orders	Orders, payments, fulfillments, refunds, gift cards, store credit
Catalog	Products, media, categories, collections, stock, publishing
Marketing	Promotions
Customers	Customer accounts and groups
Settings	Store settings, webhooks, integrations
Access	API keys, staff, sellers, commissions
Analytics	The dashboard

The same vocabulary gates API keys. A secret key’s scopes come from this catalog too, so “what may this integration do” and “what may this person do” are described the same way — there is no second permission system to keep in step.

The admin role

Each store gets one protected admin role meaning everything in this store. It can’t be renamed, edited or deleted, and it isn’t shared between stores — each owner has its own. A role is deletable only when nothing depends on it: staff assignments and pending invitations have to be moved first, so nobody silently loses access.

Roles are pure data. They’re created through the dashboard, the Admin API, or seeds — there’s no code-level role definition to keep in sync. For record-level rules beyond what keys express, see Customize Permissions.

Creating Admin Users

Use the Spree CLI to create admin users:

Spree CLI

spree user create

The CLI will prompt you for the email and password. You can also pass them directly:

Spree CLI

spree user create --email admin@example.com --password secret123

The created user gets the admin role on the default store.

Authentication & identity providers

Staff authenticate against the Admin API, which issues a short-lived JWT used for subsequent requests. How a staff member proves who they are is pluggable — Spree ships email/password out of the box, and you can plug in any external identity provider (Okta, Microsoft Entra ID, Google Workspace, a custom JWT issuer, SAML, etc.) without changing the rest of the API. A staff member logs in via the POST /api/v3/admin/auth/login endpoint (see Admin API Authentication). The request’s provider field selects a registered authentication strategy. When provider is omitted it defaults to email, the built-in email/password strategy (which you can also disable and restrict the admin to your preferred SSO provider). Whichever strategy authenticates the request, Spree issues the same credentials in return, so downstream code and the admin SPA never need to know which provider was used:

a JWT access token (aud: admin_api), short-lived by design;
a rotating refresh token, set as an HttpOnly cookie scoped to /api/v3/admin/auth (the admin flow keeps it out of the response body — see Admin Auth & Cookie Refresh).

The same strategy registry exists on the customer side, so storefront sign-in is pluggable the same way — the only difference is the user class and that the Store API returns the refresh token in the body rather than a cookie.

Registering a custom identity provider

Follow the Custom API Authentication how-to for details how to create a custom authentication strategy and register it with the admin API. Once registered, you can use it from the admin SPA or any API client by passing its name in the provider field of the login request.

Inviting Admin Users

You can invite new admins through the Admin Panel or programmatically. Via Admin Panel:

Navigate to Settings → Users
Click Invite User
Enter the email address and select a role
Click Send Invitation

Programmatically: Using the Admin SDK, call client.invitations.create:

Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
})

const invitation = await client.invitations.create({
  email: 'new-admin@example.com',
  role_id: 'role_xxx',
})

Creating an invitation publishes invitation.created, which sends the email. Either way, 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.

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 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

A role holds flat permission keys from one catalog (read_orders, write_products, …) — the same vocabulary as secret API key scopes. Every Admin API request checks the staff member’s keys on the current store against the endpoint’s read_<resource> / write_<resource> key and returns 403 with details.required_permission when it is missing. Staff endpoints (/admin_users, /invitations, /roles) need read_staff / write_staff. Permissions apply to staff only. Customers never hold roles: the Store API authorizes them by ownership-scoped queries plus Spree::Storefront::AccessPolicy. See the Customize Permissions guide for details on creating custom roles and registering your own permission keys.

Admin SDK — the TypeScript client for back-office automation
Custom API Authentication — implement a custom identity-provider strategy (the full guide)
Admin API Authentication — keys, JWTs, scopes, and the refresh-cookie flow
Customers — Customer accounts and authentication
Permissions — Roles and authorization
Events — Subscribe to invitation events

​Overview

​Roles and permissions

​The admin role

​Creating Admin Users

​Authentication & identity providers

​How admin login works

​Registering a custom identity provider

​Inviting Admin Users

​Invitation Details

​Invitation Events

​Permissions

​Related Documentation

Overview

Roles and permissions

The admin role

Creating Admin Users

Authentication & identity providers

How admin login works

Registering a custom identity provider

Inviting Admin Users

Invitation Details

Invitation Events

Permissions

Related Documentation