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.

Admin SPA Staff & API keys management

Damian Legawiec426d5005e99f
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index d4c9b1818b..5340912608 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -39,6 +39,566 @@ info:
```
version: v3
paths:
+ "/api/v3/admin/admin_users":
+ get:
+ summary: List staff
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns admin users with at least one role assignment on the current store.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: staff } = await client.adminUsers.list()
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: staff found
+ content:
+ application/json:
+ example:
+ data:
+ - id: admin_UkLWZg9DAJ
+ first_name: Jamika
+ last_name: Green
+ created_at: '2026-05-06T19:14:25.646Z'
+ updated_at: '2026-05-06T19:14:25.646Z'
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/admin/admin_users/{id}":
+ get:
+ summary: Show a staff member
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const staff = await client.adminUsers.get('admin_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: staff member found
+ content:
+ application/json:
+ example:
+ id: admin_UkLWZg9DAJ
+ first_name: Keiko
+ last_name: Wisoky
+ created_at: '2026-05-06T19:14:25.981Z'
+ updated_at: '2026-05-06T19:14:25.981Z'
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ patch:
+ summary: Update a staff member
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const staff = await client.adminUsers.update('admin_xxx', {
+ first_name: 'Ada',
+ role_ids: ['role_xxx']
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: staff member updated
+ content:
+ application/json:
+ example:
+ id: admin_UkLWZg9DAJ
+ first_name: Renamed
+ last_name: Stark
+ created_at: '2026-05-06T19:14:26.296Z'
+ updated_at: '2026-05-06T19:14:26.322Z'
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ first_name:
+ type: string
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ role_ids:
+ type: array
+ items:
+ type: string
+ delete:
+ summary: Remove a staff member from this store
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.adminUsers.delete('admin_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: staff removed from store
+ "/api/v3/admin/api_keys":
+ get:
+ summary: List API keys
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: keys } = await client.apiKeys.list()
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: API keys found
+ content:
+ application/json:
+ example:
+ data:
+ - id: key_UkLWZg9DAJ
+ name: Storefront key
+ key_type: publishable
+ token_prefix:
+ scopes: []
+ created_at: '2026-05-06T19:14:26.624Z'
+ updated_at: '2026-05-06T19:14:26.624Z'
+ revoked_at:
+ last_used_at:
+ plaintext_token: pk_ceNspWKRDdKTXY5b2ZBcx1wa
+ created_by_email:
+ - id: key_gbHJdmfrXB
+ name: Backend integration
+ key_type: secret
+ token_prefix: sk_JBwbUC97E
+ scopes:
+ - write_all
+ created_at: '2026-05-06T19:14:26.625Z'
+ updated_at: '2026-05-06T19:14:26.625Z'
+ revoked_at:
+ last_used_at:
+ plaintext_token:
+ created_by_email:
+ - id: key_EfhxLZ9ck8
+ name: non
+ key_type: secret
+ token_prefix: sk_aHNiBUfCZ
+ scopes:
+ - write_all
+ created_at: '2026-05-06T19:14:26.626Z'
+ updated_at: '2026-05-06T19:14:26.626Z'
+ revoked_at:
+ last_used_at:
+ plaintext_token:
+ created_by_email:
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
+ post:
+ summary: Create an API key
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const key = await client.apiKeys.create({
+ name: 'Backend integration',
+ key_type: 'secret',
+ scopes: ['read_orders', 'write_orders']
+ })
+ // `key.plaintext_token` is available only on this response.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: secret key created — plaintext token returned once
+ content:
+ application/json:
+ example:
+ id: key_VqXmZF31wY
+ name: CI key
+ key_type: secret
+ token_prefix: sk_hFv9z3sTw
+ scopes:
+ - read_orders
+ created_at: '2026-05-06T19:14:27.192Z'
+ updated_at: '2026-05-06T19:14:27.192Z'
+ revoked_at:
+ last_used_at:
+ plaintext_token: sk_hFv9z3sTw9vXGgqJpSFBc4Ch
+ created_by_email: [email protected]
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank and Scopes can't be blank
+ details:
+ name:
+ - can't be blank
+ scopes:
+ - can't be blank
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ - key_type
+ properties:
+ name:
+ type: string
+ example: Backend integration
+ key_type:
+ type: string
+ enum:
+ - publishable
+ - secret
+ scopes:
+ type: array
+ items:
+ type: string
+ example:
+ - read_orders
+ - write_orders
+ "/api/v3/admin/api_keys/{id}":
+ get:
+ summary: Show an API key
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const key = await client.apiKeys.get('key_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: API key found
+ content:
+ application/json:
+ example:
+ id: key_UkLWZg9DAJ
+ name: Storefront key
+ key_type: publishable
+ token_prefix:
+ scopes: []
+ created_at: '2026-05-06T19:14:27.480Z'
+ updated_at: '2026-05-06T19:14:27.480Z'
+ revoked_at:
+ last_used_at:
+ plaintext_token: pk_zBo9Dptd9m1eqzq2tvk2jiWZ
+ created_by_email:
+ delete:
+ summary: Delete an API key
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.apiKeys.delete('key_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: API key deleted
+ "/api/v3/admin/api_keys/{id}/revoke":
+ patch:
+ summary: Revoke an API key
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const key = await client.apiKeys.revoke('key_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: API key revoked
+ content:
+ application/json:
+ example:
+ id: key_gbHJdmfrXB
+ name: Backend integration
+ key_type: secret
+ token_prefix: sk_1tNpCb5UU
+ scopes:
+ - write_all
+ created_at: '2026-05-06T19:14:28.057Z'
+ updated_at: '2026-05-06T19:14:28.357Z'
+ revoked_at: '2026-05-06T19:14:28.356Z'
+ last_used_at:
+ plaintext_token:
+ created_by_email:
"/api/v3/admin/custom_field_definitions":
get:
summary: List custom field definitions
@@ -104,8 +664,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-06T15:38:39.483Z'
- updated_at: '2026-05-06T15:38:39.483Z'
+ created_at: '2026-05-06T19:14:28.376Z'
+ updated_at: '2026-05-06T19:14:28.376Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -113,8 +673,8 @@ paths:
field_type: short_text
resource_type: Spree::Order
storefront_visible: true
- created_at: '2026-05-06T15:38:39.484Z'
- updated_at: '2026-05-06T15:38:39.484Z'
+ created_at: '2026-05-06T19:14:28.379Z'
+ updated_at: '2026-05-06T19:14:28.379Z'
meta:
page: 1
limit: 25
@@ -177,8 +737,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-06T15:38:40.131Z'
- updated_at: '2026-05-06T15:38:40.131Z'
+ created_at: '2026-05-06T19:14:28.972Z'
+ updated_at: '2026-05-06T19:14:28.972Z'
requestBody:
content:
application/json:
@@ -261,8 +821,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-05-06T15:38:40.135Z'
- updated_at: '2026-05-06T15:38:40.135Z'
+ created_at: '2026-05-06T19:14:28.976Z'
+ updated_at: '2026-05-06T19:14:28.976Z'
patch:
summary: Update a custom field definition
tags:
@@ -301,8 +861,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: false
- created_at: '2026-05-06T15:38:40.423Z'
- updated_at: '2026-05-06T15:38:40.705Z'
+ created_at: '2026-05-06T19:14:29.258Z'
+ updated_at: '2026-05-06T19:14:29.536Z'
requestBody:
content:
application/json:
@@ -424,8 +984,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-05-06T15:38:41.292Z'
- updated_at: '2026-05-06T15:38:41.292Z'
+ created_at: '2026-05-06T19:14:30.104Z'
+ updated_at: '2026-05-06T19:14:30.104Z'
customer_id: cus_UkLWZg9DAJ
meta:
page: 1
@@ -513,8 +1073,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-05-06T15:38:42.658Z'
- updated_at: '2026-05-06T15:38:42.658Z'
+ created_at: '2026-05-06T19:14:31.455Z'
+ updated_at: '2026-05-06T19:14:31.455Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -625,8 +1185,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-05-06T15:38:42.930Z'
- updated_at: '2026-05-06T15:38:43.504Z'
+ created_at: '2026-05-06T19:14:31.723Z'
+ updated_at: '2026-05-06T19:14:32.299Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -759,8 +1319,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-05-06T15:38:44.711Z'
- updated_at: '2026-05-06T15:38:44.711Z'
+ created_at: '2026-05-06T19:14:33.408Z'
+ updated_at: '2026-05-06T19:14:33.408Z'
meta:
page: 1
limit: 25
@@ -847,8 +1407,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-05-06T15:38:45.281Z'
- updated_at: '2026-05-06T15:38:45.281Z'
+ created_at: '2026-05-06T19:14:33.963Z'
+ updated_at: '2026-05-06T19:14:33.963Z'
delete:
summary: Delete a customer credit card
tags:
@@ -966,8 +1526,8 @@ paths:
display_amount_remaining: "$50.00"
currency: USD
metadata: {}
- created_at: '2026-05-06T15:38:46.675Z'
- updated_at: '2026-05-06T15:38:46.675Z'
+ created_at: '2026-05-06T19:14:35.346Z'
+ updated_at: '2026-05-06T19:14:35.346Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
meta:
@@ -1039,8 +1599,8 @@ paths:
display_amount_remaining: "$25.00"
currency: USD
metadata: {}
- created_at: '2026-05-06T15:38:47.799Z'
- updated_at: '2026-05-06T15:38:47.799Z'
+ created_at: '2026-05-06T19:14:36.445Z'
+ updated_at: '2026-05-06T19:14:36.445Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
requestBody:
@@ -1128,8 +1688,8 @@ paths:
display_amount_remaining: "$50.00"
currency: USD
metadata: {}
- created_at: '2026-05-06T15:38:48.342Z'
- updated_at: '2026-05-06T15:38:48.626Z'
+ created_at: '2026-05-06T19:14:36.987Z'
+ updated_at: '2026-05-06T19:14:37.264Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
requestBody:
@@ -1281,8 +1841,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-06T15:38:49.750Z'
- updated_at: '2026-05-06T15:38:49.750Z'
+ created_at: '2026-05-06T19:14:38.349Z'
+ updated_at: '2026-05-06T19:14:38.349Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1365,8 +1925,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-06T15:38:50.607Z'
- updated_at: '2026-05-06T15:38:50.607Z'
+ created_at: '2026-05-06T19:14:39.194Z'
+ updated_at: '2026-05-06T19:14:39.194Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1482,8 +2042,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-05-06T15:38:50.881Z'
- updated_at: '2026-05-06T15:38:50.881Z'
+ created_at: '2026-05-06T19:14:39.462Z'
+ updated_at: '2026-05-06T19:14:39.462Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -1499,14 +2059,216 @@ paths:
patch:
summary: Update a customer
tags:
- - Customers
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Updates customer attributes. `tags` replaces the full set.
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const customer = await client.customers.update('cus_UkLWZg9DAJ', {
+ first_name: 'Updated',
+ tags: ['wholesale', 'vip'],
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: customer updated
+ content:
+ application/json:
+ example:
+ id: cus_UkLWZg9DAJ
+ first_name: Updated
+ last_name: Doe
+ phone:
+ accepts_email_marketing: false
+ full_name: Updated Doe
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ metadata: {}
+ last_sign_in_at:
+ current_sign_in_at:
+ created_at: '2026-05-06T19:14:40.006Z'
+ updated_at: '2026-05-06T19:14:40.285Z'
+ sign_in_count: 0
+ failed_attempts: 0
+ last_sign_in_ip:
+ current_sign_in_ip:
+ tags: []
+ internal_note_html:
+ default_billing_address_id:
+ default_shipping_address_id:
+ orders_count: 0
+ total_spent: '0.0'
+ display_total_spent: "$0.00"
+ last_order_completed_at:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ first_name:
+ type: string
+ last_name:
+ type: string
+ phone:
+ type: string
+ accepts_email_marketing:
+ type: boolean
+ internal_note:
+ type: string
+ tags:
+ type: array
+ items:
+ type: string
+ metadata:
+ type: object
+ delete:
+ summary: Delete a customer
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Deletes a customer. Returns 422 if the customer has any orders.
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.customers.delete('cus_UkLWZg9DAJ')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: customer deleted
+ "/api/v3/admin/invitations":
+ get:
+ summary: List invitations
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns invitations for the current store, including pending and accepted.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: invitations } = await client.invitations.list()
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: invitations found
+ content:
+ application/json:
+ example:
+ data:
+ - id: inv_UkLWZg9DAJ
+ status: pending
+ created_at: '2026-05-06T19:14:41.123Z'
+ updated_at: '2026-05-06T19:14:41.123Z'
+ expires_at: '2026-05-20T19:14:41.120Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create an invitation
+ tags:
+ - Configuration
security:
- api_key: []
bearer_auth: []
description: |-
- Updates customer attributes. `tags` replaces the full set.
+ Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -1518,9 +2280,9 @@ paths:
secretKey: 'sk_xxx',
})
- const customer = await client.customers.update('cus_UkLWZg9DAJ', {
- first_name: 'Updated',
- tags: ['wholesale', 'vip'],
+ const invitation = await client.invitations.create({
+ email: '[email protected]',
+ role_id: 'role_xxx'
})
parameters:
- name: x-spree-api-key
@@ -1533,79 +2295,88 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
responses:
- '200':
- description: customer updated
+ '201':
+ description: invitation created
content:
application/json:
example:
- id: cus_UkLWZg9DAJ
- first_name: Updated
- last_name: Doe
- phone:
- accepts_email_marketing: false
- full_name: Updated Doe
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- metadata: {}
- last_sign_in_at:
- current_sign_in_at:
- created_at: '2026-05-06T15:38:51.517Z'
- updated_at: '2026-05-06T15:38:51.847Z'
- sign_in_count: 0
- failed_attempts: 0
- last_sign_in_ip:
- current_sign_in_ip:
- tags: []
- internal_note_html:
- default_billing_address_id:
- default_shipping_address_id:
- orders_count: 0
- total_spent: '0.0'
- display_total_spent: "$0.00"
- last_order_completed_at:
+ id: inv_gbHJdmfrXB
+ status: pending
+ created_at: '2026-05-06T19:14:41.418Z'
+ updated_at: '2026-05-06T19:14:41.418Z'
+ expires_at: '2026-05-20T19:14:41.416Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - email
+ - role_id
properties:
email:
type: string
- first_name:
- type: string
- last_name:
- type: string
- phone:
- type: string
- accepts_email_marketing:
- type: boolean
- internal_note:
+ role_id:
type: string
- tags:
- type: array
- items:
- type: string
- metadata:
- type: object
+ example: role_xxx
+ "/api/v3/admin/invitations/{id}":
delete:
- summary: Delete a customer
+ summary: Revoke an invitation
tags:
- - Customers
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.invitations.delete('inv_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: invitation revoked
+ "/api/v3/admin/invitations/{id}/resend":
+ patch:
+ summary: Resend an invitation
+ tags:
+ - Configuration
security:
- api_key: []
bearer_auth: []
description: |-
- Deletes a customer. Returns 422 if the customer has any orders.
+ Issues a fresh token and dispatches the invitation email again.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -1617,7 +2388,7 @@ paths:
secretKey: 'sk_xxx',
})
- await client.customers.delete('cus_UkLWZg9DAJ')
+ const invitation = await client.invitations.resend('inv_xxx')
parameters:
- name: x-spree-api-key
in: header
@@ -1635,8 +2406,20 @@ paths:
schema:
type: string
responses:
- '204':
- description: customer deleted
+ '200':
+ description: invitation resent
+ content:
+ application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ status: pending
+ created_at: '2026-05-06T19:14:41.985Z'
+ updated_at: '2026-05-06T19:14:41.985Z'
+ expires_at: '2026-05-20T19:14:41.982Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
"/api/v3/admin/me":
get:
summary: Get current admin user and permissions
@@ -1682,11 +2465,14 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Tyron
- last_name: Littel
- created_at: '2026-05-06T15:38:52.838Z'
- updated_at: '2026-05-06T15:38:52.838Z'
+ first_name: Charlene
+ last_name: Wisoky
+ created_at: '2026-05-06T19:14:42.263Z'
+ updated_at: '2026-05-06T19:14:42.263Z'
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
permissions:
- allow: true
actions:
@@ -1832,8 +2618,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-06T15:38:52.943Z'
- updated_at: '2026-05-06T15:38:52.943Z'
+ created_at: '2026-05-06T19:14:42.313Z'
+ updated_at: '2026-05-06T19:14:42.313Z'
option_values: []
meta:
page: 1
@@ -1924,8 +2710,8 @@ paths:
position: 2
kind: dropdown
metadata: {}
- created_at: '2026-05-06T15:38:53.629Z'
- updated_at: '2026-05-06T15:38:53.629Z'
+ created_at: '2026-05-06T19:14:42.956Z'
+ updated_at: '2026-05-06T19:14:42.956Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -2046,8 +2832,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-06T15:38:53.949Z'
- updated_at: '2026-05-06T15:38:53.949Z'
+ created_at: '2026-05-06T19:14:43.247Z'
+ updated_at: '2026-05-06T19:14:43.247Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -2119,8 +2905,8 @@ paths:
position: 1
kind: dropdown
metadata: {}
- created_at: '2026-05-06T15:38:54.568Z'
- updated_at: '2026-05-06T15:38:54.853Z'
+ created_at: '2026-05-06T19:14:43.807Z'
+ updated_at: '2026-05-06T19:14:44.084Z'
option_values: []
schema:
"$ref": "#/components/schemas/OptionType"
@@ -2280,7 +3066,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H46988334888
+ number: H62698337491
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2305,8 +3091,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:38:55.814Z'
- updated_at: '2026-05-06T15:38:55.984Z'
+ created_at: '2026-05-06T19:14:45.021Z'
+ updated_at: '2026-05-06T19:14:45.117Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -2389,7 +3175,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H14401345119
+ number: H37384901266
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2414,8 +3200,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:38:56.799Z'
- updated_at: '2026-05-06T15:38:56.864Z'
+ created_at: '2026-05-06T19:14:45.731Z'
+ updated_at: '2026-05-06T19:14:45.794Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -2474,7 +3260,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H03111903140
+ number: H49288097976
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -2499,8 +3285,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:38:57.539Z'
- updated_at: '2026-05-06T15:38:57.916Z'
+ created_at: '2026-05-06T19:14:46.382Z'
+ updated_at: '2026-05-06T19:14:46.722Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -2569,7 +3355,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H30767646225
+ number: H34344934685
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2586,7 +3372,7 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-05-06T15:38:58Z'
+ fulfilled_at: '2026-05-06T19:14:47Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -2594,8 +3380,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:38:58.297Z'
- updated_at: '2026-05-06T15:38:58.695Z'
+ created_at: '2026-05-06T19:14:47.048Z'
+ updated_at: '2026-05-06T19:14:47.385Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -2653,7 +3439,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H04934591932
+ number: H82620392914
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2678,8 +3464,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:38:59.022Z'
- updated_at: '2026-05-06T15:38:59.370Z'
+ created_at: '2026-05-06T19:14:47.716Z'
+ updated_at: '2026-05-06T19:14:48.053Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -2737,7 +3523,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H77939081440
+ number: H83935840263
tracking: U10000
tracking_url:
cost: '10.0'
@@ -2762,8 +3548,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:38:59.707Z'
- updated_at: '2026-05-06T15:39:00.073Z'
+ created_at: '2026-05-06T19:14:48.373Z'
+ updated_at: '2026-05-06T19:14:48.712Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -2824,7 +3610,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H78758486575
+ number: H63075459410
tracking:
tracking_url:
cost: '10.0'
@@ -2849,8 +3635,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-05-06T15:39:00.970Z'
- updated_at: '2026-05-06T15:39:01.031Z'
+ created_at: '2026-05-06T19:14:49.439Z'
+ updated_at: '2026-05-06T19:14:49.485Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -2922,7 +3708,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 9767CD5982E9E1F3
+ code: 61CE3BB204DBDC09
status: active
currency: USD
amount: '10.0'
@@ -2936,8 +3722,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-05-06T15:39:01.377Z'
- updated_at: '2026-05-06T15:39:01.685Z'
+ created_at: '2026-05-06T19:14:49.826Z'
+ updated_at: '2026-05-06T19:14:50.124Z'
requestBody:
content:
application/json:
@@ -3068,8 +3854,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 108552
- slug: product-108552
+ name: Product 107040
+ slug: product-107040
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -3101,12 +3887,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:02.412Z'
- updated_at: '2026-05-06T15:39:02.412Z'
+ created_at: '2026-05-06T19:14:50.884Z'
+ updated_at: '2026-05-06T19:14:50.884Z'
digital_links: []
metadata: {}
- created_at: '2026-05-06T15:39:02.771Z'
- updated_at: '2026-05-06T15:39:02.771Z'
+ created_at: '2026-05-06T19:14:51.174Z'
+ updated_at: '2026-05-06T19:14:51.174Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -3173,8 +3959,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 122624
- slug: product-122624
+ name: Product 123452
+ slug: product-123452
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -3206,12 +3992,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:03.851Z'
- updated_at: '2026-05-06T15:39:03.851Z'
+ created_at: '2026-05-06T19:14:52.085Z'
+ updated_at: '2026-05-06T19:14:52.085Z'
digital_links: []
metadata: {}
- created_at: '2026-05-06T15:39:03.881Z'
- updated_at: '2026-05-06T15:39:03.881Z'
+ created_at: '2026-05-06T19:14:52.112Z'
+ updated_at: '2026-05-06T19:14:52.112Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -3300,8 +4086,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 135474
- slug: product-135474
+ name: Product 137110
+ slug: product-137110
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -3333,12 +4119,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:03.953Z'
- updated_at: '2026-05-06T15:39:03.953Z'
+ created_at: '2026-05-06T19:14:52.176Z'
+ updated_at: '2026-05-06T19:14:52.176Z'
digital_links: []
metadata: {}
- created_at: '2026-05-06T15:39:04.244Z'
- updated_at: '2026-05-06T15:39:04.244Z'
+ created_at: '2026-05-06T19:14:52.462Z'
+ updated_at: '2026-05-06T19:14:52.462Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -3400,8 +4186,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 145608
- slug: product-145608
+ name: Product 144545
+ slug: product-144545
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -3433,12 +4219,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:04.600Z'
- updated_at: '2026-05-06T15:39:04.600Z'
+ created_at: '2026-05-06T19:14:52.783Z'
+ updated_at: '2026-05-06T19:14:52.783Z'
digital_links: []
metadata: {}
- created_at: '2026-05-06T15:39:04.899Z'
- updated_at: '2026-05-06T15:39:05.204Z'
+ created_at: '2026-05-06T19:14:53.066Z'
+ updated_at: '2026-05-06T19:14:53.368Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -3564,8 +4350,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-dca37bbe3b96
- number: PPD8OIGN
+ response_code: BGS-b6f17bdce014
+ number: P2LMS7NO
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3583,14 +4369,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-06T15:39:06.236Z'
- updated_at: '2026-05-06T15:39:06.241Z'
+ created_at: '2026-05-06T19:14:54.340Z'
+ updated_at: '2026-05-06T19:14:54.343Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-06T15:39:06.239Z'
- updated_at: '2026-05-06T15:39:06.239Z'
+ created_at: '2026-05-06T19:14:54.342Z'
+ updated_at: '2026-05-06T19:14:54.342Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -3657,7 +4443,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: PMWHRZFU
+ number: P4IWE7MU
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -3668,8 +4454,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-06T15:39:07.591Z'
- updated_at: '2026-05-06T15:39:07.591Z'
+ created_at: '2026-05-06T19:14:55.632Z'
+ updated_at: '2026-05-06T19:14:55.632Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -3759,8 +4545,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-5f85cd421c84
- number: PR42HV9C
+ response_code: BGS-28d7efb5828c
+ number: PRRYGQHP
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3778,14 +4564,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-06T15:39:07.961Z'
- updated_at: '2026-05-06T15:39:07.964Z'
+ created_at: '2026-05-06T19:14:56.000Z'
+ updated_at: '2026-05-06T19:14:56.003Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-06T15:39:07.963Z'
- updated_at: '2026-05-06T15:39:07.963Z'
+ created_at: '2026-05-06T19:14:56.002Z'
+ updated_at: '2026-05-06T19:14:56.002Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -3844,8 +4630,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-61f5e1a763a1
- number: PX4QY4MX
+ response_code: BGS-5436b829fae9
+ number: PUHLHLYQ
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -3863,14 +4649,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-06T15:39:08.632Z'
- updated_at: '2026-05-06T15:39:08.634Z'
+ created_at: '2026-05-06T19:14:56.642Z'
+ updated_at: '2026-05-06T19:14:56.644Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-06T15:39:08.633Z'
- updated_at: '2026-05-06T15:39:09.077Z'
+ created_at: '2026-05-06T19:14:56.643Z'
+ updated_at: '2026-05-06T19:14:56.967Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -3939,8 +4725,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-4c991b13915c
- number: P5O6Q1VP
+ response_code: void-BGS-ef75357224b1
+ number: P7K8C85V
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -3958,14 +4744,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-05-06T15:39:10.450Z'
- updated_at: '2026-05-06T15:39:10.456Z'
+ created_at: '2026-05-06T19:14:58.034Z'
+ updated_at: '2026-05-06T19:14:58.036Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-05-06T15:39:10.454Z'
- updated_at: '2026-05-06T15:39:11.160Z'
+ created_at: '2026-05-06T19:14:58.035Z'
+ updated_at: '2026-05-06T19:14:58.334Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/refunds":
@@ -4093,14 +4879,14 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-46da7c9a4487
+ transaction_id: BGS-37185658164a
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
metadata: {}
- created_at: '2026-05-06T15:39:12.603Z'
- updated_at: '2026-05-06T15:39:12.603Z'
+ created_at: '2026-05-06T19:14:59.647Z'
+ updated_at: '2026-05-06T19:14:59.647Z'
requestBody:
content:
application/json:
@@ -4171,8 +4957,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R610855284
+ number: R201929534
customer_note:
currency: USD
locale: en
@@ -4215,8 +5001,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:12.910Z'
- updated_at: '2026-05-06T15:39:12.964Z'
+ created_at: '2026-05-06T19:14:59.940Z'
+ updated_at: '2026-05-06T19:14:59.989Z'
tags: []
internal_note:
approver_id:
@@ -4385,8 +5171,8 @@ paths:
data:
- id: or_UkLWZg9DAJ
market_id:
- number: R100259849
+ number: R906280437
customer_note:
currency: USD
locale: en
@@ -4429,8 +5215,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:14.719Z'
- updated_at: '2026-05-06T15:39:14.719Z'
+ created_at: '2026-05-06T19:15:01.722Z'
+ updated_at: '2026-05-06T19:15:01.722Z'
tags: []
internal_note:
approver_id:
@@ -4559,7 +5345,7 @@ paths:
example:
id: or_gbHJdmfrXB
market_id:
- number: R985800491
+ number: R761025636
customer_note:
currency: USD
@@ -4603,8 +5389,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:15.895Z'
- updated_at: '2026-05-06T15:39:15.899Z'
+ created_at: '2026-05-06T19:15:02.839Z'
+ updated_at: '2026-05-06T19:15:02.842Z'
tags: []
internal_note:
approver_id:
@@ -4776,8 +5562,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R182552732
+ number: R961535675
customer_note:
currency: USD
locale: en
@@ -4820,8 +5606,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:16.177Z'
- updated_at: '2026-05-06T15:39:16.177Z'
+ created_at: '2026-05-06T19:15:03.117Z'
+ updated_at: '2026-05-06T19:15:03.117Z'
tags: []
internal_note:
approver_id:
@@ -4890,7 +5676,7 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R721111794
+ number: R368582010
customer_note:
currency: USD
@@ -4934,8 +5720,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:17.363Z'
- updated_at: '2026-05-06T15:39:17.730Z'
+ created_at: '2026-05-06T19:15:04.215Z'
+ updated_at: '2026-05-06T19:15:04.499Z'
tags: []
internal_note:
approver_id:
@@ -5106,8 +5892,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R589173215
+ number: R178948040
customer_note:
currency: USD
locale: en
@@ -5134,7 +5920,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-05-06T15:39:18.867Z'
+ completed_at: '2026-05-06T19:15:05.462Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5150,8 +5936,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:18.813Z'
- updated_at: '2026-05-06T15:39:18.893Z'
+ created_at: '2026-05-06T19:15:05.365Z'
+ updated_at: '2026-05-06T19:15:05.492Z'
tags: []
internal_note:
approver_id:
@@ -5230,8 +6016,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R487134515
+ number: R383710968
customer_note:
currency: USD
locale: en
@@ -5258,7 +6044,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-05-06T15:39:20.138Z'
+ completed_at: '2026-05-06T19:15:06.717Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5272,10 +6058,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-05-06T15:39:20.436Z'
+ canceled_at: '2026-05-06T19:15:07.004Z'
approved_at:
- created_at: '2026-05-06T15:39:20.074Z'
- updated_at: '2026-05-06T15:39:20.479Z'
+ created_at: '2026-05-06T19:15:06.668Z'
+ updated_at: '2026-05-06T19:15:07.040Z'
tags: []
internal_note:
approver_id:
@@ -5332,8 +6118,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R070365976
+ number: R996790421
customer_note:
currency: USD
locale: en
@@ -5360,7 +6146,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-06T15:39:20.831Z'
+ completed_at: '2026-05-06T19:15:07.387Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5375,9 +6161,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-05-06T15:39:21.123Z'
- created_at: '2026-05-06T15:39:20.779Z'
- updated_at: '2026-05-06T15:39:20.831Z'
+ approved_at: '2026-05-06T19:15:07.684Z'
+ created_at: '2026-05-06T19:15:07.337Z'
+ updated_at: '2026-05-06T19:15:07.387Z'
tags: []
internal_note:
approver_id: admin_UkLWZg9DAJ
@@ -5434,8 +6220,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R215651185
+ number: R867851447
customer_note:
currency: USD
locale: en
@@ -5462,7 +6248,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-05-06T15:39:21.498Z'
+ completed_at: '2026-05-06T19:15:08.016Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5476,10 +6262,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-05-06T15:39:21.795Z'
+ canceled_at: '2026-05-06T19:15:08.309Z'
approved_at:
- created_at: '2026-05-06T15:39:21.405Z'
- updated_at: '2026-05-06T15:39:21.906Z'
+ created_at: '2026-05-06T19:15:07.965Z'
+ updated_at: '2026-05-06T19:15:08.389Z'
tags: []
internal_note:
approver_id:
@@ -5536,8 +6322,8 @@ paths:
example:
id: or_UkLWZg9DAJ
market_id:
- number: R395224525
+ number: R603605437
customer_note:
currency: USD
locale: en
@@ -5564,7 +6350,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-05-06T15:39:22.237Z'
+ completed_at: '2026-05-06T19:15:08.716Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -5580,8 +6366,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-05-06T15:39:22.189Z'
- updated_at: '2026-05-06T15:39:22.236Z'
+ created_at: '2026-05-06T19:15:08.666Z'
+ updated_at: '2026-05-06T19:15:08.715Z'
tags: []
internal_note:
approver_id:
@@ -5653,8 +6439,8 @@ paths:
metadata: {}
active: true
auto_capture:
- created_at: '2026-05-06T15:39:22.538Z'
- updated_at: '2026-05-06T15:39:22.539Z'
+ created_at: '2026-05-06T19:15:09.013Z'
+ updated_at: '2026-05-06T19:15:09.014Z'
meta:
page: 1
limit: 25
@@ -5734,8 +6520,8 @@ paths:
metadata: {}
active: true
auto_capture:
- created_at: '2026-05-06T15:39:22.828Z'
- updated_at: '2026-05-06T15:39:22.829Z'
+ created_at: '2026-05-06T19:15:09.299Z'
+ updated_at: '2026-05-06T19:15:09.300Z'
"/api/v3/admin/products/{product_id}/custom_fields":
get:
summary: List product custom fields
@@ -5803,8 +6589,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-05-06T15:39:23.144Z'
- updated_at: '2026-05-06T15:39:23.144Z'
+ created_at: '2026-05-06T19:15:09.608Z'
+ updated_at: '2026-05-06T19:15:09.608Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -5871,8 +6657,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-05-06T15:39:23.750Z'
- updated_at: '2026-05-06T15:39:23.750Z'
+ created_at: '2026-05-06T19:15:10.243Z'
+ updated_at: '2026-05-06T19:15:10.243Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -5956,8 +6742,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-05-06T15:39:24.114Z'
- updated_at: '2026-05-06T15:39:24.114Z'
+ created_at: '2026-05-06T19:15:10.594Z'
+ updated_at: '2026-05-06T19:15:10.594Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -6004,8 +6790,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-05-06T15:39:24.428Z'
- updated_at: '2026-05-06T15:39:24.708Z'
+ created_at: '2026-05-06T19:15:10.915Z'
+ updated_at: '2026-05-06T19:15:11.194Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -6143,24 +6929,31 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 394321
- slug: product-394321
+ name: Product 391530
+ slug: product-391530
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-06T15:39:25.028Z'
+ available_on: '2025-05-06T19:15:11.518Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Eum distinctio hic officiis quam at doloribus porro.
- Est eius aspernatur soluta laborum expedita exercitationem perspiciatis.
- Ipsa recusandae fuga a quae quisquam quam. Fuga ipsum cum molestiae
- pariatur non aut.
- description_html: Eum distinctio hic officiis quam at doloribus
- porro. Est eius aspernatur soluta laborum expedita exercitationem
- perspiciatis. Ipsa recusandae fuga a quae quisquam quam. Fuga
- ipsum cum molestiae pariatur non aut.
+ description: Temporibus distinctio voluptates suscipit quidem. At
+ eum quidem dolores voluptate quisquam sapiente facilis. Repellendus
+ quia adipisci accusamus cum et. Pariatur neque enim culpa dolorem
+ sed iste magni. Blanditiis eos mollitia ipsam consequatur tempora
+ impedit. Rerum amet ab ipsa cumque tenetur assumenda. Perspiciatis
+ doloribus vitae quasi consequatur culpa quam veritatis natus.
+ Aperiam error veritatis hic quasi officiis ipsa dolore. In possimus
+ quidem fugiat repellat corrupti culpa. Quod eius commodi provident
+ voluptates. Nostrum ipsa sapiente laboriosam veniam eaque est
+ id. Amet cupiditate explicabo debitis tenetur officiis autem eveniet.
+ description_html: |-
+ Temporibus distinctio voluptates suscipit quidem. At eum quidem dolores voluptate quisquam sapiente facilis. Repellendus quia adipisci accusamus cum et.
+ Pariatur neque enim culpa dolorem sed iste magni. Blanditiis eos mollitia ipsam consequatur tempora impedit. Rerum amet ab ipsa cumque tenetur assumenda.
+ Perspiciatis doloribus vitae quasi consequatur culpa quam veritatis natus. Aperiam error veritatis hic quasi officiis ipsa dolore. In possimus quidem fugiat repellat corrupti culpa.
+ Quod eius commodi provident voluptates. Nostrum ipsa sapiente laboriosam veniam eaque est id. Amet cupiditate explicabo debitis tenetur officiis autem eveniet.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -6175,16 +6968,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-06T15:39:25.053Z'
- updated_at: '2026-05-06T15:39:25.053Z'
+ created_at: '2026-05-06T19:15:11.542Z'
+ updated_at: '2026-05-06T19:15:11.542Z'
original_price:
status: active
- make_active_at: '2025-05-06T15:39:25.028Z'
+ make_active_at: '2025-05-06T19:15:11.518Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-06T15:39:25.040Z'
- updated_at: '2026-05-06T15:39:25.055Z'
+ created_at: '2026-05-06T19:15:11.529Z'
+ updated_at: '2026-05-06T19:15:11.543Z'
cost_price: '17.0'
cost_currency: USD
meta:
@@ -6323,16 +7116,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-05-06T15:39:25.726Z'
- updated_at: '2026-05-06T15:39:25.726Z'
+ created_at: '2026-05-06T19:15:12.229Z'
+ updated_at: '2026-05-06T19:15:12.229Z'
original_price:
status: draft
make_active_at:
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-06T15:39:25.725Z'
- updated_at: '2026-05-06T15:39:25.733Z'
+ created_at: '2026-05-06T19:15:12.227Z'
+ updated_at: '2026-05-06T19:15:12.234Z'
cost_price:
cost_currency: USD
schema:
@@ -6519,22 +7312,25 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 439753
- slug: product-439753
+ name: Product 432495
+ slug: product-432495
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-06T15:39:26.086Z'
+ available_on: '2025-05-06T19:15:12.584Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Laboriosam accusamus quae voluptatum consequatur. Nostrum
- quidem rerum dignissimos beatae ut quaerat consectetur. Quia excepturi
- facilis libero dolor placeat velit vero aspernatur.
- description_html: Laboriosam accusamus quae voluptatum consequatur.
- Nostrum quidem rerum dignissimos beatae ut quaerat consectetur.
- Quia excepturi facilis libero dolor placeat velit vero aspernatur.
+ description: Officia assumenda veritatis nihil blanditiis nesciunt.
+ Eum quis error commodi perferendis. Voluptates quas soluta accusantium
+ vero magni provident eaque. Similique sed reiciendis deserunt eligendi
+ sapiente ut sequi. Perspiciatis nam odio voluptas vel quam quidem.
+ Tempora provident expedita accusantium ab et. Ad amet doloribus
+ est eveniet quam perspiciatis voluptatibus assumenda.
+ description_html: |-
+ Officia assumenda veritatis nihil blanditiis nesciunt. Eum quis error commodi perferendis. Voluptates quas soluta accusantium vero magni provident eaque. Similique sed reiciendis deserunt eligendi sapiente ut sequi.
+ Perspiciatis nam odio voluptas vel quam quidem. Tempora provident expedita accusantium ab et. Ad amet doloribus est eveniet quam perspiciatis voluptatibus assumenda.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -6549,16 +7345,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-06T15:39:26.110Z'
- updated_at: '2026-05-06T15:39:26.110Z'
+ created_at: '2026-05-06T19:15:12.610Z'
+ updated_at: '2026-05-06T19:15:12.610Z'
original_price:
status: active
- make_active_at: '2025-05-06T15:39:26.086Z'
+ make_active_at: '2025-05-06T19:15:12.584Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-06T15:39:26.098Z'
- updated_at: '2026-05-06T15:39:26.111Z'
+ created_at: '2026-05-06T19:15:12.597Z'
+ updated_at: '2026-05-06T19:15:12.611Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -6626,26 +7422,27 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-45396
+ slug: product-456413
meta_description:
meta_keywords:
variant_count: 0
- available_on: '2025-05-06T15:39:26.728Z'
+ available_on: '2025-05-06T19:15:13.304Z'
purchasable: true
in_stock: false
backorderable: true
available: true
- description: Esse ipsa qui mollitia optio facilis. Dolor veritatis
- nemo odio eaque voluptatem. Natus soluta alias numquam mollitia
- esse iusto maxime. Illo ea ad maxime a consectetur similique vero.
- Repudiandae rem voluptatum esse sit excepturi ipsum a. A illo animi
- sapiente earum modi repudiandae inventore. Pariatur libero dicta
- odio mollitia. Eum porro vitae quae exercitationem eligendi error
- optio deserunt. Assumenda saepe nemo doloremque dolor. Ut illum
- molestiae placeat consequatur totam ea earum possimus.
+ description: Libero fugiat repellendus ea odio. Commodi libero laborum
+ illo minima vitae adipisci nostrum quidem. Incidunt ratione ab aut
+ magnam aliquid aperiam. Ullam ipsa nisi assumenda quasi excepturi
+ suscipit facilis dicta. Ipsam fuga voluptas tempore repellat optio
+ impedit pariatur. Odit consequatur enim minus soluta. Velit voluptatem
+ eius at assumenda nostrum iure. Quos ipsa at ab fuga iste. Similique
+ quibusdam perspiciatis atque non facere. Architecto ut dolorum distinctio
+ similique. Optio provident ab officia reiciendis.
description_html: |-
- Esse ipsa qui mollitia optio facilis. Dolor veritatis nemo odio eaque voluptatem. Natus soluta alias numquam mollitia esse iusto maxime. Illo ea ad maxime a consectetur similique vero. Repudiandae rem voluptatum esse sit excepturi ipsum a.
- A illo animi sapiente earum modi repudiandae inventore. Pariatur libero dicta odio mollitia. Eum porro vitae quae exercitationem eligendi error optio deserunt. Assumenda saepe nemo doloremque dolor. Ut illum molestiae placeat consequatur totam ea earum possimus.
+ Libero fugiat repellendus ea odio. Commodi libero laborum illo minima vitae adipisci nostrum quidem. Incidunt ratione ab aut magnam aliquid aperiam. Ullam ipsa nisi assumenda quasi excepturi suscipit facilis dicta.
+ Ipsam fuga voluptas tempore repellat optio impedit pariatur. Odit consequatur enim minus soluta. Velit voluptatem eius at assumenda nostrum iure. Quos ipsa at ab fuga iste.
+ Similique quibusdam perspiciatis atque non facere. Architecto ut dolorum distinctio similique. Optio provident ab officia reiciendis.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -6660,16 +7457,16 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-05-06T15:39:26.751Z'
- updated_at: '2026-05-06T15:39:26.751Z'
+ created_at: '2026-05-06T19:15:13.343Z'
+ updated_at: '2026-05-06T19:15:13.343Z'
original_price:
status: active
- make_active_at: '2025-05-06T15:39:26.728Z'
+ make_active_at: '2025-05-06T19:15:13.304Z'
discontinue_on:
metadata: {}
deleted_at:
- created_at: '2026-05-06T15:39:26.740Z'
- updated_at: '2026-05-06T15:39:27.040Z'
+ created_at: '2026-05-06T19:15:13.325Z'
+ updated_at: '2026-05-06T19:15:13.639Z'
cost_price: '17.0'
cost_currency: USD
schema:
@@ -6832,6 +7629,62 @@ paths:
responses:
'204':
description: product deleted
+ "/api/v3/admin/roles":
+ get:
+ summary: List roles
+ tags:
+ - Configuration
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the roles available for staff role pickers. Roles are global, not per-store.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: roles } = await client.roles.list()
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: roles found
+ content:
+ application/json:
+ example:
+ data:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ created_at: '2026-05-06T19:15:14.315Z'
+ updated_at: '2026-05-06T19:15:14.315Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
"/api/v3/admin/store":
get:
summary: Get the current store
@@ -6883,8 +7736,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-05-06T15:38:39.437Z'
- updated_at: '2026-05-06T15:39:27.808Z'
+ created_at: '2026-05-06T19:14:25.333Z'
+ updated_at: '2026-05-06T19:15:14.612Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -6955,8 +7808,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-05-06T15:38:39.437Z'
- updated_at: '2026-05-06T15:39:28.429Z'
+ created_at: '2026-05-06T19:14:25.333Z'
+ updated_at: '2026-05-06T19:15:15.210Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -7175,9 +8028,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-06T15:39:29.848Z'
- updated_at: '2026-05-06T15:39:29.858Z'
- product_name: Product 48883
+ created_at: '2026-05-06T19:15:16.619Z'
+ updated_at: '2026-05-06T19:15:16.631Z'
+ product_name: Product 486546
display_price: "$0.00"
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
@@ -7189,10 +8042,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 98.2
- height: 191.7
- width: 108.27
- depth: 51.84
+ weight: 139.86
+ height: 156.38
+ width: 163.0
+ depth: 12.5
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -7215,8 +8068,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:29.867Z'
- updated_at: '2026-05-06T15:39:29.867Z'
+ created_at: '2026-05-06T19:15:16.640Z'
+ updated_at: '2026-05-06T19:15:16.640Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -7224,9 +8077,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-06T15:39:29.865Z'
- updated_at: '2026-05-06T15:39:29.885Z'
- product_name: Product 48883
+ created_at: '2026-05-06T19:15:16.637Z'
+ updated_at: '2026-05-06T19:15:16.649Z'
+ product_name: Product 486546
display_price: "$19.99"
meta:
page: 1
@@ -7338,8 +8191,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:30.532Z'
- updated_at: '2026-05-06T15:39:30.532Z'
+ created_at: '2026-05-06T19:15:17.283Z'
+ updated_at: '2026-05-06T19:15:17.283Z'
metadata: {}
position: 3
total_on_hand: 0
@@ -7347,9 +8200,9 @@ paths:
cost_price:
cost_currency: USD
deleted_at:
- created_at: '2026-05-06T15:39:30.535Z'
- updated_at: '2026-05-06T15:39:30.536Z'
- product_name: Product 496338
+ created_at: '2026-05-06T19:15:17.286Z'
+ updated_at: '2026-05-06T19:15:17.287Z'
+ product_name: Product 492475
display_price: "$24.99"
'422':
description: validation error
@@ -7537,10 +8390,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 109.61
- height: 153.88
- width: 194.6
- depth: 125.0
+ weight: 139.2
+ height: 150.49
+ width: 171.59
+ depth: 38.84
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -7563,8 +8416,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:30.926Z'
- updated_at: '2026-05-06T15:39:30.926Z'
+ created_at: '2026-05-06T19:15:17.686Z'
+ updated_at: '2026-05-06T19:15:17.686Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -7572,9 +8425,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-06T15:39:30.923Z'
- updated_at: '2026-05-06T15:39:30.936Z'
- product_name: Product 51961
+ created_at: '2026-05-06T19:15:17.683Z'
+ updated_at: '2026-05-06T19:15:17.698Z'
+ product_name: Product 518557
display_price: "$19.99"
'404':
description: variant not found
@@ -7654,10 +8507,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 85.0
- height: 130.56
- width: 173.42
- depth: 12.77
+ weight: 55.89
+ height: 7.5
+ width: 176.6
+ depth: 156.78
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -7680,8 +8533,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-05-06T15:39:31.624Z'
- updated_at: '2026-05-06T15:39:31.624Z'
+ created_at: '2026-05-06T19:15:18.349Z'
+ updated_at: '2026-05-06T19:15:18.349Z'
metadata: {}
position: 2
total_on_hand: 0
@@ -7689,9 +8542,9 @@ paths:
cost_price: '17.0'
cost_currency: USD
deleted_at:
- created_at: '2026-05-06T15:39:31.622Z'
- updated_at: '2026-05-06T15:39:31.921Z'
- product_name: Product 534060
+ created_at: '2026-05-06T19:15:18.347Z'
+ updated_at: '2026-05-06T19:15:18.641Z'
+ product_name: Product 536764
display_price: "$19.99"
requestBody:
content:
@@ -8075,6 +8928,21 @@ components:
- item_id
- variant_id
- quantity
+ AdminUserRoleAssignment:
+ type: object
+ description: A role assignment for the current store on a staff member
+ properties:
+ id:
+ type: string
+ description: Prefixed role ID
+ example: role_abc123
+ name:
+ type: string
+ description: Role name
+ example: admin
+ required:
+ - id
+ - name
Address:
type: object
properties:
@@ -8209,6 +9077,10 @@ components:
type: string
updated_at:
type: string
+ roles:
+ type: array
+ items:
+ "$ref": "#/components/schemas/AdminUserRoleAssignment"
required:
- id
- email
@@ -8216,6 +9088,7 @@ components:
- last_name
- created_at
- updated_at
+ - roles
x-typelizer: true
AllowedOrigin:
type: object
@@ -8237,6 +9110,51 @@ components:
- updated_at
- store_id
x-typelizer: true
+ ApiKey:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ key_type:
+ type: string
+ token_prefix:
+ type: string
+ nullable: true
+ scopes:
+ type: array
+ items:
+ type: string
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ revoked_at:
+ type: string
+ nullable: true
+ last_used_at:
+ type: string
+ nullable: true
+ plaintext_token:
+ type: string
+ nullable: true
+ created_by_email:
+ type: string
+ nullable: true
+ required:
+ - id
+ - name
+ - key_type
+ - token_prefix
+ - scopes
+ - created_at
+ - updated_at
+ - revoked_at
+ - last_used_at
+ - plaintext_token
+ - created_by_email
+ x-typelizer: true
Category:
type: object
properties:
@@ -8925,6 +9843,42 @@ components:
- created_at
- updated_at
x-typelizer: true
+ Invitation:
+ type: object
+ properties:
+ id:
+ type: string
+ email:
+ type: string
+ status:
+ type: string
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ expires_at:
+ type: string
+ nullable: true
+ role_id:
+ type: string
+ nullable: true
+ role_name:
+ type: string
+ nullable: true
+ inviter_email:
+ type: string
+ nullable: true
+ required:
+ - id
+ - email
+ - status
+ - created_at
+ - updated_at
+ - expires_at
+ - role_id
+ - role_name
+ - inviter_email
+ x-typelizer: true
LineItem:
type: object
properties:
@@ -9952,6 +10906,23 @@ components:
- created_at
- updated_at
x-typelizer: true
+ Role:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - name
+ - created_at
+ - updated_at
+ x-typelizer: true
State:
type: object
properties:
diff --git a/packages/admin-sdk/.changeset/admin-staff-and-api-keys.md b/packages/admin-sdk/.changeset/admin-staff-and-api-keys.md
new file mode 100644
index 0000000000..88f0daf2fb
--- /dev/null
+++ b/packages/admin-sdk/.changeset/admin-staff-and-api-keys.md
@@ -0,0 +1,12 @@
+---
+'@spree/admin-sdk': minor
+---
+
+Staff and API key management.
+
+- New `client.adminUsers` accessor with `list / get / update / delete`. Listing is scoped to admin users with at least one role assignment on the current store. `delete` removes the per-store role assignment rather than deleting the global account, so the user keeps access to any other stores.
+- New `client.invitations` accessor with `list / get / create / delete / resend`. Invitations carry an `email` + prefixed `role_id`; on accept, a per-store `RoleUser` is created. `resend` issues a fresh token and re-dispatches the invitation email.
+- New `client.apiKeys` accessor with `list / get / create / update / delete / revoke`. Supports both `publishable` (storefront) and `secret` (server-to-server) keys. The plaintext token for secret keys is delivered exactly once on the create response — store it client-side immediately because subsequent reads expose only `token_prefix`. `revoke` marks the key revoked while preserving the row for audit.
+- New `client.roles` accessor with `list / get`. Read-only — used to populate the role picker on the staff invite/edit forms.
+- New types: `ApiKey`, `Invitation`, `Role`. `AdminUser` now includes a `roles` field with the role assignments scoped to the current store.
+- New params types: `ApiKeyCreateParams`, `ApiKeyUpdateParams`, `InvitationCreateParams`, `AdminUserUpdateParams`.
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index b392fc872f..433d5becb3 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -70,6 +70,9 @@ export interface MeResponse {
}
import type {
+ AdminUserUpdateParams,
+ ApiKeyCreateParams,
+ ApiKeyUpdateParams,
CustomerAddressParams,
CustomerCreateParams,
CustomerStoreCreditCreateParams,
@@ -83,6 +86,7 @@ import type {
DirectUploadCreateParams,
FulfillmentUpdateParams,
GiftCardApplyParams,
+ InvitationCreateParams,
LineItemCreateParams,
LineItemUpdateParams,
MediaCreateParams,
@@ -104,6 +108,8 @@ import type {
import type {
Address,
Adjustment,
+ AdminUser,
+ ApiKey,
Category,
Country,
CreditCard,
@@ -111,6 +117,7 @@ import type {
CustomField,
CustomFieldDefinition,
Fulfillment,
+ Invitation,
LineItem,
Media,
OptionType,
@@ -119,6 +126,7 @@ import type {
PaymentMethod,
Product,
Refund,
+ Role,
Store,
StoreCredit,
TaxCategory,
@@ -1098,6 +1106,142 @@ export class AdminClient {
signed_id: string
}> => this.request('POST', '/direct_uploads', { ...options, body: params }),
}
+
+ // ============================================
+ // Staff (admin users with role assignment on the current store)
+ // ============================================
+
+ readonly adminUsers = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<AdminUser>> =>
+ this.request<PaginatedResponse<AdminUser>>('GET', '/admin_users', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<AdminUser> =>
+ this.request<AdminUser>('GET', `/admin_users/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ update: (
+ id: string,
+ params: AdminUserUpdateParams,
+ options?: RequestOptions,
+ ): Promise<AdminUser> =>
+ this.request<AdminUser>('PATCH', `/admin_users/${id}`, { ...options, body: params }),
+
+ /**
+ * Removes the user's role assignments on the current store. The account is
+ * preserved — the user keeps access to any other stores. Mirrors the
+ * legacy "remove from staff" behaviour rather than the legacy controller's
+ * hard delete.
+ */
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/admin_users/${id}`, options),
+ }
+
+ // ============================================
+ // Invitations (pending staff invitations)
+ // ============================================
+
+ readonly invitations = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<Invitation>> =>
+ this.request<PaginatedResponse<Invitation>>('GET', '/invitations', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<Invitation> =>
+ this.request<Invitation>('GET', `/invitations/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (params: InvitationCreateParams, options?: RequestOptions): Promise<Invitation> =>
+ this.request<Invitation>('POST', '/invitations', { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/invitations/${id}`, options),
+
+ /** Issues a fresh token + email for a pending invitation. */
+ resend: (id: string, options?: RequestOptions): Promise<Invitation> =>
+ this.request<Invitation>('PATCH', `/invitations/${id}/resend`, options),
+ }
+
+ // ============================================
+ // API Keys (publishable + secret)
+ // ============================================
+
+ readonly apiKeys = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<ApiKey>> =>
+ this.request<PaginatedResponse<ApiKey>>('GET', '/api_keys', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<ApiKey> =>
+ this.request<ApiKey>('GET', `/api_keys/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ /**
+ * Creates a publishable or secret API key. For secret keys the response
+ * carries `plaintext_token` exactly once — store it client-side immediately
+ * because subsequent reads will return `null`.
+ */
+ create: (params: ApiKeyCreateParams, options?: RequestOptions): Promise<ApiKey> =>
+ this.request<ApiKey>('POST', '/api_keys', { ...options, body: params }),
+
+ update: (id: string, params: ApiKeyUpdateParams, options?: RequestOptions): Promise<ApiKey> =>
+ this.request<ApiKey>('PATCH', `/api_keys/${id}`, { ...options, body: params }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/api_keys/${id}`, options),
+
+ /** Marks a key revoked without deleting the row (preserves audit history). */
+ revoke: (id: string, options?: RequestOptions): Promise<ApiKey> =>
+ this.request<ApiKey>('PATCH', `/api_keys/${id}/revoke`, options),
+ }
+
+ // ============================================
+ // Roles (read-only — for staff role pickers)
+ // ============================================
+
+ readonly roles = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<Role>> =>
+ this.request<PaginatedResponse<Role>>('GET', '/roles', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (id: string, params?: { expand?: string[] }, options?: RequestOptions): Promise<Role> =>
+ this.request<Role>('GET', `/roles/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+ }
}
// Re-export for type convenience
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 47799ae31c..a0c219e12c 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -346,6 +346,32 @@ export interface CustomFieldDefinitionUpdateParams {
storefront_visible?: boolean
}
+export interface ApiKeyCreateParams {
+ name: string
+ key_type: 'publishable' | 'secret'
+ /** Required for `key_type: 'secret'`. See `Spree::ApiKey::SCOPES` for the full list. */
+ scopes?: string[]
+}
+
+export interface ApiKeyUpdateParams {
+ /** `key_type` is set on create only — flipping types invalidates downstream consumers. */
+ name?: string
+ scopes?: string[]
+}
+
+export interface InvitationCreateParams {
+ email: string
+ /** Prefixed role ID (e.g. `role_xxx`). */
+ role_id: string
+}
+
+export interface AdminUserUpdateParams {
+ first_name?: string
+ last_name?: string
+ /** Prefixed role IDs scoped to the current store. Treated as a complete replacement. */
+ role_ids?: string[]
+}
+
/**
* Owner type passed to the generic `client.customFields(ownerType, ownerId)`
* escape hatch. The first-class six (products, variants, orders, customers,
diff --git a/packages/admin-sdk/src/types/generated/AdminUser.ts b/packages/admin-sdk/src/types/generated/AdminUser.ts
index 1405cd17ec..3f956c9052 100644
--- a/packages/admin-sdk/src/types/generated/AdminUser.ts
+++ b/packages/admin-sdk/src/types/generated/AdminUser.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 6888199fe487f055f36bb5367b32b8e6
+// Typelizer digest 6933e1740c01636ff3f3edaf9171393d
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -9,6 +9,7 @@ interface AdminUser {
last_name: string | null;
created_at: string;
updated_at: string;
+ roles: Array<{ id: string; name: string }>;
}
export default AdminUser;
diff --git a/packages/admin-sdk/src/types/generated/ApiKey.ts b/packages/admin-sdk/src/types/generated/ApiKey.ts
new file mode 100644
index 0000000000..99da1412e8
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/ApiKey.ts
@@ -0,0 +1,19 @@
+// Typelizer digest 7afc1ab8373265baf688df481a0bf8d1
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface ApiKey {
+ id: string;
+ name: string;
+ key_type: string;
+ token_prefix: string | null;
+ scopes: Array<string>;
+ created_at: string;
+ updated_at: string;
+ revoked_at: string | null;
+ last_used_at: string | null;
+ plaintext_token: string | null;
+ created_by_email: string | null;
+}
+
+export default ApiKey;
diff --git a/packages/admin-sdk/src/types/generated/Invitation.ts b/packages/admin-sdk/src/types/generated/Invitation.ts
new file mode 100644
index 0000000000..43ab1cd868
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/Invitation.ts
@@ -0,0 +1,17 @@
+// Typelizer digest a180ffdf01300567a126e5dfb1f598ca
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface Invitation {
+ id: string;
+ email: string;
+ status: string;
+ created_at: string;
+ updated_at: string;
+ expires_at: string | null;
+ role_id: string | null;
+ role_name: string | null;
+ inviter_email: string | null;
+}
+
+export default Invitation;
diff --git a/packages/admin-sdk/src/types/generated/Role.ts b/packages/admin-sdk/src/types/generated/Role.ts
new file mode 100644
index 0000000000..05bc258986
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/Role.ts
@@ -0,0 +1,12 @@
+// Typelizer digest 5e193d55c9f6afeffe8ebbb1b762c0c2
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface Role {
+ id: string;
+ name: string;
+ created_at: string;
+ updated_at: string;
+}
+
+export default Role;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index 9298923ba8..dd6d371c01 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,10 +1,11 @@
-// Typelizer digest d10fc03e8f757b74e4cf20fa26a753f4
+// Typelizer digest ba039c928f7378234dfb83913d8b1211
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
export type { default as Adjustment } from './Adjustment'
export type { default as AdminUser } from './AdminUser'
export type { default as AllowedOrigin } from './AllowedOrigin'
+export type { default as ApiKey } from './ApiKey'
export type { default as Category } from './Category'
export type { default as Country } from './Country'
export type { default as CreditCard } from './CreditCard'
@@ -17,6 +18,7 @@ export type { default as DigitalLink } from './DigitalLink'
export type { default as Discount } from './Discount'
export type { default as Fulfillment } from './Fulfillment'
export type { default as GiftCard } from './GiftCard'
+export type { default as Invitation } from './Invitation'
export type { default as LineItem } from './LineItem'
export type { default as Market } from './Market'
export type { default as Media } from './Media'
@@ -32,6 +34,7 @@ export type { default as Product } from './Product'
export type { default as Refund } from './Refund'
export type { default as Reimbursement } from './Reimbursement'
export type { default as ReturnAuthorization } from './ReturnAuthorization'
+export type { default as Role } from './Role'
export type { default as State } from './State'
export type { default as StockItem } from './StockItem'
export type { default as StockLocation } from './StockLocation'
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 07b7b71a6f..be73161db8 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -13,6 +13,7 @@ export type { default as Address } from './generated/Address'
export type { default as Adjustment } from './generated/Adjustment'
export type { default as AdminUser } from './generated/AdminUser'
export type { default as AllowedOrigin } from './generated/AllowedOrigin'
+export type { default as ApiKey } from './generated/ApiKey'
export type { default as Category } from './generated/Category'
export type { default as Country } from './generated/Country'
export type { default as CreditCard } from './generated/CreditCard'
@@ -25,6 +26,7 @@ export type { default as DigitalLink } from './generated/DigitalLink'
export type { default as Discount } from './generated/Discount'
export type { default as Fulfillment } from './generated/Fulfillment'
export type { default as GiftCard } from './generated/GiftCard'
+export type { default as Invitation } from './generated/Invitation'
export type { default as LineItem } from './generated/LineItem'
export type { default as Market } from './generated/Market'
export type { default as Media } from './generated/Media'
@@ -40,6 +42,7 @@ export type { default as Product } from './generated/Product'
export type { default as Refund } from './generated/Refund'
export type { default as Reimbursement } from './generated/Reimbursement'
export type { default as ReturnAuthorization } from './generated/ReturnAuthorization'
+export type { default as Role } from './generated/Role'
export type { default as State } from './generated/State'
export type { default as StockItem } from './generated/StockItem'
export type { default as StockLocation } from './generated/StockLocation'
diff --git a/packages/admin/package.json b/packages/admin/package.json
index d826e2d50a..c380a1e5bf 100644
--- a/packages/admin/package.json
+++ b/packages/admin/package.json
@@ -30,6 +30,7 @@
"cmdk": "^1.1.1",
"date-fns": "^4.1.0",
"lucide-react": "^1.14.0",
+ "next-themes": "^0.4.6",
"react": "^19.2.5",
"react-day-picker": "^9.14.0",
"react-dom": "^19.2.5",
diff --git a/packages/admin/src/components/spree/page-header.tsx b/packages/admin/src/components/spree/page-header.tsx
index 0c84216cc7..b164ea0002 100644
--- a/packages/admin/src/components/spree/page-header.tsx
+++ b/packages/admin/src/components/spree/page-header.tsx
@@ -141,9 +141,15 @@ export function PageHeader({
>
{backTo && <BackButton fallback={backTo} />}
- <div className="flex flex-1 flex-wrap items-center gap-x-3 gap-y-1">
- <h1 className="text-2xl font-medium leading-tight">{title}</h1>
- {badges}
+ {/* Title + badges share the first row; subtitle drops to its own line
+ underneath so descriptive prose doesn't get crammed alongside the
+ heading. Short metadata subtitles (customer location, order status
+ hint) read fine on the second line too. */}
+ <div className="flex min-w-0 flex-1 flex-col gap-1">
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+ <h1 className="text-2xl font-medium leading-tight">{title}</h1>
+ {badges}
+ </div>
{subtitle && <span className="text-sm text-muted-foreground">{subtitle}</span>}
</div>
diff --git a/packages/admin/src/components/ui/badge.tsx b/packages/admin/src/components/ui/badge.tsx
index 6fb6ed0c56..1b5267300c 100644
--- a/packages/admin/src/components/ui/badge.tsx
+++ b/packages/admin/src/components/ui/badge.tsx
@@ -1,17 +1,25 @@
import { cva, type VariantProps } from 'class-variance-authority'
-
+import * as React from 'react'
+import { Slot } from '@/components/ui/slot'
import { cn } from '@/lib/utils'
const badgeVariants = cva(
- 'inline-flex items-center whitespace-nowrap text-xs font-normal leading-none rounded-md py-1 px-2',
+ 'group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-4xl border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3!',
{
variants: {
variant: {
- default: 'bg-card text-muted-foreground border border-border',
- active: 'bg-green-200 text-green-900 border border-transparent',
- warning: 'bg-yellow-200 text-yellow-900 border border-transparent',
- danger: 'bg-red-100 text-red-900 border border-transparent',
- info: 'bg-blue-50 text-blue-900 border border-transparent',
+ default: 'bg-primary text-primary-foreground [a]:hover:bg-primary/80',
+ secondary: 'bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80',
+ destructive:
+ 'bg-destructive/10 text-destructive focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:focus-visible:ring-destructive/40 [a]:hover:bg-destructive/20',
+ // Mirrors the `destructive` recipe (tinted bg + matching text) with a
+ // green hue for "succeeded / completed / paid / shipped" states. Dark
+ // mode bumps text to `green-400` so it stays legible on dark fills.
+ success:
+ 'bg-green-500/15 text-green-700 dark:bg-green-500/15 dark:text-green-400 [a]:hover:bg-green-500/25',
+ outline: 'border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground',
+ ghost: 'hover:bg-muted hover:text-muted-foreground dark:hover:bg-muted/50',
+ link: 'text-primary underline-offset-4 hover:underline',
},
},
defaultVariants: {
@@ -22,46 +30,60 @@ const badgeVariants = cva(
function Badge({
className,
- variant,
+ variant = 'default',
+ asChild = false,
...props
-}: React.ComponentProps<'span'> & VariantProps<typeof badgeVariants>) {
- return <span className={cn(badgeVariants({ variant }), className)} {...props} />
+}: React.ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+ const Comp = asChild ? Slot : 'span'
+
+ return (
+ <Comp
+ data-slot="badge"
+ data-variant={variant}
+ className={cn(badgeVariants({ variant }), className)}
+ {...props}
+ />
+ )
}
+// Maps order/payment/etc. status strings to one of the canonical Badge
+// variants. Success-y states ("active", "paid", "shipped", …) route through
+// the `success` variant so the UI stays color-coded; everything else leans
+// on the canonical shadcn variants with shape + label carrying meaning.
const statusVariantMap: Record<string, VariantProps<typeof badgeVariants>['variant']> = {
- active: 'active',
- complete: 'active',
- completed: 'active',
- paid: 'active',
- shipped: 'active',
- published: 'active',
- approved: 'active',
- ready: 'active',
- draft: 'default',
- pending: 'default',
- processing: 'default',
- inactive: 'default',
- cart: 'default',
- address: 'default',
- delivery: 'default',
- payment: 'default',
- confirm: 'default',
- resumed: 'info',
- partial: 'warning',
- archived: 'warning',
- returned: 'warning',
- backorder: 'warning',
- balance_due: 'warning',
- credit_owed: 'warning',
- canceled: 'danger',
- failed: 'danger',
- void: 'danger',
- error: 'danger',
- rejected: 'danger',
+ active: 'success',
+ complete: 'success',
+ completed: 'success',
+ paid: 'success',
+ shipped: 'success',
+ published: 'success',
+ approved: 'success',
+ ready: 'success',
+ draft: 'outline',
+ pending: 'outline',
+ processing: 'outline',
+ inactive: 'outline',
+ cart: 'outline',
+ address: 'outline',
+ delivery: 'outline',
+ payment: 'outline',
+ confirm: 'outline',
+ resumed: 'secondary',
+ partial: 'secondary',
+ archived: 'secondary',
+ returned: 'secondary',
+ backorder: 'secondary',
+ balance_due: 'secondary',
+ credit_owed: 'secondary',
+ canceled: 'destructive',
+ failed: 'destructive',
+ void: 'destructive',
+ error: 'destructive',
+ rejected: 'destructive',
}
function StatusBadge({ status, className }: { status: string; className?: string }) {
- const variant = statusVariantMap[status] ?? 'default'
+ const variant = statusVariantMap[status] ?? 'outline'
return (
<Badge variant={variant} className={cn('capitalize', className)}>
{status.replace(/_/g, ' ')}
diff --git a/packages/admin/src/components/ui/data-table.tsx b/packages/admin/src/components/ui/data-table.tsx
index 144dd5bc92..1429af3569 100644
--- a/packages/admin/src/components/ui/data-table.tsx
+++ b/packages/admin/src/components/ui/data-table.tsx
@@ -27,7 +27,7 @@ function TableHead({ className, ...props }: React.ComponentProps<'th'>) {
return (
<th
className={cn(
- 'text-left text-sm font-medium text-muted-foreground bg-muted py-2 px-3 border-b border-border whitespace-nowrap first:pl-4 last:pr-4 first:rounded-tl-2xl last:rounded-tr-2xl',
+ 'text-left text-sm font-medium text-muted-foreground bg-muted py-2 px-3 border-b border-border whitespace-nowrap first:pl-4 last:pr-4',
className,
)}
{...props}
diff --git a/packages/admin/src/components/ui/sonner.tsx b/packages/admin/src/components/ui/sonner.tsx
new file mode 100644
index 0000000000..84222ed3bd
--- /dev/null
+++ b/packages/admin/src/components/ui/sonner.tsx
@@ -0,0 +1,47 @@
+import {
+ CircleCheckIcon,
+ InfoIcon,
+ Loader2Icon,
+ OctagonXIcon,
+ TriangleAlertIcon,
+} from 'lucide-react'
+import type { CSSProperties } from 'react'
+import { Toaster as Sonner, type ToasterProps } from 'sonner'
+import { useTheme } from '@/providers/theme-provider'
+
+const Toaster = ({ ...props }: ToasterProps) => {
+ // The shadcn-default Sonner template assumes `next-themes`. This app has its
+ // own ThemeProvider that exposes a `mode` (the user's selection: light/dark/system)
+ // — Sonner's `theme` prop accepts the same three values, so we forward it.
+ const { mode } = useTheme()
+
+ return (
+ <Sonner
+ theme={mode as ToasterProps['theme']}
+ className="toaster group"
+ icons={{
+ success: <CircleCheckIcon className="size-4" />,
+ info: <InfoIcon className="size-4" />,
+ warning: <TriangleAlertIcon className="size-4" />,
+ error: <OctagonXIcon className="size-4" />,
+ loading: <Loader2Icon className="size-4 animate-spin" />,
+ }}
+ style={
+ {
+ '--normal-bg': 'var(--popover)',
+ '--normal-text': 'var(--popover-foreground)',
+ '--normal-border': 'var(--border)',
+ '--border-radius': 'var(--radius)',
+ } as CSSProperties
+ }
+ toastOptions={{
+ classNames: {
+ toast: 'cn-toast',
+ },
+ }}
+ {...props}
+ />
+ )
+}
+
+export { Toaster }
diff --git a/packages/admin/src/hooks/use-api-keys.ts b/packages/admin/src/hooks/use-api-keys.ts
new file mode 100644
index 0000000000..6cb73a3321
--- /dev/null
+++ b/packages/admin/src/hooks/use-api-keys.ts
@@ -0,0 +1,42 @@
+import type { ApiKey, ApiKeyCreateParams } from '@spree/admin-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { adminClient } from '@/client'
+
+const API_KEYS_KEY = ['api-keys'] as const
+
+export function useApiKeys() {
+ return useQuery({
+ queryKey: API_KEYS_KEY,
+ queryFn: () => adminClient.apiKeys.list({ limit: 100 }),
+ })
+}
+
+export function useCreateApiKey() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: (params: ApiKeyCreateParams) => adminClient.apiKeys.create(params),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: API_KEYS_KEY })
+ },
+ })
+}
+
+export function useRevokeApiKey() {
+ const qc = useQueryClient()
+ return useMutation<ApiKey, Error, string>({
+ mutationFn: (id: string) => adminClient.apiKeys.revoke(id),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: API_KEYS_KEY })
+ },
+ })
+}
+
+export function useDeleteApiKey() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: (id: string) => adminClient.apiKeys.delete(id),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: API_KEYS_KEY })
+ },
+ })
+}
diff --git a/packages/admin/src/hooks/use-staff.ts b/packages/admin/src/hooks/use-staff.ts
new file mode 100644
index 0000000000..66a9917ec3
--- /dev/null
+++ b/packages/admin/src/hooks/use-staff.ts
@@ -0,0 +1,86 @@
+import type { AdminUserUpdateParams, InvitationCreateParams } from '@spree/admin-sdk'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { adminClient } from '@/client'
+
+const STAFF_KEY = ['staff'] as const
+const INVITATIONS_KEY = ['invitations'] as const
+const ROLES_KEY = ['roles'] as const
+
+export function useStaff() {
+ return useQuery({
+ queryKey: STAFF_KEY,
+ queryFn: () => adminClient.adminUsers.list({ limit: 100 }),
+ })
+}
+
+export function useInvitations() {
+ return useQuery({
+ queryKey: INVITATIONS_KEY,
+ queryFn: () => adminClient.invitations.list({ limit: 100 }),
+ })
+}
+
+export function useRoles() {
+ return useQuery({
+ queryKey: ROLES_KEY,
+ queryFn: () => adminClient.roles.list({ limit: 100 }),
+ // Roles are global; cache aggressively so the role picker doesn't refetch
+ // every time the staff dialog opens.
+ staleTime: 5 * 60 * 1000,
+ })
+}
+
+export function useUpdateStaff() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: ({ id, params }: { id: string; params: AdminUserUpdateParams }) =>
+ adminClient.adminUsers.update(id, params),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: STAFF_KEY })
+ },
+ })
+}
+
+/**
+ * Removes the user's role assignments on the current store. The account is
+ * preserved — the user keeps access to any other stores.
+ */
+export function useRemoveStaff() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: (id: string) => adminClient.adminUsers.delete(id),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: STAFF_KEY })
+ },
+ })
+}
+
+export function useCreateInvitation() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: (params: InvitationCreateParams) => adminClient.invitations.create(params),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: INVITATIONS_KEY })
+ },
+ })
+}
+
+export function useResendInvitation() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: (id: string) => adminClient.invitations.resend(id),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: INVITATIONS_KEY })
+ },
+ })
+}
+
+export function useDeleteInvitation() {
+ const qc = useQueryClient()
+ return useMutation({
+ mutationFn: (id: string) => adminClient.invitations.delete(id),
+ onSuccess: () => {
+ qc.invalidateQueries({ queryKey: INVITATIONS_KEY })
+ },
+ })
+}
diff --git a/packages/admin/src/nav/settings.ts b/packages/admin/src/nav/settings.ts
index 92c93ecea2..5d96729533 100644
--- a/packages/admin/src/nav/settings.ts
+++ b/packages/admin/src/nav/settings.ts
@@ -23,7 +23,6 @@ settingsNav.add({
group: 'team',
position: 100,
subject: Subject.AdminUser,
- comingSoon: true,
})
settingsNav.add({
@@ -34,5 +33,4 @@ settingsNav.add({
group: 'team',
position: 200,
subject: Subject.ApiKey,
- comingSoon: true,
})
diff --git a/packages/admin/src/routes/__root.tsx b/packages/admin/src/routes/__root.tsx
index f990ab8cfc..7b83c945af 100644
--- a/packages/admin/src/routes/__root.tsx
+++ b/packages/admin/src/routes/__root.tsx
@@ -1,5 +1,5 @@
import { createRootRoute, Outlet } from '@tanstack/react-router'
-import { Toaster } from 'sonner'
+import { Toaster } from '@/components/ui/sonner'
export const Route = createRootRoute({
component: RootLayout,
@@ -9,7 +9,7 @@ function RootLayout() {
return (
<>
<Outlet />
- <Toaster position="bottom-right" richColors />
+ <Toaster position="bottom-right" />
</>
)
}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx b/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx
index bfefb53187..a1bba1f1ba 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/customers/$customerId.tsx
@@ -424,7 +424,7 @@ function OrdersCard({
<CardHeader>
<CardTitle>
Orders
- {totalCount > 0 && <Badge>{totalCount}</Badge>}
+ {totalCount > 0 && <Badge variant="outline">{totalCount}</Badge>}
</CardTitle>
{totalCount > orders.length && (
<CardAction>
@@ -595,7 +595,7 @@ function AddressesCard({ customer }: { customer: Customer }) {
<CardHeader>
<CardTitle>
Addresses
- {addresses.length > 0 && <Badge>{addresses.length}</Badge>}
+ {addresses.length > 0 && <Badge variant="outline">{addresses.length}</Badge>}
</CardTitle>
<CardAction>
<Button size="sm" variant="outline" onClick={() => setAddOpen(true)}>
@@ -621,8 +621,10 @@ function AddressesCard({ customer }: { customer: Customer }) {
addr.label ||
'—'}
<span className="ml-2 inline-flex gap-1">
- {addr.is_default_billing && <Badge variant="info">Default billing</Badge>}
- {addr.is_default_shipping && <Badge variant="info">Default shipping</Badge>}
+ {addr.is_default_billing && <Badge variant="outline">Default billing</Badge>}
+ {addr.is_default_shipping && (
+ <Badge variant="outline">Default shipping</Badge>
+ )}
</span>
</div>
<div className="text-muted-foreground">{addr.address1}</div>
diff --git a/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx b/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
index 97df47a164..8933708d44 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/orders/$orderId.tsx
@@ -397,9 +397,9 @@ function AddLineItemDialog({
</Field>
{selectedVariant && (
- <div className="rounded-lg border border-blue-200 bg-blue-50 p-3 flex items-center justify-between">
+ <div className="flex items-center justify-between rounded-lg border border-primary/30 bg-primary/5 p-3">
<div>
- <div className="font-medium text-sm">
+ <div className="text-sm font-medium">
{selectedVariant.product_name ?? selectedVariant.sku}
</div>
<div className="text-xs text-muted-foreground">
@@ -412,7 +412,8 @@ function AddLineItemDialog({
<button
type="button"
onClick={() => setSelectedVariant(null)}
- className="p-1 rounded hover:bg-blue-100 text-blue-600"
+ className="rounded p-1 text-muted-foreground hover:bg-accent hover:text-foreground"
+ aria-label="Clear selected variant"
>
<XCircleIcon className="size-4" />
</button>
@@ -526,7 +527,7 @@ function LineItemsCard({ order }: { order: Order }) {
<CardTitle>
<ShoppingCartIcon className="size-4" />
Line Items
- {items.length > 0 && <Badge>{items.length}</Badge>}
+ {items.length > 0 && <Badge variant="outline">{items.length}</Badge>}
</CardTitle>
<CardAction className="flex items-center gap-2">
<Button size="sm" variant="outline" onClick={() => setAddOpen(true)}>
@@ -736,7 +737,7 @@ function ShipmentsCard({ order }: { order: Order }) {
<CardTitle>
<TruckIcon className="size-4" />
Fulfillments
- <Badge>{fulfillments.length}</Badge>
+ <Badge variant="outline">{fulfillments.length}</Badge>
</CardTitle>
<CardAction className="flex items-center gap-2">
{order.fulfillment_status && <StatusBadge status={order.fulfillment_status} />}
@@ -889,7 +890,7 @@ function PaymentsCard({ order }: { order: Order }) {
<CardTitle>
<CreditCardIcon className="size-4" />
Payments
- {payments.length > 0 && <Badge>{payments.length}</Badge>}
+ {payments.length > 0 && <Badge variant="outline">{payments.length}</Badge>}
</CardTitle>
<CardAction className="flex items-center gap-2">
{order.payment_status && <StatusBadge status={order.payment_status} />}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx
index 40b430b1aa..578d5575fa 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings/api-keys.tsx
@@ -1,38 +1,738 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type { ApiKey, ApiKeyCreateParams } from '@spree/admin-sdk'
import { createFileRoute } from '@tanstack/react-router'
-import { ConstructionIcon } from 'lucide-react'
+import {
+ AlertTriangleIcon,
+ CheckIcon,
+ CopyIcon,
+ KeyRoundIcon,
+ MoreHorizontalIcon,
+ PlusIcon,
+} from 'lucide-react'
+import { useState } from 'react'
+import { Controller, useForm } from 'react-hook-form'
+import { toast } from 'sonner'
+import { z } from 'zod/v4'
+import { useConfirm } from '@/components/spree/confirm-dialog'
import { EmptyState } from '@/components/spree/empty-state'
import { PageHeader } from '@/components/spree/page-header'
-import { Card, CardContent } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHead,
+ TableHeader,
+ TableRow,
+} from '@/components/ui/data-table'
+import {
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from '@/components/ui/dialog'
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { Field, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import {
+ Sheet,
+ SheetContent,
+ SheetDescription,
+ SheetFooter,
+ SheetHeader,
+ SheetTitle,
+} from '@/components/ui/sheet'
+import { Skeleton } from '@/components/ui/skeleton'
+import { useApiKeys, useCreateApiKey, useDeleteApiKey, useRevokeApiKey } from '@/hooks/use-api-keys'
+import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard'
+import { formatRelativeTime } from '@/lib/formatters'
+import { cn } from '@/lib/utils'
export const Route = createFileRoute('/_authenticated/$storeId/settings/api-keys')({
component: ApiKeysSettingsPage,
})
-// TODO: replace placeholder once the Admin API exposes CRUD for `Spree::ApiKey`
-// - controller: spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
-// (model exists, with KEY_TYPES, SCOPES, revoke!, plaintext_token surfacing)
-// - serializer: needs to be built. Mind: never serialize `token`/`token_digest`;
-// only the `token_prefix` (12 chars) for display. `plaintext_token` is one-shot
-// in the create response.
-// - sdk methods: client.apiKeys.{list,get,create,revoke}
-// - UX: scope picker on create (multiselect against ApiKey::SCOPES); show
-// plaintext token exactly once with a "copy and store securely" warning.
+// Scope groups, in display order. Each entry maps a resource label to the
+// `read_*` and `write_*` scopes recognised by `Spree::ApiKey::SCOPES`. We
+// only render `write_*` for resources that ship a write scope (dashboard
+// is read-only). Keep this in sync with the server-side allowlist.
+const SCOPE_GROUPS: Array<{ label: string; resource: string; readOnly?: boolean }> = [
+ { label: 'Orders', resource: 'orders' },
+ { label: 'Products', resource: 'products' },
+ { label: 'Customers', resource: 'customers' },
+ { label: 'Payments', resource: 'payments' },
+ { label: 'Fulfillments', resource: 'fulfillments' },
+ { label: 'Refunds', resource: 'refunds' },
+ { label: 'Gift cards', resource: 'gift_cards' },
+ { label: 'Store credits', resource: 'store_credits' },
+ { label: 'Categories', resource: 'categories' },
+ { label: 'Custom field definitions', resource: 'custom_field_definitions' },
+ { label: 'Settings', resource: 'settings' },
+ { label: 'Webhooks', resource: 'webhooks' },
+ { label: 'Dashboard', resource: 'dashboard', readOnly: true },
+]
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
function ApiKeysSettingsPage() {
+ const { data, isLoading } = useApiKeys()
+ const [createOpen, setCreateOpen] = useState(false)
+ const [tokenReveal, setTokenReveal] = useState<ApiKey | null>(null)
+
+ const keys = data?.data ?? []
+ const publishable = keys.filter((k) => k.key_type === 'publishable')
+ const secret = keys.filter((k) => k.key_type === 'secret')
+
return (
<div className="flex flex-col gap-6">
<PageHeader
title="API keys"
subtitle="Publishable and secret keys for the Storefront and Admin APIs."
+ actions={
+ <Button size="sm" onClick={() => setCreateOpen(true)}>
+ <PlusIcon className="size-4" />
+ Create key
+ </Button>
+ }
+ />
+
+ <ApiKeyTable
+ title="Publishable"
+ description="Used by your storefront. Safe to expose in client-side code."
+ keys={publishable}
+ loading={isLoading}
+ showScopes={false}
+ />
+
+ <ApiKeyTable
+ title="Secret"
+ description="Server-to-server only. Never expose in client-side code."
+ keys={secret}
+ loading={isLoading}
+ showScopes
+ />
+
+ <CreateApiKeyDialog
+ open={createOpen}
+ onOpenChange={setCreateOpen}
+ onCreated={(key) => {
+ setCreateOpen(false)
+ // Surface the plaintext token modal only for secret keys — publishable
+ // tokens are always readable from the row, so a one-shot reveal would
+ // be confusing.
+ if (key.key_type === 'secret' && key.plaintext_token) {
+ setTokenReveal(key)
+ }
+ }}
/>
- <Card>
- <CardContent className="p-0">
+
+ <TokenRevealDialog
+ apiKey={tokenReveal}
+ onOpenChange={(open) => {
+ if (!open) setTokenReveal(null)
+ }}
+ />
+ </div>
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Table
+// ---------------------------------------------------------------------------
+
+function ApiKeyTable({
+ title,
+ description,
+ keys,
+ loading,
+ showScopes,
+}: {
+ title: string
+ description: string
+ keys: ApiKey[]
+ loading: boolean
+ showScopes: boolean
+}) {
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{title}</CardTitle>
+ <p className="text-sm text-muted-foreground">{description}</p>
+ </CardHeader>
+ <CardContent className="p-0">
+ {loading ? (
+ <div className="p-4">
+ <Skeleton className="h-10 w-full" />
+ </div>
+ ) : keys.length === 0 ? (
<EmptyState
- icon={<ConstructionIcon />}
- title="API key management is coming soon"
- description="Storefront and Admin keys are managed in the legacy Rails admin while the Admin API endpoints are being finalized."
+ icon={<KeyRoundIcon />}
+ title={`No ${title.toLowerCase()} keys yet`}
+ description="Create one to get started."
/>
- </CardContent>
- </Card>
+ ) : (
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead>Name</TableHead>
+ <TableHead>Token</TableHead>
+ {showScopes && <TableHead>Scopes</TableHead>}
+ <TableHead>Last used</TableHead>
+ <TableHead>Created</TableHead>
+ <TableHead className="w-12" />
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {keys.map((key) => (
+ <ApiKeyRow key={key.id} apiKey={key} showScopes={showScopes} />
+ ))}
+ </TableBody>
+ </Table>
+ )}
+ </CardContent>
+ </Card>
+ )
+}
+
+function ApiKeyRow({ apiKey, showScopes }: { apiKey: ApiKey; showScopes: boolean }) {
+ const revokeMutation = useRevokeApiKey()
+ const deleteMutation = useDeleteApiKey()
+ const confirm = useConfirm()
+ const { copied, copy } = useCopyToClipboard()
+
+ const isRevoked = !!apiKey.revoked_at
+ // Publishable keys always carry their plaintext token (they're meant to be
+ // exposed); secret keys only return `token_prefix` after the one-shot
+ // create response.
+ const visibleToken = apiKey.plaintext_token ?? apiKey.token_prefix ?? ''
+
+ async function handleRevoke() {
+ const ok = await confirm({
+ title: 'Revoke key?',
+ message: `Future requests using ${apiKey.name} will fail. The key stays in the list (with a revoked badge) so you can audit it later.`,
+ variant: 'destructive',
+ confirmLabel: 'Revoke',
+ })
+ if (!ok) return
+
+ try {
+ await revokeMutation.mutateAsync(apiKey.id)
+ toast.success('Key revoked')
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to revoke key')
+ }
+ }
+
+ async function handleDelete() {
+ const ok = await confirm({
+ title: 'Delete key?',
+ message: `${apiKey.name} will be permanently removed from this store. This can't be undone.`,
+ variant: 'destructive',
+ confirmLabel: 'Delete',
+ })
+ if (!ok) return
+
+ try {
+ await deleteMutation.mutateAsync(apiKey.id)
+ toast.success('Key deleted')
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to delete key')
+ }
+ }
+
+ return (
+ <TableRow className={cn(isRevoked && 'opacity-60')}>
+ <TableCell>
+ <div className="flex items-center gap-2">
+ <span className="font-medium">{apiKey.name}</span>
+ {isRevoked && <Badge variant="destructive">Revoked</Badge>}
+ </div>
+ </TableCell>
+ <TableCell>
+ <div className="flex items-center gap-1.5">
+ <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-xs">{visibleToken}…</code>
+ {apiKey.plaintext_token && (
+ <Button
+ size="icon-xs"
+ variant="ghost"
+ onClick={() => copy(apiKey.plaintext_token ?? '')}
+ aria-label="Copy token"
+ >
+ {copied ? <CheckIcon /> : <CopyIcon />}
+ </Button>
+ )}
+ </div>
+ </TableCell>
+ {showScopes && (
+ <TableCell>
+ <ScopeList scopes={apiKey.scopes} />
+ </TableCell>
+ )}
+ <TableCell className="text-sm text-muted-foreground whitespace-nowrap">
+ {/* `last_used_at` is throttled to update at most hourly (see
+ ApiKeyAuthentication#touch_api_key_if_needed), so the timestamp
+ won't be perfectly fresh — but it's accurate enough for "is this
+ key still in use?" decisions. */}
+ {apiKey.last_used_at ? (
+ formatRelativeTime(apiKey.last_used_at)
+ ) : (
+ <span className="text-muted-foreground/60">Never</span>
+ )}
+ </TableCell>
+ <TableCell className="text-sm text-muted-foreground whitespace-nowrap">
+ {formatRelativeTime(apiKey.created_at)}
+ {apiKey.created_by_email && <div className="text-xs">by {apiKey.created_by_email}</div>}
+ </TableCell>
+ <TableCell className="text-right">
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button size="icon-sm" variant="ghost" aria-label="Actions">
+ <MoreHorizontalIcon className="size-4" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ {!isRevoked && (
+ <>
+ <DropdownMenuItem onClick={handleRevoke}>Revoke key</DropdownMenuItem>
+ <DropdownMenuSeparator />
+ </>
+ )}
+ <DropdownMenuItem variant="destructive" onClick={handleDelete}>
+ Delete key
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </TableCell>
+ </TableRow>
+ )
+}
+
+// Maximum number of scope chips rendered inline before collapsing the rest
+// into a `+N` popover. Chosen so a typical row stays under one line at the
+// usual table widths.
+const SCOPE_PREVIEW_COUNT = 3
+
+function ScopeList({ scopes }: { scopes: string[] }) {
+ if (scopes.includes('write_all')) {
+ return <Badge>Full access</Badge>
+ }
+ if (scopes.includes('read_all')) {
+ return <Badge>Read all</Badge>
+ }
+ if (scopes.length === 0) {
+ return <span className="text-sm text-muted-foreground">—</span>
+ }
+
+ const preview = scopes.slice(0, SCOPE_PREVIEW_COUNT)
+ const overflow = scopes.slice(SCOPE_PREVIEW_COUNT)
+
+ return (
+ <div className="flex max-w-xs flex-wrap items-center gap-1">
+ {preview.map((scope) => (
+ <Badge key={scope} className="font-mono text-[10px]">
+ {scope}
+ </Badge>
+ ))}
+ {overflow.length > 0 && (
+ <Popover>
+ {/* `asChild` so the Badge itself becomes the click target — no
+ extra button chrome around the chip. */}
+ <PopoverTrigger asChild>
+ <button
+ type="button"
+ className="cursor-pointer rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+ aria-label={`Show ${overflow.length} more scope${overflow.length === 1 ? '' : 's'}`}
+ >
+ <Badge className="font-mono text-[10px] hover:bg-accent">+{overflow.length}</Badge>
+ </button>
+ </PopoverTrigger>
+ <PopoverContent align="start" className="w-auto max-w-sm p-2">
+ <div className="flex max-h-60 flex-col gap-1 overflow-y-auto">
+ {scopes.map((scope) => (
+ <Badge key={scope} className="self-start font-mono text-[10px]">
+ {scope}
+ </Badge>
+ ))}
+ </div>
+ </PopoverContent>
+ </Popover>
+ )}
</div>
)
}
+
+// ---------------------------------------------------------------------------
+// Create dialog
+// ---------------------------------------------------------------------------
+
+const createSchema = z
+ .object({
+ name: z.string().min(1, 'Name is required'),
+ key_type: z.enum(['publishable', 'secret']),
+ scopes: z.array(z.string()),
+ })
+ .refine((v) => v.key_type !== 'secret' || v.scopes.length > 0, {
+ message: 'Pick at least one scope',
+ path: ['scopes'],
+ })
+
+type CreateFormValues = z.infer<typeof createSchema>
+
+// Create UX is a side Sheet (not a Dialog) because the scope grid makes the
+// form taller than most viewports — Sheet handles overflow with internal
+// scroll and avoids the centered-modal "content cut off" problem.
+function CreateApiKeyDialog({
+ open,
+ onOpenChange,
+ onCreated,
+}: {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+ onCreated: (key: ApiKey) => void
+}) {
+ const createMutation = useCreateApiKey()
+
+ const form = useForm<CreateFormValues>({
+ resolver: zodResolver(createSchema),
+ defaultValues: { name: '', key_type: 'secret', scopes: [] },
+ })
+
+ const keyType = form.watch('key_type')
+
+ async function onSubmit(values: CreateFormValues) {
+ const params: ApiKeyCreateParams = {
+ name: values.name,
+ key_type: values.key_type,
+ scopes: values.key_type === 'secret' ? values.scopes : undefined,
+ }
+ try {
+ const key = await createMutation.mutateAsync(params)
+ toast.success('Key created')
+ form.reset({ name: '', key_type: 'secret', scopes: [] })
+ onCreated(key)
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to create key')
+ }
+ }
+
+ return (
+ <Sheet
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) form.reset({ name: '', key_type: 'secret', scopes: [] })
+ onOpenChange(next)
+ }}
+ >
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>Create API key</SheetTitle>
+ <SheetDescription>
+ Secret keys are server-to-server only and limited to the scopes you pick. Publishable
+ keys are for storefront/client-side use and have no scopes.
+ </SheetDescription>
+ </SheetHeader>
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ {/* `flex-1 overflow-y-auto` keeps the footer pinned while the body
+ scrolls when the scope grid overflows. */}
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <Field>
+ <FieldLabel htmlFor="key-name">Name</FieldLabel>
+ <Input
+ id="key-name"
+ autoFocus
+ placeholder="Backend integration, Storefront prod, …"
+ {...form.register('name')}
+ aria-invalid={!!form.formState.errors.name}
+ />
+ {form.formState.errors.name && (
+ <p className="text-sm text-destructive">{form.formState.errors.name.message}</p>
+ )}
+ </Field>
+
+ <Field>
+ <FieldLabel>Type</FieldLabel>
+ <Controller
+ name="key_type"
+ control={form.control}
+ render={({ field }) => (
+ <div className="grid grid-cols-2 gap-2">
+ <KeyTypeOption
+ value="secret"
+ label="Secret"
+ description="Admin API · server-to-server"
+ selected={field.value === 'secret'}
+ onSelect={() => field.onChange('secret')}
+ />
+ <KeyTypeOption
+ value="publishable"
+ label="Publishable"
+ description="Storefront · safe to expose"
+ selected={field.value === 'publishable'}
+ onSelect={() => field.onChange('publishable')}
+ />
+ </div>
+ )}
+ />
+ </Field>
+
+ {keyType === 'secret' && (
+ <Field>
+ <FieldLabel>Scopes</FieldLabel>
+ <Controller
+ name="scopes"
+ control={form.control}
+ render={({ field }) => (
+ <ScopePicker value={field.value} onChange={field.onChange} />
+ )}
+ />
+ {form.formState.errors.scopes && (
+ <p className="text-sm text-destructive">{form.formState.errors.scopes.message}</p>
+ )}
+ </Field>
+ )}
+ </div>
+ <SheetFooter>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ Cancel
+ </Button>
+ <Button type="submit" size="sm" disabled={form.formState.isSubmitting}>
+ {form.formState.isSubmitting ? 'Creating…' : 'Create key'}
+ </Button>
+ </SheetFooter>
+ </form>
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+function KeyTypeOption({
+ label,
+ description,
+ selected,
+ onSelect,
+}: {
+ value: 'publishable' | 'secret'
+ label: string
+ description: string
+ selected: boolean
+ onSelect: () => void
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onSelect}
+ className={cn(
+ 'flex flex-col items-start gap-1 rounded-lg border p-3 text-left transition-colors',
+ selected
+ ? 'border-primary bg-primary/5 text-foreground'
+ : 'border-border hover:border-foreground/30',
+ )}
+ >
+ <span className="font-medium">{label}</span>
+ <span className="text-xs text-muted-foreground">{description}</span>
+ </button>
+ )
+}
+
+function ScopePicker({ value, onChange }: { value: string[]; onChange: (next: string[]) => void }) {
+ const hasWriteAll = value.includes('write_all')
+ const hasReadAll = value.includes('read_all')
+
+ function toggleScope(scope: string) {
+ onChange(value.includes(scope) ? value.filter((v) => v !== scope) : [...value, scope])
+ }
+
+ function setAllRead(checked: boolean) {
+ let next = value.filter((v) => v !== 'read_all' && !v.startsWith('read_'))
+ if (checked) next = [...next, 'read_all']
+ onChange(next)
+ }
+
+ function setAllWrite(checked: boolean) {
+ let next = value.filter((v) => v !== 'write_all' && !v.startsWith('write_'))
+ if (checked) next = [...next, 'write_all']
+ onChange(next)
+ }
+
+ return (
+ <div className="flex flex-col gap-3 rounded-md border border-border">
+ {/* Quick access: write_all / read_all toggles. Selecting one blocks the
+ per-resource grid because the catch-all already covers it. */}
+ <div className="flex flex-col gap-2 border-b border-border bg-muted/30 p-3">
+ <label className="flex cursor-pointer items-center gap-2 text-sm">
+ <input
+ type="checkbox"
+ checked={hasWriteAll}
+ onChange={(e) => setAllWrite(e.target.checked)}
+ className="size-4 rounded border-border accent-primary"
+ />
+ <span className="font-medium">Full access (write_all)</span>
+ <span className="text-xs text-muted-foreground">— read + write on every resource</span>
+ </label>
+ <label className="flex cursor-pointer items-center gap-2 text-sm">
+ <input
+ type="checkbox"
+ checked={hasReadAll}
+ onChange={(e) => setAllRead(e.target.checked)}
+ disabled={hasWriteAll}
+ className="size-4 rounded border-border accent-primary"
+ />
+ <span className="font-medium">Read all (read_all)</span>
+ <span className="text-xs text-muted-foreground">— read on every resource</span>
+ </label>
+ </div>
+
+ <div
+ className={cn(
+ 'grid grid-cols-[1fr_auto_auto] gap-x-4 gap-y-2 p-3 text-sm',
+ (hasWriteAll || hasReadAll) && 'pointer-events-none opacity-50',
+ )}
+ >
+ <span className="font-medium text-muted-foreground">Resource</span>
+ <span className="font-medium text-muted-foreground">Read</span>
+ <span className="font-medium text-muted-foreground">Write</span>
+ {SCOPE_GROUPS.map((group) => {
+ const readScope = `read_${group.resource}`
+ const writeScope = `write_${group.resource}`
+ const hasRead = value.includes(readScope) || value.includes(writeScope)
+ const hasWrite = value.includes(writeScope)
+ return (
+ <ScopeRow
+ key={group.resource}
+ label={group.label}
+ hasRead={hasRead}
+ hasWrite={hasWrite}
+ readOnly={group.readOnly}
+ onToggleRead={() => toggleScope(readScope)}
+ onToggleWrite={() => {
+ // Toggling write also implies read on the server, but we keep
+ // them as separate checkboxes to make the user's intent
+ // explicit. If they tick write without read, the server
+ // grants read implicitly via `has_scope?`.
+ toggleScope(writeScope)
+ }}
+ />
+ )
+ })}
+ </div>
+ </div>
+ )
+}
+
+function ScopeRow({
+ label,
+ hasRead,
+ hasWrite,
+ readOnly,
+ onToggleRead,
+ onToggleWrite,
+}: {
+ label: string
+ hasRead: boolean
+ hasWrite: boolean
+ readOnly?: boolean
+ onToggleRead: () => void
+ onToggleWrite: () => void
+}) {
+ return (
+ <>
+ <span>{label}</span>
+ <input
+ type="checkbox"
+ checked={hasRead}
+ onChange={onToggleRead}
+ // Checking write implies read; reflect that here so the UI doesn't
+ // look out of sync with what the server will enforce.
+ disabled={hasWrite}
+ aria-label={`Read ${label}`}
+ className="size-4 justify-self-center rounded border-border accent-primary"
+ />
+ {readOnly ? (
+ <span className="text-xs text-muted-foreground justify-self-center">—</span>
+ ) : (
+ <input
+ type="checkbox"
+ checked={hasWrite}
+ onChange={onToggleWrite}
+ aria-label={`Write ${label}`}
+ className="size-4 justify-self-center rounded border-border accent-primary"
+ />
+ )}
+ </>
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Token reveal dialog (one-shot, on create)
+// ---------------------------------------------------------------------------
+
+function TokenRevealDialog({
+ apiKey,
+ onOpenChange,
+}: {
+ apiKey: ApiKey | null
+ onOpenChange: (open: boolean) => void
+}) {
+ const { copied, copy } = useCopyToClipboard()
+
+ return (
+ <Dialog open={!!apiKey} onOpenChange={onOpenChange}>
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Save your secret key</DialogTitle>
+ <DialogDescription>
+ This is the only time we'll show you the full key. Store it in a password manager or
+ your secret store now — if you lose it, you'll need to create a new one.
+ </DialogDescription>
+ </DialogHeader>
+ <DialogBody className="flex flex-col gap-3">
+ <div className="flex items-start gap-2 rounded-md border border-yellow-200 bg-yellow-50 p-3 text-sm text-yellow-900 dark:border-yellow-900/40 dark:bg-yellow-950/40 dark:text-yellow-200">
+ <AlertTriangleIcon className="size-4 shrink-0" />
+ <span>
+ Treat this key like a password. Anyone with it can act on your store via the Admin
+ API.
+ </span>
+ </div>
+ {apiKey?.plaintext_token && (
+ <div className="flex items-center gap-2 rounded-md border border-border bg-muted/40 p-3">
+ <code className="flex-1 truncate font-mono text-sm">{apiKey.plaintext_token}</code>
+ <Button
+ size="sm"
+ variant="outline"
+ onClick={() => copy(apiKey.plaintext_token ?? '')}
+ >
+ {copied ? <CheckIcon /> : <CopyIcon />}
+ {copied ? 'Copied' : 'Copy'}
+ </Button>
+ </div>
+ )}
+ </DialogBody>
+ <DialogFooter>
+ <Button size="sm" onClick={() => onOpenChange(false)}>
+ Done
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx b/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx
index 42c33c3167..ef55e1b03b 100644
--- a/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx
+++ b/packages/admin/src/routes/_authenticated/$storeId/settings/staff.tsx
@@ -1,34 +1,647 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type { AdminUser, Invitation, Role } from '@spree/admin-sdk'
import { createFileRoute } from '@tanstack/react-router'
-import { ConstructionIcon } from 'lucide-react'
+import {
+ ClockIcon,
+ MailIcon,
+ MoreHorizontalIcon,
+ PlusIcon,
+ ShieldIcon,
+ UsersRoundIcon,
+} from 'lucide-react'
+import { useState } from 'react'
+import { Controller, useForm } from 'react-hook-form'
+import { toast } from 'sonner'
+import { z } from 'zod/v4'
+import { useConfirm } from '@/components/spree/confirm-dialog'
import { EmptyState } from '@/components/spree/empty-state'
import { PageHeader } from '@/components/spree/page-header'
-import { Card, CardContent } from '@/components/ui/card'
+import { Avatar, AvatarFallback } from '@/components/ui/avatar'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import {
+ Table,
+ TableBody,
+ TableCell,
+ TableHead,
+ TableHeader,
+ TableRow,
+} from '@/components/ui/data-table'
+import {
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from '@/components/ui/dialog'
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { Field, FieldLabel } from '@/components/ui/field'
+import { Input } from '@/components/ui/input'
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from '@/components/ui/select'
+import { Skeleton } from '@/components/ui/skeleton'
+import {
+ useCreateInvitation,
+ useDeleteInvitation,
+ useInvitations,
+ useRemoveStaff,
+ useResendInvitation,
+ useRoles,
+ useStaff,
+ useUpdateStaff,
+} from '@/hooks/use-staff'
+import { formatRelativeTime } from '@/lib/formatters'
export const Route = createFileRoute('/_authenticated/$storeId/settings/staff')({
component: StaffSettingsPage,
})
-// TODO: replace placeholder once the Admin API exposes CRUD for `Spree.admin_user_class`
-// - controller: spree/api/app/controllers/spree/api/v3/admin/admin_users_controller.rb
-// - serializer already exists at spree/api/app/serializers/spree/api/v3/admin/admin_user_serializer.rb
-// - sdk methods: client.adminUsers.{list,get,create,update,delete}
-// - role assignment via Spree::RoleUser (scoped to current_store as resource)
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
function StaffSettingsPage() {
+ const { data: staff, isLoading: staffLoading } = useStaff()
+ const { data: invitations, isLoading: invitationsLoading } = useInvitations()
+ const [inviteOpen, setInviteOpen] = useState(false)
+
+ const pendingInvitations = invitations?.data.filter((i) => i.status === 'pending') ?? []
+
return (
<div className="flex flex-col gap-6">
<PageHeader
title="Staff"
subtitle="Invite teammates and manage their access to this store."
+ actions={
+ <Button size="sm" onClick={() => setInviteOpen(true)}>
+ <PlusIcon className="size-4" />
+ Invite teammate
+ </Button>
+ }
/>
- <Card>
- <CardContent className="p-0">
+
+ <StaffCard staff={staff?.data ?? []} loading={staffLoading} />
+
+ {(invitationsLoading || pendingInvitations.length > 0) && (
+ <PendingInvitationsCard invitations={pendingInvitations} loading={invitationsLoading} />
+ )}
+
+ <InviteDialog open={inviteOpen} onOpenChange={setInviteOpen} />
+ </div>
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Active staff card
+// ---------------------------------------------------------------------------
+
+function StaffCard({ staff, loading }: { staff: AdminUser[]; loading: boolean }) {
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>Members</CardTitle>
+ </CardHeader>
+ <CardContent className="p-0">
+ {loading ? (
+ <div className="flex flex-col gap-3 p-4">
+ <Skeleton className="h-10 w-full" />
+ <Skeleton className="h-10 w-full" />
+ </div>
+ ) : staff.length === 0 ? (
<EmptyState
- icon={<ConstructionIcon />}
- title="Staff management is coming soon"
- description="The Admin API endpoints for inviting and managing staff are next on the roadmap. In the meantime, manage staff via the legacy Rails admin."
+ icon={<UsersRoundIcon />}
+ title="No staff yet"
+ description="Invite a teammate to give them access to this store."
/>
- </CardContent>
- </Card>
+ ) : (
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead>Member</TableHead>
+ <TableHead>Roles</TableHead>
+ <TableHead className="w-12" />
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {staff.map((member) => (
+ <StaffRow key={member.id} member={member} />
+ ))}
+ </TableBody>
+ </Table>
+ )}
+ </CardContent>
+ </Card>
+ )
+}
+
+function StaffRow({ member }: { member: AdminUser }) {
+ const [editOpen, setEditOpen] = useState(false)
+ const removeMutation = useRemoveStaff()
+ const confirm = useConfirm()
+
+ const fullName = [member.first_name, member.last_name].filter(Boolean).join(' ').trim()
+ const initials = (fullName || member.email)
+ .split(/\s+/)
+ .map((s) => s[0])
+ .filter(Boolean)
+ .slice(0, 2)
+ .join('')
+ .toUpperCase()
+
+ async function handleRemove() {
+ const ok = await confirm({
+ title: 'Remove from store?',
+ message: `${fullName || member.email} will lose access to this store. Their account stays — they keep access to any other stores they belong to.`,
+ variant: 'destructive',
+ confirmLabel: 'Remove',
+ })
+ if (!ok) return
+
+ try {
+ await removeMutation.mutateAsync(member.id)
+ toast.success('Removed from store')
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to remove staff')
+ }
+ }
+
+ return (
+ <>
+ <TableRow>
+ <TableCell>
+ <div className="flex items-center gap-3">
+ <Avatar className="size-8">
+ <AvatarFallback className="bg-muted text-xs">{initials}</AvatarFallback>
+ </Avatar>
+ <div className="flex flex-col leading-tight">
+ <span className="font-medium text-foreground">{fullName || member.email}</span>
+ {fullName && <span className="text-xs text-muted-foreground">{member.email}</span>}
+ </div>
+ </div>
+ </TableCell>
+ <TableCell>
+ {member.roles.length === 0 ? (
+ <span className="text-sm text-muted-foreground">—</span>
+ ) : (
+ <div className="flex flex-wrap gap-1">
+ {member.roles.map((role) => (
+ <Badge key={role.id} className="capitalize">
+ {role.name}
+ </Badge>
+ ))}
+ </div>
+ )}
+ </TableCell>
+ <TableCell className="text-right">
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button size="icon-sm" variant="ghost" aria-label="Actions">
+ <MoreHorizontalIcon className="size-4" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ <DropdownMenuItem onClick={() => setEditOpen(true)}>
+ <ShieldIcon className="size-4" />
+ Edit roles
+ </DropdownMenuItem>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem variant="destructive" onClick={handleRemove}>
+ Remove from store
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </TableCell>
+ </TableRow>
+
+ <EditStaffDialog open={editOpen} onOpenChange={setEditOpen} member={member} />
+ </>
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Pending invitations card
+// ---------------------------------------------------------------------------
+
+function PendingInvitationsCard({
+ invitations,
+ loading,
+}: {
+ invitations: Invitation[]
+ loading: boolean
+}) {
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>Pending invitations</CardTitle>
+ </CardHeader>
+ <CardContent className="p-0">
+ {loading ? (
+ <div className="p-4">
+ <Skeleton className="h-10 w-full" />
+ </div>
+ ) : (
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead>Email</TableHead>
+ <TableHead>Role</TableHead>
+ <TableHead>Expires</TableHead>
+ <TableHead className="w-12" />
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {invitations.map((invitation) => (
+ <InvitationRow key={invitation.id} invitation={invitation} />
+ ))}
+ </TableBody>
+ </Table>
+ )}
+ </CardContent>
+ </Card>
+ )
+}
+
+function InvitationRow({ invitation }: { invitation: Invitation }) {
+ const resendMutation = useResendInvitation()
+ const deleteMutation = useDeleteInvitation()
+ const confirm = useConfirm()
+
+ async function handleResend() {
+ try {
+ await resendMutation.mutateAsync(invitation.id)
+ toast.success('Invitation resent')
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to resend invitation')
+ }
+ }
+
+ async function handleDelete() {
+ const ok = await confirm({
+ title: 'Revoke invitation?',
+ message: `${invitation.email} won't be able to accept this invitation. You can invite them again later.`,
+ variant: 'destructive',
+ confirmLabel: 'Revoke',
+ })
+ if (!ok) return
+
+ try {
+ await deleteMutation.mutateAsync(invitation.id)
+ toast.success('Invitation revoked')
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to revoke invitation')
+ }
+ }
+
+ return (
+ <TableRow>
+ <TableCell>
+ <div className="flex items-center gap-2">
+ <MailIcon className="size-4 text-muted-foreground" />
+ <span className="font-medium">{invitation.email}</span>
+ </div>
+ </TableCell>
+ <TableCell>
+ {invitation.role_name ? (
+ <Badge className="capitalize">{invitation.role_name}</Badge>
+ ) : (
+ <span className="text-sm text-muted-foreground">—</span>
+ )}
+ </TableCell>
+ <TableCell className="text-sm text-muted-foreground">
+ {invitation.expires_at ? (
+ <span className="inline-flex items-center gap-1">
+ <ClockIcon className="size-3.5" />
+ {formatRelativeTime(invitation.expires_at)}
+ </span>
+ ) : (
+ '—'
+ )}
+ </TableCell>
+ <TableCell className="text-right">
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button size="icon-sm" variant="ghost" aria-label="Actions">
+ <MoreHorizontalIcon className="size-4" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ <DropdownMenuItem onClick={handleResend}>
+ <MailIcon className="size-4" />
+ Resend invitation
+ </DropdownMenuItem>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem variant="destructive" onClick={handleDelete}>
+ Revoke invitation
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </TableCell>
+ </TableRow>
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Invite dialog
+// ---------------------------------------------------------------------------
+
+const inviteSchema = z.object({
+ email: z.string().min(1, 'Email is required').email('Enter a valid email'),
+ role_id: z.string().min(1, 'Pick a role'),
+})
+
+type InviteFormValues = z.infer<typeof inviteSchema>
+
+function InviteDialog({
+ open,
+ onOpenChange,
+}: {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { data: roles, isLoading: rolesLoading } = useRoles()
+ const createMutation = useCreateInvitation()
+
+ const form = useForm<InviteFormValues>({
+ resolver: zodResolver(inviteSchema),
+ defaultValues: { email: '', role_id: '' },
+ })
+
+ async function onSubmit(values: InviteFormValues) {
+ try {
+ await createMutation.mutateAsync(values)
+ toast.success('Invitation sent')
+ form.reset({ email: '', role_id: '' })
+ onOpenChange(false)
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to send invitation')
+ }
+ }
+
+ return (
+ <Dialog
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) form.reset({ email: '', role_id: '' })
+ onOpenChange(next)
+ }}
+ >
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Invite teammate</DialogTitle>
+ <DialogDescription>
+ We'll email them a sign-up link. They'll get the role you pick here for this store only.
+ </DialogDescription>
+ </DialogHeader>
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ <DialogBody className="flex flex-col gap-4">
+ <Field>
+ <FieldLabel htmlFor="invite-email">Email</FieldLabel>
+ <Input
+ id="invite-email"
+ type="email"
+ autoFocus
+ placeholder="[email protected]"
+ {...form.register('email')}
+ aria-invalid={!!form.formState.errors.email}
+ />
+ {form.formState.errors.email && (
+ <p className="text-sm text-destructive">{form.formState.errors.email.message}</p>
+ )}
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="invite-role">Role</FieldLabel>
+ <Controller
+ name="role_id"
+ control={form.control}
+ render={({ field }) => {
+ const roleList = roles?.data ?? []
+ return (
+ <Select value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger id="invite-role">
+ {/* Base UI's SelectValue defaults to rendering the raw
+ `value` (a prefixed role ID). Use the children
+ render-prop to map ID → name. */}
+ <SelectValue
+ placeholder={rolesLoading ? 'Loading roles…' : 'Select a role'}
+ >
+ {(value) => {
+ const role = roleList.find((r) => r.id === value)
+ return role ? (
+ <span className="capitalize">{role.name}</span>
+ ) : (
+ (value as string)
+ )
+ }}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectContent>
+ {roleList.map((role) => (
+ <SelectItem key={role.id} value={role.id} className="capitalize">
+ {role.name}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )
+ }}
+ />
+ {form.formState.errors.role_id && (
+ <p className="text-sm text-destructive">{form.formState.errors.role_id.message}</p>
+ )}
+ </Field>
+ </DialogBody>
+ <DialogFooter>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ Cancel
+ </Button>
+ <Button type="submit" size="sm" disabled={form.formState.isSubmitting}>
+ {form.formState.isSubmitting ? 'Sending…' : 'Send invitation'}
+ </Button>
+ </DialogFooter>
+ </form>
+ </DialogContent>
+ </Dialog>
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Edit staff dialog
+// ---------------------------------------------------------------------------
+
+const editSchema = z.object({
+ first_name: z.string().optional(),
+ last_name: z.string().optional(),
+ role_ids: z.array(z.string()).min(1, 'Pick at least one role'),
+})
+
+type EditFormValues = z.infer<typeof editSchema>
+
+function EditStaffDialog({
+ open,
+ onOpenChange,
+ member,
+}: {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+ member: AdminUser
+}) {
+ const { data: roles } = useRoles()
+ const updateMutation = useUpdateStaff()
+
+ const form = useForm<EditFormValues>({
+ resolver: zodResolver(editSchema),
+ defaultValues: {
+ first_name: member.first_name ?? '',
+ last_name: member.last_name ?? '',
+ role_ids: member.roles.map((r) => r.id),
+ },
+ })
+
+ async function onSubmit(values: EditFormValues) {
+ try {
+ await updateMutation.mutateAsync({
+ id: member.id,
+ params: {
+ first_name: values.first_name || undefined,
+ last_name: values.last_name || undefined,
+ role_ids: values.role_ids,
+ },
+ })
+ toast.success('Staff updated')
+ onOpenChange(false)
+ } catch (err) {
+ toast.error(err instanceof Error ? err.message : 'Failed to update staff')
+ }
+ }
+
+ return (
+ <Dialog
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) {
+ form.reset({
+ first_name: member.first_name ?? '',
+ last_name: member.last_name ?? '',
+ role_ids: member.roles.map((r) => r.id),
+ })
+ }
+ onOpenChange(next)
+ }}
+ >
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>Edit staff member</DialogTitle>
+ <DialogDescription>{member.email}</DialogDescription>
+ </DialogHeader>
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ <DialogBody className="flex flex-col gap-4">
+ <div className="grid grid-cols-2 gap-3">
+ <Field>
+ <FieldLabel htmlFor="edit-first-name">First name</FieldLabel>
+ <Input id="edit-first-name" {...form.register('first_name')} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="edit-last-name">Last name</FieldLabel>
+ <Input id="edit-last-name" {...form.register('last_name')} />
+ </Field>
+ </div>
+ <Field>
+ <FieldLabel>Roles for this store</FieldLabel>
+ <Controller
+ name="role_ids"
+ control={form.control}
+ render={({ field }) => (
+ <RoleCheckboxGroup
+ roles={roles?.data ?? []}
+ value={field.value}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ {form.formState.errors.role_ids && (
+ <p className="text-sm text-destructive">{form.formState.errors.role_ids.message}</p>
+ )}
+ </Field>
+ </DialogBody>
+ <DialogFooter>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ Cancel
+ </Button>
+ <Button type="submit" size="sm" disabled={form.formState.isSubmitting}>
+ {form.formState.isSubmitting ? 'Saving…' : 'Save'}
+ </Button>
+ </DialogFooter>
+ </form>
+ </DialogContent>
+ </Dialog>
+ )
+}
+
+// Minimal multi-select for roles. Spree core only ships `admin` today, so a
+// vertical checkbox list is plenty; we'll graduate to a richer picker once
+// roles diversify.
+function RoleCheckboxGroup({
+ roles,
+ value,
+ onChange,
+}: {
+ roles: Role[]
+ value: string[]
+ onChange: (next: string[]) => void
+}) {
+ function toggle(id: string) {
+ onChange(value.includes(id) ? value.filter((v) => v !== id) : [...value, id])
+ }
+
+ if (roles.length === 0) {
+ return <p className="text-sm text-muted-foreground">No roles available.</p>
+ }
+
+ return (
+ <div className="flex flex-col gap-1.5 rounded-md border border-border p-3">
+ {roles.map((role) => {
+ const checked = value.includes(role.id)
+ return (
+ <label
+ key={role.id}
+ className="flex cursor-pointer items-center gap-2 text-sm capitalize"
+ >
+ <input
+ type="checkbox"
+ checked={checked}
+ onChange={() => toggle(role.id)}
+ className="size-4 rounded border-border accent-primary"
+ />
+ {role.name}
+ </label>
+ )
+ })}
</div>
)
}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 89b9a7cde8..357dfce68d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -72,6 +72,9 @@ importers:
lucide-react:
specifier: ^1.14.0
version: 1.14.0([email protected])
+ next-themes:
+ specifier: ^0.4.6
react:
specifier: ^19.2.5
version: 19.2.5
@@ -2944,6 +2947,12 @@ packages:
resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
engines: {node: '>= 0.6'}
+ resolution: {integrity: sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA==}
+ peerDependencies:
+ react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+ react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
+
resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
engines: {node: '>=10.5.0'}
@@ -6425,6 +6434,11 @@ snapshots:
+ dependencies:
+ react: 19.2.5
+ react-dom: 19.2.5([email protected])
+
diff --git a/spree/api/app/controllers/spree/api/v3/admin/admin_users_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/admin_users_controller.rb
new file mode 100644
index 0000000000..1eedc0ab68
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/admin_users_controller.rb
@@ -0,0 +1,97 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Manages staff for the current store. "Staff" = admin users with at
+ # least one `Spree::RoleUser` whose `resource` is the current store.
+ # The legacy controller hard-deletes the global account on destroy;
+ # this v3 endpoint instead removes the per-store `RoleUser` rows so
+ # the user keeps their account (and access to other stores).
+ class AdminUsersController < ResourceController
+ scoped_resource :settings
+
+ # POST is not exposed — staff are created via invitations.
+ def create
+ head :method_not_allowed
+ end
+
+ # DELETE /api/v3/admin/admin_users/:id
+ # Removes role assignments for the current store rather than deleting
+ # the account globally. The user keeps access to any other stores.
+ def destroy
+ authorize!(:destroy, @resource)
+ @resource.role_users.where(resource: current_store).destroy_all
+ head :no_content
+ end
+
+ # PATCH allows updating identity fields and replacing the user's
+ # roles for this store. `role_ids` accepts prefixed IDs and is
+ # applied via `add_role`/`remove_role` so the change is scoped to
+ # `current_store` and never touches other-store assignments.
+ def update
+ authorize!(:update, @resource)
+
+ attrs = identity_params
+ if @resource.update(attrs)
+ apply_role_ids(role_ids_param) if params.key?(:role_ids)
+ render json: serialize_resource(@resource)
+ else
+ render_validation_error(@resource.errors)
+ end
+ end
+
+ protected
+
+ def model_class
+ Spree.admin_user_class
+ end
+
+ def serializer_class
+ Spree.api.admin_admin_user_serializer
+ end
+
+ def collection_includes
+ [{ role_users: :role }]
+ end
+
+ # Restrict to users with a role assignment on the current store.
+ # `accessible_by` enforces CanCanCan on top.
+ def scope
+ model_class.
+ joins(:role_users).
+ where(spree_role_users: { resource: current_store }).
+ distinct.
+ accessible_by(current_ability, :show)
+ end
+
+ private
+
+ def identity_params
+ params.permit(:first_name, :last_name)
+ end
+
+ def role_ids_param
+ ids = Array(params[:role_ids])
+ ids.map { |id| Spree::PrefixedId.prefixed_id?(id) ? Spree::PrefixedId.decode_prefixed_id(id) : id }.compact
+ end
+
+ # Reconcile the user's roles on this store to match `desired_role_ids`.
+ # Adds missing assignments and removes extras — no-op for unchanged.
+ def apply_role_ids(desired_role_ids)
+ current = @resource.role_users.where(resource: current_store).pluck(:role_id).map(&:to_s)
+ target = desired_role_ids.map(&:to_s)
+
+ (target - current).each do |role_id|
+ role = Spree::Role.find_by(id: role_id)
+ @resource.role_users.find_or_create_by!(role: role, resource: current_store) if role
+ end
+
+ (current - target).each do |role_id|
+ @resource.role_users.where(role_id: role_id, resource: current_store).destroy_all
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
new file mode 100644
index 0000000000..9b794ed85a
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/api_keys_controller.rb
@@ -0,0 +1,55 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ class ApiKeysController < ResourceController
+ scoped_resource :settings
+
+ # PATCH /api/v3/admin/api_keys/:id/revoke
+ # Marks the key revoked rather than deleting it — the row stays so
+ # audit logs and `created_by`/`revoked_by` remain queryable. Hard
+ # deletion is available via `destroy` for cleanup.
+ def revoke
+ @resource = find_resource
+ authorize!(:update, @resource)
+
+ @resource.revoke!(try_spree_current_user)
+ render json: serialize_resource(@resource)
+ end
+
+ protected
+
+ def model_class
+ Spree::ApiKey
+ end
+
+ def serializer_class
+ Spree.api.admin_api_key_serializer
+ end
+
+ def scope
+ current_store.api_keys.accessible_by(current_ability, :show)
+ end
+
+ # Stamp the creating user; key generation (token, prefix, digest)
+ # happens in `before_validation :generate_token` on the model.
+ def build_resource
+ scope.new(permitted_params).tap do |key|
+ key.created_by = try_spree_current_user
+ end
+ end
+
+ # `key_type` is set on create only — flipping a publishable key to a
+ # secret one (or vice versa) would invalidate every consumer of the
+ # plaintext token. We strip it on update so that's impossible to do
+ # by accident through the API.
+ def permitted_params
+ attrs = params.permit(:name, :key_type, scopes: [])
+ attrs.delete(:key_type) if action_name == 'update'
+ attrs
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/invitations_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/invitations_controller.rb
new file mode 100644
index 0000000000..b7ef87cd3e
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/invitations_controller.rb
@@ -0,0 +1,70 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Manages staff invitations for the current store. Each invitation
+ # carries an email + role; on accept, a `Spree::RoleUser` is created
+ # via the invitation's `after_accept` callback and the invitee
+ # becomes a member of the staff list for this store.
+ class InvitationsController < ResourceController
+ scoped_resource :settings
+
+ # PATCH /api/v3/admin/invitations/:id/resend
+ # Issues a fresh token + email for an existing pending invitation.
+ # The model's `resend!` is responsible for resetting `expires_at`
+ # and dispatching the mailer.
+ def resend
+ @resource = find_resource
+ authorize!(:update, @resource)
+
+ @resource.resend!
+ render json: serialize_resource(@resource)
+ end
+
+ # Invitations are immutable post-create — UI calls `resend` for
+ # token rotation, `destroy` to revoke. Clearing the action set
+ # keeps the surface honest if a client ever fires PATCH directly.
+ def update
+ head :method_not_allowed
+ end
+
+ protected
+
+ def model_class
+ Spree::Invitation
+ end
+
+ def serializer_class
+ Spree.api.admin_invitation_serializer
+ end
+
+ def collection_includes
+ [:role, :inviter]
+ end
+
+ def scope
+ Spree::Invitation.
+ where(resource: current_store).
+ accessible_by(current_ability, :show)
+ end
+
+ def build_resource
+ scope.new(permitted_params).tap do |invitation|
+ invitation.resource = current_store
+ invitation.inviter = try_spree_current_user
+ end
+ end
+
+ # `email` and `role_id` are flat — `role_id` accepts a prefixed ID.
+ def permitted_params
+ attrs = params.permit(:email, :role_id)
+ if attrs[:role_id].present? && Spree::PrefixedId.prefixed_id?(attrs[:role_id])
+ attrs[:role_id] = Spree::PrefixedId.decode_prefixed_id(attrs[:role_id])
+ end
+ attrs
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/roles_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/roles_controller.rb
new file mode 100644
index 0000000000..756c1b852d
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/roles_controller.rb
@@ -0,0 +1,29 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Read-only list of roles available for staff role pickers (invite +
+ # edit forms). Roles are global, not per-store; CRUD is handled
+ # outside the SPA today and may grow into a richer permissions UI
+ # later. The controller ignores `current_store` for that reason.
+ class RolesController < ResourceController
+ scoped_resource :settings
+
+ protected
+
+ def model_class
+ Spree::Role
+ end
+
+ def serializer_class
+ Spree.api.admin_role_serializer
+ end
+
+ def scope
+ Spree::Role.accessible_by(current_ability, :show)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/admin_user_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/admin_user_serializer.rb
index 9f4e83bd06..bd2e9e69fc 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/admin_user_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/admin_user_serializer.rb
@@ -3,11 +3,26 @@ module Spree
module V3
module Admin
class AdminUserSerializer < V3::BaseSerializer
- typelize email: :string, first_name: [:string, nullable: true],
- last_name: [:string, nullable: true]
+ typelize email: :string,
+ first_name: [:string, nullable: true],
+ last_name: [:string, nullable: true],
+ roles: 'Array<{ id: string; name: string }>'
attributes :email, :first_name, :last_name,
created_at: :iso8601, updated_at: :iso8601
+
+ # Roles assigned to this user *for the current store*. Each store
+ # gets its own role set via `Spree::RoleUser`, so this attribute is
+ # scoped against `current_store` rather than returning every role
+ # the user might have on other stores. Block receives `params`
+ # only when Alba passes it through the `serializer_params` hash —
+ # we fall back to `Spree::Current.store` if not.
+ attribute :roles do |user, params|
+ store = params&.dig(:store) || Spree::Current.store
+ scope = user.role_users
+ scope = scope.where(resource: store) if store
+ scope.includes(:role).map { |ru| { id: ru.role.prefixed_id, name: ru.role.name } }
+ end
end
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/api_key_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/api_key_serializer.rb
new file mode 100644
index 0000000000..c242721622
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/api_key_serializer.rb
@@ -0,0 +1,42 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Admin API serializer for {Spree::ApiKey}.
+ #
+ # Never exposes `token` or `token_digest` — only the 12-char
+ # `token_prefix` (e.g. `sk_abc123def`) so existing keys can be
+ # identified in the UI without leaking material that would let an
+ # attacker make requests. The full plaintext token is delivered
+ # exactly once, as the response body of `POST /api/v3/admin/api_keys`,
+ # via {#plaintext_token} below — it is `nil` everywhere else.
+ class ApiKeySerializer < V3::BaseSerializer
+ typelize name: :string,
+ key_type: :string,
+ token_prefix: [:string, nullable: true],
+ plaintext_token: [:string, nullable: true],
+ scopes: [:string, multi: true],
+ revoked_at: [:string, nullable: true],
+ last_used_at: [:string, nullable: true],
+ created_by_email: [:string, nullable: true]
+
+ attributes :name, :key_type, :token_prefix, :scopes,
+ created_at: :iso8601, updated_at: :iso8601,
+ revoked_at: :iso8601, last_used_at: :iso8601
+
+ # Returned only on the create response — `plaintext_token` is held in
+ # memory on the model after `generate_token` and is never persisted
+ # for secret keys, so we serialize it whenever it's available rather
+ # than gating on the action.
+ attribute :plaintext_token do |key|
+ key.plaintext_token
+ end
+
+ attribute :created_by_email do |key|
+ key.created_by&.email
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/invitation_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/invitation_serializer.rb
new file mode 100644
index 0000000000..e2c7ff804d
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/invitation_serializer.rb
@@ -0,0 +1,35 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Admin API serializer for {Spree::Invitation}. Used on the staff
+ # settings page to list pending invitations and to surface the result
+ # of `POST /admin/invitations`. Inviter and invitee are flattened to
+ # email-only — the full polymorphic identities aren't useful to the UI.
+ class InvitationSerializer < V3::BaseSerializer
+ typelize email: :string,
+ status: :string,
+ role_id: [:string, nullable: true],
+ role_name: [:string, nullable: true],
+ inviter_email: [:string, nullable: true],
+ expires_at: [:string, nullable: true]
+
+ attributes :email, :status,
+ created_at: :iso8601, updated_at: :iso8601, expires_at: :iso8601
+
+ attribute :role_id do |invitation|
+ invitation.role&.prefixed_id
+ end
+
+ attribute :role_name do |invitation|
+ invitation.role&.name
+ end
+
+ attribute :inviter_email do |invitation|
+ invitation.inviter&.email
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/role_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/role_serializer.rb
new file mode 100644
index 0000000000..2b5673604f
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/role_serializer.rb
@@ -0,0 +1,17 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Admin API serializer for {Spree::Role}. Read-only — used to populate
+ # the role picker on the staff invite/edit forms. Spree core ships
+ # with a single `admin` role today; richer role/permission management
+ # is on the roadmap.
+ class RoleSerializer < V3::BaseSerializer
+ typelize name: :string
+
+ attributes :name, created_at: :iso8601, updated_at: :iso8601
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 78e1213f08..d23305a237 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -116,6 +116,20 @@ Spree::Core::Engine.add_routes do
# Store Settings
resource :store, only: [:show, :update], controller: 'store'
+ # Staff & access (invitations, admin users, roles, API keys)
+ resources :admin_users, only: [:index, :show, :update, :destroy]
+ resources :invitations, only: [:index, :show, :create, :destroy] do
+ member do
+ patch :resend
+ end
+ end
+ resources :api_keys, only: [:index, :show, :create, :destroy] do
+ member do
+ patch :revoke
+ end
+ end
+ resources :roles, only: [:index, :show]
+
# Direct Uploads (Active Storage)
resources :direct_uploads, only: [:create]
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index d4972b32a1..c3a55b64cf 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -197,6 +197,9 @@ module Spree
admin_payment_source_serializer: 'Spree::Api::V3::Admin::PaymentSourceSerializer',
admin_digital_link_serializer: 'Spree::Api::V3::Admin::DigitalLinkSerializer',
admin_store_serializer: 'Spree::Api::V3::Admin::StoreSerializer',
+ admin_api_key_serializer: 'Spree::Api::V3::Admin::ApiKeySerializer',
+ admin_invitation_serializer: 'Spree::Api::V3::Admin::InvitationSerializer',
+ admin_role_serializer: 'Spree::Api::V3::Admin::RoleSerializer',
# platform serializers
platform_metafield_serializer: 'Spree::Api::V2::Platform::MetafieldSerializer',
diff --git a/spree/api/lib/spree/api/openapi/schema_helper.rb b/spree/api/lib/spree/api/openapi/schema_helper.rb
index 3efc17325c..f4e7b39bbd 100644
--- a/spree/api/lib/spree/api/openapi/schema_helper.rb
+++ b/spree/api/lib/spree/api/openapi/schema_helper.rb
@@ -135,6 +135,15 @@ module Spree
quantity: { type: :integer, description: 'Quantity in this fulfillment', example: 2 }
},
required: %w[item_id variant_id quantity]
+ },
+ AdminUserRoleAssignment: {
+ type: :object,
+ description: 'A role assignment for the current store on a staff member',
+ properties: {
+ id: { type: :string, description: 'Prefixed role ID', example: 'role_abc123' },
+ name: { type: :string, description: 'Role name', example: 'admin' }
+ },
+ required: %w[id name]
}
}
end
@@ -179,6 +188,7 @@ module Spree
end
patch_cart_schema(schemas)
patch_fulfillment_schema(schemas)
+ patch_admin_user_schema(schemas)
schemas
end
end
@@ -209,6 +219,24 @@ module Spree
end
end
+ # Same Array<{...}> issue as cart/fulfillment — patch AdminUser#roles
+ # to reference the AdminUserRoleAssignment component schema.
+ def patch_admin_user_schema(schemas)
+ admin_user = schemas['AdminUser'] || schemas[:AdminUser]
+ return unless admin_user
+
+ props = admin_user[:properties]
+ return unless props
+
+ roles_key = props.key?('roles') ? 'roles' : :roles
+ if props[roles_key]
+ props[roles_key] = {
+ type: :array,
+ items: { '$ref' => '#/components/schemas/AdminUserRoleAssignment' }
+ }
+ end
+ end
+
# Typelizer cannot represent Array<{...}> inline object types in OpenAPI,
# so we patch Fulfillment#items to reference the FulfillmentManifestItem component schema.
def patch_fulfillment_schema(schemas)
diff --git a/spree/api/spec/integration/spree/api/v3/admin/admin_users_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/admin_users_spec.rb
new file mode 100644
index 0000000000..e9d355d9b1
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/admin_users_spec.rb
@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Staff API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:admin_role) { Spree::Role.default_admin_role }
+
+ # The shared `admin_user` factory creates a RoleUser via its `after_create`
+ # callback, but the resource defaults to `Spree::Current.store`, which may
+ # not be set during request specs. We explicitly create the staff member
+ # and pin the role assignment to `store` so the staff list returns it.
+ let!(:staff_member) do
+ user = admin_user
+ user.role_users.find_or_create_by!(role: admin_role, resource: store)
+ user
+ end
+
+ path '/api/v3/admin/admin_users' do
+ get 'List staff' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns admin users with at least one role assignment on the current store.'
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const { data: staff } = await client.adminUsers.list()
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'staff found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].pluck('id')).to include(staff_member.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/admin_users/{id}' do
+ let(:id) { staff_member.prefixed_id }
+
+ get 'Show a staff member' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const staff = await client.adminUsers.get('admin_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'staff member found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(staff_member.prefixed_id)
+ expect(data['roles']).to be_an(Array)
+ expect(data['roles'].pluck('name')).to include('admin')
+ end
+ end
+ end
+
+ patch 'Update a staff member' do
+ tags 'Configuration'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Updates name fields and reassigns roles for the current store. ' \
+ '`role_ids` is a complete replacement — roles not in the array are removed for this store.'
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const staff = await client.adminUsers.update('admin_xxx', {
+ first_name: 'Ada',
+ role_ids: ['role_xxx']
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ first_name: { type: :string, example: 'Ada' },
+ last_name: { type: :string, example: 'Lovelace' },
+ role_ids: { type: :array, items: { type: :string } }
+ }
+ }
+
+ response '200', 'staff member updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { first_name: 'Renamed', role_ids: [admin_role.prefixed_id] } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['first_name']).to eq('Renamed')
+ expect(data['roles'].pluck('name')).to include('admin')
+ end
+ end
+ end
+
+ delete 'Remove a staff member from this store' do
+ tags 'Configuration'
+ security [api_key: [], bearer_auth: []]
+ description "Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores."
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ await client.adminUsers.delete('admin_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'staff removed from store' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ # Account still exists; only the per-store RoleUser is gone.
+ expect(Spree.admin_user_class.exists?(staff_member.id)).to be true
+ expect(staff_member.role_users.where(resource: store).exists?).to be false
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb
new file mode 100644
index 0000000000..5510fa8c6a
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/api_keys_spec.rb
@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin API Keys API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:publishable_key) { create(:api_key, :publishable, store: store, name: 'Storefront key') }
+ let!(:secret_key_record) do
+ create(:api_key, :secret, store: store, name: 'Backend integration')
+ end
+
+ path '/api/v3/admin/api_keys' do
+ get 'List API keys' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns publishable and secret API keys for the current store. ' \
+ 'Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.'
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const { data: keys } = await client.apiKeys.list()
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'API keys found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].pluck('name')).to include('Storefront key', 'Backend integration')
+
+ # Secret keys never leak `token` or `token_digest`. Publishable keys
+ # serialize their plaintext token via `token_prefix` is fine.
+ data['data'].each do |k|
+ expect(k.keys).not_to include('token', 'token_digest')
+ end
+ end
+ end
+ end
+
+ post 'Create an API key' do
+ tags 'Configuration'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; ' \
+ 'publishable keys expose their token on every read since they are intended for client-side use.'
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const key = await client.apiKeys.create({
+ name: 'Backend integration',
+ key_type: 'secret',
+ scopes: ['read_orders', 'write_orders']
+ })
+ // `key.plaintext_token` is available only on this response.
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[name key_type],
+ properties: {
+ name: { type: :string, example: 'Backend integration' },
+ key_type: { type: :string, enum: %w[publishable secret] },
+ scopes: { type: :array, items: { type: :string }, example: %w[read_orders write_orders] }
+ }
+ }
+
+ response '201', 'secret key created — plaintext token returned once' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { name: 'CI key', key_type: 'secret', scopes: ['read_orders'] } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('CI key')
+ expect(data['key_type']).to eq('secret')
+ expect(data['plaintext_token']).to be_present
+ expect(data['plaintext_token']).to start_with('sk_')
+ expect(data['token_prefix']).to eq(data['plaintext_token'][0, 12])
+ end
+ end
+
+ response '422', 'validation error' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { name: '', key_type: 'secret' } }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/api_keys/{id}' do
+ let(:id) { publishable_key.prefixed_id }
+
+ get 'Show an API key' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const key = await client.apiKeys.get('key_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'API key found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['id']).to eq(publishable_key.prefixed_id)
+ end
+ end
+ end
+
+ delete 'Delete an API key' do
+ tags 'Configuration'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ await client.apiKeys.delete('key_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'API key deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/api_keys/{id}/revoke' do
+ let(:id) { secret_key_record.prefixed_id }
+
+ patch 'Revoke an API key' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.'
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const key = await client.apiKeys.revoke('key_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'API key revoked' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['revoked_at']).to be_present
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/invitations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/invitations_spec.rb
new file mode 100644
index 0000000000..b7e33815e6
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/invitations_spec.rb
@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Invitations API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:admin_role) { Spree::Role.default_admin_role }
+ let!(:invitation) do
+ create(:invitation, resource: store, role: admin_role, inviter: admin_user)
+ end
+
+ path '/api/v3/admin/invitations' do
+ get 'List invitations' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns invitations for the current store, including pending and accepted.'
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const { data: invitations } = await client.invitations.list()
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'invitations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].pluck('id')).to include(invitation.prefixed_id)
+ end
+ end
+ end
+
+ post 'Create an invitation' do
+ tags 'Configuration'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; ' \
+ 'on accept, a `RoleUser` is created via the invitation\'s `after_accept` callback.'
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const invitation = await client.invitations.create({
+ email: '[email protected]',
+ role_id: 'role_xxx'
+ })
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[email role_id],
+ properties: {
+ email: { type: :string, example: '[email protected]' },
+ role_id: { type: :string, example: 'role_xxx' }
+ }
+ }
+
+ response '201', 'invitation created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { email: '[email protected]', role_id: admin_role.prefixed_id } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['email']).to eq('[email protected]')
+ expect(data['status']).to eq('pending')
+ expect(data['role_name']).to eq('admin')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/invitations/{id}' do
+ let(:id) { invitation.prefixed_id }
+
+ delete 'Revoke an invitation' do
+ tags 'Configuration'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ await client.invitations.delete('inv_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '204', 'invitation revoked' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/invitations/{id}/resend' do
+ let(:id) { invitation.prefixed_id }
+
+ patch 'Resend an invitation' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Issues a fresh token and dispatches the invitation email again.'
+ admin_scope :write, :settings
+
+ admin_sdk_example <<~JS
+ const invitation = await client.invitations.resend('inv_xxx')
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :id, in: :path, type: :string, required: true
+
+ response '200', 'invitation resent' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/roles_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/roles_spec.rb
new file mode 100644
index 0000000000..7e97ec1e9d
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/roles_spec.rb
@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Roles API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:admin_role) { Spree::Role.default_admin_role }
+
+ path '/api/v3/admin/roles' do
+ get 'List roles' do
+ tags 'Configuration'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the roles available for staff role pickers. Roles are global, not per-store.'
+ admin_scope :read, :settings
+
+ admin_sdk_example <<~JS
+ const { data: roles } = await client.roles.list()
+ JS
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'roles found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data']).to be_an(Array)
+ expect(data['data'].pluck('name')).to include('admin')
+ end
+ end
+ end
+ end
+end