Skip to main content
V2 Preview — This authentication flow is part of the V2 API preview. Breaking changes may occur.

​
Overview

All V2 Vendor API endpoints require a JWT token passed via the x-access-token header. There are two ways to get a token:
MethodBest ForEndpoint
API KeyIntegrations, scripts, AI agentsPOST /authenticate
Portal LoginCustom vendor portals, mobile appsPOST /portal/auth/login
Use this for programmatic access. Your vendor API key starts with vk_. 
curl -X POST https://staging-api.puppetvendors.com/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "vk_live_YOUR_VENDOR_API_KEY"
  }'

import requests

resp = requests.post(
    "https://staging-api.puppetvendors.com/authenticate",
    json={"apiKey": "vk_live_YOUR_VENDOR_API_KEY"}
)
token = resp.json()["data"]["token"]

const resp = await fetch("https://staging-api.puppetvendors.com/authenticate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ apiKey: "vk_live_YOUR_VENDOR_API_KEY" })
});
const { data } = await resp.json();
const token = data.token;
200
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400,
    "scope": "vendor",
    "permissions": ["orders:read", "products:read", "products:write"],
    "shopDomain": "my-store.myshopify.com",
    "mode": "live",
    "vendorId": "507f1f77bcf86cd799439012"
  }
}
  • scope is always "vendor" for vendor tokens — it’s the token type
  • permissions lists the specific scopes granted to your API key (e.g., orders:read, products:write)

​
Getting a Vendor API Key

You can create API keys in the vendor portal under Settings > API Keys, or your merchant can provide one. See API Keys & Scopes for details on key permissions.

​
Method 2: Portal Login

Use this if you’re building a custom login experience for vendors. 
curl -X POST https://staging-api.puppetvendors.com/portal/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "vendor@example.com",
    "password": "your-password",
    "shopDomain": "my-store.myshopify.com"
  }'
Portal login is rate limited to 5 attempts per 15 minutes per IP address.

​
Using the Token

Include the token in all subsequent requests via the x-access-token header: 
curl -X GET "https://staging-api.puppetvendors.com/orders?first=10" \
  -H "x-access-token: YOUR_JWT_TOKEN"

resp = requests.get(
    "https://staging-api.puppetvendors.com/orders",
    params={"first": 10},
    headers={"x-access-token": token}
)
orders = resp.json()["data"]["items"]

const resp = await fetch("https://staging-api.puppetvendors.com/orders?first=10", {
  headers: { "x-access-token": token }
});
const { data } = await resp.json();

​
Token Expiry & Refresh

Tokens expire after 24 hours (86400 seconds). Use POST /refresh-token with a valid (non-expired) token to get a new one without re-authenticating: 
curl -X POST https://staging-api.puppetvendors.com/refresh-token \
  -H "x-access-token: YOUR_CURRENT_TOKEN"

​
Scope Behaviour

Vendor-scoped tokens automatically filter all data to your vendor account. For example, calling GET /orders will only return orders containing your line items. Attempting to access another vendor’s data returns HTTP 403.

​
API Key Scopes

API keys can be restricted to specific permissions. See the full API Keys & Scopes reference for a complete list of available scopes and what each one grants access to.