Authentication · Adyvance Developers

API keys

Keys are made in the admin under Apps → Developer → API keys. Send the key as a Bearer token on every request:

curl "https://app.adyvance.com/_public/v1/orgs/org_…/stores/str_…/products" \
  -H "Authorization: Bearer ady_live_…"

A key looks like one of these:

Prefix	What it is
`ady_live_`	A live key. It reads and changes the shop's real data.
`ady_test_`	A test key. It works while the shop's test mode is on (see below).
`ady_oat_`	An access token that an AI app got through "Sign in with Adyvance". You do not make these by hand; see AI apps.

A request with no key, a wrong key, or a revoked or expired key gets 401:

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "auth.unauthenticated",
    "message": "Send a valid API key as `Authorization: Bearer ady_live_…` (or an AI app's access token).",
    "request_id": "…"
  }
}

Permissions

When you make a key you choose what it may do. Each endpoint in the reference names the permission it needs.

Permission	Allows
`orders.read`	Read orders
`orders.update`	Change an order's status, note and tags
`products.read`	Read products and categories
`products.write`	Create and edit products and variants
`customers.read`	Read customers
`inventory.read`	Read stock levels
`inventory.adjust`	Adjust stock or set it to a count
`webhooks.manage`	List and create webhook endpoints

The admin offers four ready-made sets, or pick your own:

Set	Permissions
Read only	orders.read, products.read, customers.read, inventory.read
Orders	orders.read, orders.update, customers.read, products.read, inventory.read
Catalog	products.read, products.write, inventory.read, inventory.adjust
Full access	all eight

A key never has more power than its maker

A request is allowed only when the key's permissions allow it and the staff member who made the key can still do it today. If their role changes, or they leave the team, their keys lose that power at once. Otherwise the answer is 403 authz.forbidden.

What a key sees follows the same rule. Without permission to see product costs, cost fields are left out; without permission to see customers' contact details, phone numbers and emails come back masked.

Limiting a key to some stores

A shop with more than one store can limit a key to the stores it chooses. Other stores then answer 404 not_found, exactly as if they did not exist. IDs from another shop always answer 404 too, never 403, so a key cannot learn what exists elsewhere.

A key's own request limit

Each key can have its own limit of 10 to 120 requests a minute, below the shop's. Use it to keep a busy script from using up the shop's allowance. See rate limits.

Test mode and test keys

The shop's Owner can turn on test mode on the API keys page. Test keys (ady_test_…) work only while it is on, so a key you handed out while building stops working the moment the Owner turns test mode off. Every response says which kind of key answered, in the Ady-Livemode header (true or false).

Test keys use the real shop data

A test key reads and changes the same products, orders and stock as a live key. Try your changes on a test product or a test order (orders marked "is_test": true).

Keeping keys safe

The full key is shown once, when it is made. Adyvance keeps only a fingerprint (a SHA-256 hash) and cannot show it again.
Use a key only from a server or a script you control. Never put it in a website's code, a mobile app or a public repository.
Keep it in an environment variable or a secret store, not in source files.
Give each app its own key with only the permissions it needs, so you can revoke one without breaking the others.
If a key may have leaked, revoke it in the admin straight away and make a new one.