Skip to main content
Issue a Session Token for a consumer to create orders in your store. This is an API Key exclusive endpoint. 
POST /v1/actions/auth/issue-session-token
Authentication: API Key

​
How It Works

  1. Your server calls this endpoint with API Key authentication
  2. You receive a short-lived session token
  3. Pass the token to the consumer’s browser
  4. The consumer uses the token (Authorization: Bearer <token>) to create orders and interact with checkout
Session tokens are scoped to a single store and expire automatically.

​
Request Body

FieldTypeRequiredDescription
storeIdstringNoTarget store ID (Short ID format STO_xxx). Required when productId is not provided
productIdstringNoProduct ID (Short ID format PROD_xxx). When provided without storeId, the server derives the store from the product
buyerIdentitystringYesConsumer identity for order attribution (e.g., email or internal user ID). Encoded into the session JWT

​
Example Request

// Using storeId
const { token, expiresAt } = await client.auth.issueSessionToken({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  buyerIdentity: "customer@example.com",
});

// Using productId (storeId derived automatically)
const { token, expiresAt } = await client.auth.issueSessionToken({
  productId: "PROD_7J3K5L8M2N4P6Q9R",
  buyerIdentity: "customer@example.com",
});

​
Success Response (200)

{
  "data": {
    "token": "opaque-session-token...",
    "expiresAt": "2024-01-15T11:00:00.000Z"
  }
}

​
Response Fields

FieldTypeDescription
tokenstringSession Token
expiresAtstringExpiration time (ISO 8601)

​
Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).
Statuserrors[0].messageWhat it meansRecommended handling
400Missing required field: buyerIdentitybuyerIdentity is empty or missingFix the request body, then resubmit
400Missing required field: provide storeId or productIdNeither storeId nor productId was providedProvide one of them, then resubmit
400Expected format: STO_xxx, got "..."storeId Short ID could not be decodedFix the storeId format, then resubmit
400Expected format: PROD_xxx, got "..."productId Short ID could not be decodedFix the productId format, then resubmit
400Store is not activeStore exists but its status is not activeActivate the store, then resubmit
401Missing merchantId in request contextAPI Key authentication did not resolve a merchantVerify API Key headers and signature
403Access denied: you do not have permission to this storeMerchant does not own the storeVerify store ownership
404Store not foundStore does not exist or has been deletedVerify the store ID
404Product not foundProduct does not existVerify the product ID
500Internal server errorUnexpected server-side failureRetry with exponential backoff (start 5s, max 3 attempts)