Skip to main content
POST
/
authenticate
Authenticate
curl --request POST \
  --url https://staging-api.puppetvendors.com/authenticate \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "apiKey": "<string>",
  "shopDomain": "<string>"
}
'
V2 Preview — This endpoint is part of the V2 API preview. Breaking changes may occur.

​
Overview

Exchange your vendor API key for a short-lived JWT token. The token is scoped to your vendor account and carries the permissions granted to your API key. Tokens expire after 24 hours. When a token expires, either re-authenticate or use POST /refresh-token to get a new one.

​
Use Cases

  • Vendor portal apps — Secure, isolated access to your vendor data
  • Custom integrations — Sync your orders, products, and payouts with external systems
  • AI agents — Programmatic access with scoped permissions

​
Request Body

​
apiKey
string
required
Your vendor API key (starts with vk_). Create one in the vendor portal under Settings > API Keys, or ask your merchant.
​
shopDomain
string
Optional. The shop is resolved from your API key. Only send this if your key works across multiple shops — if it doesn’t match, the request is rejected.

​
Response

200
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 86400,
    "scope": "vendor",
    "permissions": ["orders:read", "products:read", "products:write", "fulfillments:read"],
    "shopDomain": "my-store.myshopify.com",
    "mode": "live",
    "vendorId": "507f1f77bcf86cd799439012"
  }
}

​
Response Fields

FieldTypeDescription
tokenstringJWT token to use in the x-access-token header
expiresInnumberToken lifetime in seconds (always 86400 = 24 hours)
scopestringAlways "vendor" for vendor API keys
permissionsstring[]The specific scopes granted to your API key (e.g., orders:read, products:write). See API Keys & Scopes
shopDomainstringThe Shopify store domain associated with your key
modestring"live" or "test" — matches your API key mode
vendorIdstringYour vendor account ID

​
Error Responses

401
{ "success": false, "error": { "message": "Invalid API key", "code": "UNAUTHORIZED" } }
401
{ "success": false, "error": { "message": "API key revoked", "code": "UNAUTHORIZED" } }
401
{ "success": false, "error": { "message": "Shop is not active", "code": "UNAUTHORIZED" } }
401
{ "success": false, "error": { "message": "The provided shopDomain is not available.", "code": "UNAUTHORIZED" } }
429
{ "success": false, "error": { "message": "Too many authentication requests", "code": "RATE_LIMITED" } }

​
Examples

curl -X POST https://staging-api.puppetvendors.com/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "vk_live_x9y8z7w6v5u4..."
  }'