Authenticate Admin API requests with keys and JWTs

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.

Secret API key

Pass the key via the X-Spree-Api-Key header:

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

# 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

Secret API keys are prefixed with sk_. Create them with the Spree CLI or in the Spree admin under Settings → API Keys:

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 below); pass --scopes read_all for a read-only key that can access everything.

{
  "error": {
    "code": "authentication_required",
    "message": "Authentication required"
  }
}

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

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

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"}'

Token refresh

JWT tokens expire after 1 hour by default. Refresh them with the current token:

const { token } = await client.auth.refresh({ token: currentToken })

curl -X POST 'https://store.example.com/api/v3/admin/auth/refresh' \
  -H 'X-Spree-Api-Key: sk_xxx' \
  -H 'Authorization: Bearer <current_jwt_token>'

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

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:

{
  "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: CanCanCan abilities

JWT-authenticated admin users are authorized via CanCanCan abilities derived from their Spree::Roles. The SPA uses this fine-grained model to render UI conditionally; partial-permission staff users see only the resources their role grants.

If the caller lacks permission for a specific action, the API returns 403 Forbidden:

{
  "error": {
    "code": "access_denied",
    "message": "You are not authorized to perform this action"
  }
}

Authentication summary