Skip to main content
V2 Alpha — 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. You obtain this token by exchanging your vendor API key at POST /v2/authenticate.

​
Vendor API Key

Your merchant assigns a vendor API key to your account. Vendor keys always start with the vk_ prefix.
Key TypePrefixToken ScopeWhere to Find
Vendor keyvk_vendor — your data onlyProvided by your merchant

​
Authenticating

Exchange your vendor API key for a JWT token: 
curl -X POST https://api.puppetvendors.com/v2/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "vk_YOUR_VENDOR_API_KEY"
  }'

​
Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400,
    "scope": "vendor",
    "shopDomain": "my-store.myshopify.com"
  }
}

​
Using the Token

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

​
Token Expiry & Refresh

Tokens expire after 24 hours (86400 seconds). Use POST /v2/refresh-token with a valid (non-expired) token to get a new one without re-authenticating: 
curl -X POST https://api.puppetvendors.com/v2/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 /v2/vendor/orders will only return orders containing your line items. Attempting to access another vendor’s data returns HTTP 403.