@spree/docs 0.1.92 → 0.1.93
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -34,11 +34,13 @@ curl -X GET 'https://store.example.com/api/v3/admin/orders' \
|
|
|
34
34
|
Secret API keys are prefixed with `sk_`. Create them in the Spree admin under **Settings → API Keys** or via the Spree CLI:
|
|
35
35
|
|
|
36
36
|
```bash
|
|
37
|
-
spree api-key create --type secret
|
|
38
|
-
spree api-key list
|
|
39
|
-
spree api-key revoke <key_id>
|
|
37
|
+
spree api-key create --type secret --scopes read_orders,write_products # Create a scoped secret key
|
|
38
|
+
spree api-key list # List existing keys
|
|
39
|
+
spree api-key revoke <key_id> # Revoke a key
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
+
Secret keys require at least one scope (see [Permissions](#permissions) below); pass `--scopes read_all` for a read-only key that can access everything.
|
|
43
|
+
|
|
42
44
|
> **WARNING:** If you omit the API key, the API returns `401 Unauthorized`:
|
|
43
45
|
>
|
|
44
46
|
> ```json
|
|
@@ -101,19 +103,32 @@ Authorization works differently depending on which credentials you use.
|
|
|
101
103
|
|
|
102
104
|
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>`.
|
|
103
105
|
|
|
104
|
-
| Scope |
|
|
106
|
+
| Scope | Grants access to |
|
|
105
107
|
|---|---|
|
|
106
|
-
| `read_orders` / `write_orders` | `/orders
|
|
107
|
-
| `read_products` / `write_products` | `/products/*`, `/variants/*`, `/option_types/*`, `/media/*` |
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
108
|
+
| `read_orders` / `write_orders` | `/orders/*` — including nested items and adjustments |
|
|
109
|
+
| `read_products` / `write_products` | `/products/*`, `/variants/*`, `/option_types/*`, `/media/*`, `/prices/*`, `/price_lists/*` |
|
|
110
|
+
| `read_promotions` / `write_promotions` | `/promotions/*` — including nested rules, actions, and coupon codes |
|
|
111
|
+
| `read_customers` / `write_customers` | `/customers/*`, `/customer_groups/*` — including nested addresses and credit cards |
|
|
112
|
+
| `read_payments` / `write_payments` | `/orders/:id/payments` — including capture and void |
|
|
110
113
|
| `read_fulfillments` / `write_fulfillments` | `/orders/:id/fulfillments` |
|
|
111
114
|
| `read_refunds` / `write_refunds` | `/orders/:id/refunds` |
|
|
112
|
-
| `read_gift_cards` / `write_gift_cards` | `/orders/:id/gift_cards` |
|
|
115
|
+
| `read_gift_cards` / `write_gift_cards` | `/gift_cards/*`, `/gift_card_batches/*`, `/orders/:id/gift_cards` |
|
|
113
116
|
| `read_store_credits` / `write_store_credits` | `/customers/:id/store_credits`, `/orders/:id/store_credits` |
|
|
117
|
+
| `read_stock` / `write_stock` | `/stock_locations/*`, `/stock_items/*`, `/stock_transfers/*`, `/stock_reservations/*` |
|
|
114
118
|
| `read_categories` / `write_categories` | `/categories/*` |
|
|
115
|
-
| `read_settings` / `write_settings` | `/
|
|
116
|
-
| `
|
|
119
|
+
| `read_settings` / `write_settings` | Store configuration — `/store`, `/payment_methods/*`, `/markets/*`, `/channels/*`, `/tax_categories/*`, `/countries`, `/custom_field_definitions/*`, `/store_credit_categories/*`, staff management (`/admin_users`, `/invitations`, `/roles`), `/allowed_origins/*` |
|
|
120
|
+
| `read_webhooks` / `write_webhooks` | `/webhook_endpoints/*` — including delivery logs and redelivery |
|
|
121
|
+
| `read_api_keys` / `write_api_keys` | `/api_keys/*` — creating, revoking, and deleting API keys |
|
|
122
|
+
| `read_dashboard` | `/dashboard/*` (analytics; read-only) |
|
|
123
|
+
|
|
124
|
+
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`.
|
|
125
|
+
|
|
126
|
+
**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.
|
|
127
|
+
|
|
128
|
+
Two scopes are deliberately separate from `settings` because they're security-sensitive:
|
|
129
|
+
|
|
130
|
+
- **`webhooks`** — webhook endpoints receive event payloads (orders, customers) at whatever URL they point to, so the ability to create them is its own grant.
|
|
131
|
+
- **`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.
|
|
117
132
|
|
|
118
133
|
Two convenience aliases:
|
|
119
134
|
|