Developers
API keys & authentication
Every request is made with an API key that you create in Vanix. A key belongs to your store, and you choose what it can do.
Creating a key
- In Vanix, go to Settings. The API keys card lists your keys.
- Choose Create API key.
- Give it a Name: the integration that will use it, so you can tell keys apart. Up to 60 characters.
- Choose its Access: Read only, Full access, or Custom to choose No access, Read or Read & write for each area.
- Choose Create key, and copy the key.
The key is shown only once. Store it somewhere safe, such as your integration's secret settings. If you lose it, revoke it and make a new one.
Live keys start with vx_live_. You can have up to 10 keys at once.
What a key can do
Each area has a read scope, and most have a write scope, which includes reading.
| Scope | Allows |
|---|---|
subscriptions:read | Reading subscriptions, their orders, cancellation attempts and activity, the store's activity, billing runs, and where a skip or a frequency change would leave a subscription. |
subscriptions:write | Every change to a subscription, and the previews that price a change before you make it. |
customers:read | Reading customers and their activity. Customers are Shopify's records, so there's no write scope. |
Any key can read /v1/shop, to check it works. A request the key's scopes don't cover is refused with 403 insufficient_scope, and the error's requiredScope names the scope it needed.
Full access means every scope there is when you choose it. When the API gains a new area, existing keys don't gain it: edit a key to add it.
Authenticating
Send the key in the Authorization header of every request:
Authorization: Bearer vx_live_…Only the header works. A key in the URL is refused with key_in_query, because URLs end up in logs. A missing header is missing_api_key, and a key that's been revoked, or was never a key, is invalid_api_key.
Keep keys on your server
Anyone with a key can act on your subscriptions as far as its access goes. Use keys from your own server only:
- Never in your theme, your storefront's JavaScript, or anything else that runs in a browser. The API refuses requests from browsers on other sites, so a key used there fails while you're building it rather than leaking later.
- Never in a code repository. Keep it in an environment variable or your platform's secret settings.
- Give each integration its own key, with only the access it needs, so you can revoke one without stopping the others.
If a key may have leaked, revoke it straight away and make a new one.
Editing and revoking
The API keys card shows each key's name, the start of the key, its access, when it was made, and when it was last used.
- Edit changes a key's name and access. The change applies from the key's next request. The key itself stays the same.
- Revoke stops a key. Anything using it stops working at once. This can't be undone, but you can make a new key.
Creating, editing and revoking a key are recorded in your store's activity. Changes made with a key show on the subscription as By API key with the key's name.
If you uninstall Vanix
Every key is revoked when you uninstall. If you reinstall, create new keys.
Checking a key
The store a key belongs to, and the key
GET /v1/shop
The first call to make with a new key, to check it works. Needs no scope.
Request
curl "https://api.vanixcommerce.com/v1/shop" \
-H "Authorization: Bearer $VANIX_API_KEY"Response
{
"shop": {
"domain": "example.myshopify.com",
"timeZone": "America/Denver",
"plan": {
"handle": "growth",
"name": "Growth"
},
"currencyCode": "USD",
"taxesIncluded": false
},
"apiKey": {
"id": "3f6c2b1e-8d4a-4c7e-9f1a-2b3c4d5e6f70",
"name": "Warehouse sync",
"prefix": "vx_live_4f9Q",
"scopes": ["subscriptions:read", "customers:read"]
},
"environment": "live"
}Response fields
| Field | Type | Description |
|---|---|---|
shop | object | |
shop.domain | string | |
shop.timeZone | string | The zone date-only fields are in. |
shop.plan | object or null | |
shop.plan.handle | string | |
shop.plan.name | string | |
shop.currencyCode | string or null | |
shop.taxesIncluded | boolean or null | Whether the store's prices include tax, by default. Markets can price tax-inclusive per country, so this is not a promise about every subscription; rely on a subscription's totals.total. Null when Shopify could not be read. |
apiKey | object | |
apiKey.id | string | |
apiKey.name | string | |
apiKey.prefix | string | |
apiKey.scopes | array of string | |
environment | string | One of live, test. |