Getting started

Authentication and scopes

Access tokens, scopes and how staff roles narrow them.

Every Admin API request carries an access token in the X-Ostorya-Access-Token header. Tokens are stored hashed (SHA-256): Ostorya can't show one again, and a leaked database doesn't leak tokens.

curl -X POST https://ostorya.com/api/admin/2026-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Ostorya-Access-Token: $OSTORYA_TOKEN" \
  -d '{"query":"{ shop { name currencyCode } }"}'

How an app gets a token#

Apps get tokens from the desktop through App Bridge. When the merchant opens your app, the desktop issues a token for this shop, this app and this staff member, valid for 15 minutes. bridge.graphql() asks for a new one when it expires, so you never handle expiry yourself. See App Bridge.

To call the API from your own server, send the token from the browser to your backend with each request and use it there. Don't store it: it expires in 15 minutes and is only valid for the staff member who opened your app.

Not available yet: offline tokens and OAuth

Long-lived tokens for background jobs, a self-serve install (OAuth) flow and webhooks are planned. Until then an app works while a staff member has it open. If your app needs background access, tell us at [email protected].

Scopes#

Each app is registered with the scopes it needs, named like Shopify's. write_x includes read_x. A field or mutation that needs a scope your token lacks returns ACCESS_DENIED with the missing scope in extensions.requiredAccess.

read_productswrite_productsread_orderswrite_ordersread_customerswrite_customersread_fulfillmentswrite_fulfillmentsread_discountswrite_discountsread_inventorywrite_inventoryread_themeswrite_themesread_online_store_pageswrite_online_store_pagesread_fileswrite_filesread_checkoutsread_reportsread_apps

Staff roles narrow the token#

A token is the app's scopes narrowed to the role of the staff member who opened it:

Role	What the token can do
Owner, Admin	Everything the app was granted.
Agent (call center)	Only `read/write_orders`, `read_customers`, `read_products`, `read_inventory`, `read_discounts`, `read_fulfillments`, and only the orders assigned to them.

Tokens of a deactivated staff member stop working immediately. Design your app so a missing scope shows a clear message instead of an error page: an agent opening Ads Manager can't read reports.

Errors#

HTTP / code	Meaning
`401 UNAUTHORIZED`	Missing, unknown or expired token. With App Bridge, call again: it fetches a fresh token.
`ACCESS_DENIED`	The token lacks a scope. extensions.requiredAccess names it.
`MAX_COST_EXCEEDED`	The query is too expensive. See Query cost.

PreviousBuild on Ostorya NextAPI versions