One API that answers only what you were allowed
Apps call a GraphQL endpoint with their token. Each field names the scope it needs, and a query outside the app's scopes is refused with SCOPE_DENIED and written to the audit log.
Rider Sync · GraphQL
/api/apps/graphql
- query
- orders(first: 5) { nodes { id totalMinor status } }
- scope
- read:orders · granted
- then
- parties(ids: [412]) { name phone }
Audit log
- orders · 5 nodes returned 200 OK
- parties · scope not granted, written to the audit log SCOPE_DENIED
In short
Apps read and write through POST /api/apps/graphql, where every field checks the scopes the merchant granted, for example orders requires read:orders. A request without the scope is refused with SCOPE_DENIED and recorded in the audit log, and app calls are limited to 60 a minute per app.
The problem it solves
An API key that opens everything turns every app into a copy of your database. Scopes only mean something if the API enforces them on every field.
How it works
4 steps, start to finish
-
1
Install grants scopes
The merchant approves the scopes on the consent screen.
-
2
Call the endpoint
Send GraphQL to /api/apps/graphql with the app token.
-
3
Scopes are checked
Each field checks its scope before it answers.
-
4
Denials are recorded
A missing scope returns SCOPE_DENIED and lands in the audit log.
In detail
What scoped graphql API does for you
-
Real queries
orders, catalogItems, parties, locations, discounts, platformSettings and more.
-
Mutations
ledgerPost, ledgerReverse, ensureParties and ensureLocations.
-
Scope per field
The schema documents the scope each field requires.
-
Paged results
Connections with nodes and pageInfo, filtered by date or status.
-
Rate limits
60 requests a minute per app.
-
The field is refused with SCOPE_DENIED, and the denial is written to the audit log.
-
Older REST routes still exist but are deprecated in favour of GraphQL.
-
In minor units, such as totalMinor and paidMinor on an order.
Works together with
- The install screen lists every scope an app asks for before it gets access.
- Platform events delivered to your app, with a delivery log and replay.
- Public documentation for building apps, plus an API reference with Postman and OpenAPI exports.
- A development app installs only on stores you own, for testing or private use.
Scoped GraphQL API · Free to start
Try scoped graphql API on your own business
Set up in a couple of minutes. Your catalogue, orders and books stay yours to export.
- Live in 2 minutes
- Free to start
- No credit card
