Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt

Use this file to discover all available pages before exploring further.

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"
  }'
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"

​
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.