Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: "Authenticate Admin API requests with keys and JWTs"
sidebarTitle: "Authentication"
description: "Authenticate Spree Admin API requests using secret API keys for server-to-server calls or JWT bearer tokens for interactive admin sessions."
---
The Admin API supports two authentication methods: **secret API keys** for server-to-server integrations, and **JWT bearer tokens** for admin SPA / interactive sessions. Every request must include credentials — there is no public surface.
<Warning>
Secret API keys grant full administrative access to your store. **Never embed them in client-side code, mobile apps, or public repositories.** Use them only from secure server environments.
</Warning>
## Secret API key
Pass the key via the `X-Spree-Api-Key` header:
<CodeGroup>
```typescript SDK
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
// The SDK automatically sends the secret key with every request
const { data: products } = await client.products.list()
```
```bash CLI
# Point the CLI at your store + key, then call any endpoint:
export SPREE_BASE_URL='https://store.example.com'
export SPREE_API_KEY='sk_xxx'
spree api get /products
```
</CodeGroup>
Secret API keys are prefixed with `sk_`. Create them with the [Spree CLI](/developer/cli/admin-api) or in the Spree admin under **Settings → API Keys**:
```bash
spree api-key create --type secret --scopes read_orders,write_products # Create a scoped secret key
spree api-key list # List existing keys
spree api-key revoke <key_id> # Revoke a key
```
Secret keys require at least one scope (see [Permissions](#permissions) below); pass `--scopes read_all` for a read-only key that can access everything.
<Warning>
If you omit the API key, the API returns `401 Unauthorized`:
```json
{
"error": {
"code": "authentication_required",
"message": "Authentication required"
}
}
```
</Warning>
## JWT bearer token (admin user)
For interactive admin sessions (the Spree admin SPA, custom dashboards, etc.) authenticate as an admin user and use the returned JWT token for subsequent requests.
### Login
<CodeGroup>
```typescript SDK
const { token, user } = await client.auth.login({
email: '[email protected]',
password: 'secret123',
})
// Reuse the JWT for subsequent requests. setToken is sticky — every
// later call on `client` carries the bearer header automatically.
client.setToken(token)
const orders = await client.orders.list()
```
```bash cURL
curl -X POST 'https://store.example.com/api/v3/admin/auth/login' \
-H 'X-Spree-Api-Key: sk_xxx' \
-H 'Content-Type: application/json' \
-d '{"email": "[email protected]", "password": "secret123"}'
```
</CodeGroup>
### Token refresh
Admin JWT tokens are short-lived — they expire after 5 minutes by default (configurable with `SPREE_ADMIN_JWT_EXPIRATION`, in seconds). Login also sets a refresh token in an HttpOnly cookie scoped to `/api/v3/admin/auth`; it is never returned in the response body. Exchange that cookie for a new access token:
<CodeGroup>
```typescript SDK
// Sends the refresh cookie set at login; the cookie is rotated on every call
const { token } = await client.auth.refresh()
client.setToken(token)
```
```bash cURL
# Log in with -c cookies.txt to store the refresh cookie, then:
curl -X POST 'https://store.example.com/api/v3/admin/auth/refresh' \
-b cookies.txt -c cookies.txt
```
</CodeGroup>
## Permissions
Authorization works differently depending on which credentials you use.
### Secret API keys: scopes
Each secret API key carries a list of **scopes** that grant access to specific resources. Scopes follow a `read_<resource>` / `write_<resource>` convention; `write_<resource>` implies `read_<resource>`.
| Scope | Grants access to |
|---|---|
| `read_orders` / `write_orders` | `/orders/*` — including nested items and adjustments |
| `read_products` / `write_products` | `/products/*`, `/variants/*`, `/option_types/*`, `/prices/*`, `/price_lists/*`, `/catalogs/*`, `/digital_assets/*`, `/imports/*` |
| `read_product_types` / `write_product_types` | `/product_types/*` |
| `read_publishing` / `write_publishing` | Publishing products to channels |
| `read_media` / `write_media` | `/media/*` |
| `read_promotions` / `write_promotions` | `/promotions/*` — including nested rules, actions, and coupon codes |
| `read_customers` / `write_customers` | `/customers/*`, `/customer_groups/*` — including nested addresses and credit cards |
| `read_payments` / `write_payments` | `/orders/:id/payments` — including capture and void |
| `read_fulfillments` / `write_fulfillments` | `/orders/:id/fulfillments` |
| `read_refunds` / `write_refunds` | `/orders/:id/refunds` |
| `read_gift_cards` / `write_gift_cards` | `/gift_cards/*`, `/gift_card_batches/*`, `/orders/:id/gift_cards` |
| `read_store_credits` / `write_store_credits` | `/customers/:id/store_credits`, `/orders/:id/store_credits` |
| `read_stock` / `write_stock` | `/stock_locations/*`, `/stock_levels/*`, `/stock_movements/*`, `/stock_transfers/*`, `/stock_reservations/*`, `/stock_receipts/*` |
| `read_purchasing` / `write_purchasing` | `/suppliers/*`, `/purchase_orders/*`, `/stock_receipts/*` |
| `read_categories` / `write_categories` | `/categories/*` |
| `read_collections` / `write_collections` | `/collections/*` |
| `read_sellers` / `write_sellers` | `/sellers/*`, `/seller_requirements/*` |
| `read_commissions` / `write_commissions` | `/commission_rates/*`, `/commission_lines/*` |
| `read_payouts` / `write_payouts` | `/seller_transfers/*`, `/seller_payouts/*` |
| `read_settings` / `write_settings` | Store configuration — `/store`, `/payment_methods/*`, `/markets/*`, `/channels/*`, `/tax_categories/*`, `/custom_field_definitions/*`, `/allowed_origins/*` |
| `read_staff` / `write_staff` | Staff management — `/admin_users/*`, `/invitations/*`, `/roles/*` |
| `read_delivery_methods` / `write_delivery_methods` | `/delivery_methods/*` — including rules and carrier services |
| `read_package_types` / `write_package_types` | `/package_types/*` |
| `read_integrations` / `write_integrations` | `/integrations/*` |
| `read_webhooks` / `write_webhooks` | `/webhook_endpoints/*` — including delivery logs and redelivery |
| `read_api_keys` / `write_api_keys` | `/api_keys/*` — creating, revoking, and deleting API keys |
| `read_dashboard` | `/dashboard/*` (analytics; read-only) |
| `read_reports` / `write_reports` | Reports, `/saved_reports/*` and report exports |
Custom field **values** are gated by the resource they're attached to: a `write_products` key can manage custom fields on products, variants, and option types; `write_orders` covers order custom fields, and so on. Custom field **definitions** (the schema) are part of `settings`.
**Exports have no scope of their own.** An export is a bulk read, so each export type (`/exports/*`) is gated by the read scope of the resource it exports — `read_customers` lets a key create and download customer exports, `read_promotions` covers coupon-code exports, and so on. The exports list only shows the types the key can read, so a key can never export data it couldn't read through the API directly.
Two scopes are deliberately separate from `settings` because they're security-sensitive:
- **`webhooks`** — webhook endpoints receive event payloads (orders, customers) at whatever URL they point to, so the ability to create them is its own grant.
- **`api_keys`** — credential management. A key holding `write_api_keys` can create new keys, but only with scopes it already holds itself; scopes can never be amplified through the API.
Two convenience aliases:
- **`read_all`** — every `read_*` scope
- **`write_all`** — every `read_*` and `write_*` scope (full admin)
If the key lacks the required scope, the API returns `403 Forbidden`:
```json
{
"error": {
"code": "access_denied",
"message": "API key lacks scope: write_orders",
"details": {
"required_scope": "write_orders"
}
}
}
```
The `details.required_scope` field tells you exactly which scope to add — and `spree api-key create --type secret --scopes <scope>` mints a key that has it. Choose the narrowest set that covers your integration's needs.
### JWT bearer tokens: role permissions
JWT-authenticated admin users pass the same per-controller gate as secret keys. Instead of key scopes, the gate checks the permission keys held by the user's `Spree::Role`s on the current store — the same `read_<resource>` / `write_<resource>` vocabulary. The SPA reads those keys from `GET /api/v3/admin/me` to render UI conditionally; partial-permission staff users see only the resources their role grants.
If the user's role lacks the required key, the API returns `403 Forbidden`:
```json
{
"error": {
"code": "access_denied",
"message": "Missing permission: write_orders",
"details": {
"required_permission": "write_orders"
}
}
}
```
A `403` without `details.required_permission` means the user holds the key but a record-level rule refused the action.
## Authentication summary
| Method | Header | Use case | Authorization |
|---|---|---|---|
| Secret API key | `X-Spree-Api-Key: sk_xxx` | Server-to-server integrations | Scopes |
| JWT token | `Authorization: Bearer <token>` | Interactive admin sessions; SPA | Role permissions |
<Note>
If both headers are present, the JWT token wins: the user's role permissions apply and the key's scopes are ignored. This lets you use `sk_xxx` to bootstrap a session and then issue per-user JWTs for individual admin actions.
</Note>
## Who a write is attributed to
Records that remember who acted on them — an order's `canceler`, `approver`
and `created_by`, a refund's `refunder`, the opener of a return, exchange or
claim, the receiver of a stock delivery — name whichever credential made the
call. A JWT request records the signed-in admin; a secret-key request records
the key itself, so a warehouse connector's write is attributed to the
connector rather than to nobody.
Each of these fields comes as a pair. The `*_id` is a prefixed id, `adm_…`
for a person and `key_…` for a key, and the `*_type` beside it says which:
```json
{
"canceler_id": "key_8QrN3xLq",
"canceler_type": "api_key",
"canceled_at": "2026-09-16T11:04:22Z"
}
```
`*_type` is `admin_user` or `api_key` today, and an extension may register
further kinds, so treat the value as an open list rather than a closed set.
Expanding the association gives the same three facts in one object — `id`,
`type` and a `label` fit to show in a timeline:
<Tabs>
<Tab title="SDK">
```ts
const order = await client.orders.get('or_m3Rp9wXz', { expand: ['canceler'] })
order.canceler // { id: 'key_8QrN3xLq', type: 'api_key', label: 'WMS connector' }
```
</Tab>
<Tab title="cURL">
```bash
curl "https://example.com/api/v3/admin/orders/or_m3Rp9wXz?expand=canceler" \
-H "X-Spree-Api-Key: sk_xxx"
```
</Tab>
</Tabs>
<Note>
Attribution answers *who*, not *through which surface*. A store upgrading from
an earlier release should run `rake spree:upgrade:backfill_actor_types` so
existing records name the kind of actor they already held.
</Note>