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.

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