Authentication

The REST API uses the same API keys as AI / Agent access. Mint a key, then send it as a bearer token.

The REST API requires the Enhanced plan

API keys work for AI / Agent access independently of the REST gate — but the REST API specifically is an Enhanced-plan feature. A request from a shop that isn’t on Enhanced returns 403 PLAN_REQUIRED, even with a valid key. The plan is checked on every request against your current subscription, before the path is even matched — so a downgrade takes effect immediately.

Get a key

Create an API key in Settings → Connections → API & agent access in the Assemblified admin — the same API keys for REST and your own agent card that serves desktop and CLI AI assistants. The full walkthrough (labels, the one-time reveal, revoking) lives in the Agent-access docs:

API keys (mint, scope, revoke) →

Scopes

Pick the key’s scope when you create it:

Scope	What it allows over REST
Read only	Every GET endpoint — materials, inventory, bills of materials, order breakdowns, work orders, locations, assignees, bill versions.
Read & write	Everything a read key can, plus the five PATCH endpoints: edit a virtual material, set a virtual material’s per-location stock, edit a work order’s header, move a work order to another state, and start a build run.

A PATCH with a read-only key returns 403 FORBIDDEN_SCOPE. A key keeps the scope it was created with; to change it, revoke the key and mint a new one.

A write key can move real stock

Starting a build run pushes the run’s consumption to Shopify. That one endpoint additionally requires the Enhanced plan, but no separate scope — a read & write key is enough. If your integration only needs to edit material fields, that is still all a write key should be used for, and a read key is the right default for anything exploratory.

Tip

Start with a read key unless the integration actually needs to change data. On the /raw-materials endpoints even a write key can only modify virtual (VMAT-*) materials in v1 — Shopify-managed materials are read-only regardless of scope.

Send the token

Put the key in the Authorization header:

curl -s -H "Authorization: Bearer asmk_xxxxxxxx" \
  "https://assemblified.com/api/v1/raw-materials"

• A missing or invalid token returns 401 immediately — before any data is touched.
• A revoked key returns 401. Revoke in Settings → API & agent access at any time.
• The key identifies your shop on its own; there is no shop id in the URL.

Caution

Keep keys server-side. Because auth is a bearer token (not a cookie), there’s no CSRF risk — but a leaked key grants access until you revoke it. Rotate by minting a new key and revoking the old one.

Managing access

Each request is recorded in the audit log (tagged rest:), so you can see which key made which call. Manage and revoke keys from Settings → API & agent access.

Managing access & security →