Issue a Session Token for a buyer to create orders in your store. This is an API Key exclusive endpoint — JWT authentication is not supported.
POST /v1/actions/auth/issue-session-token
Session Types
| Type | TTL | Behavior | Description |
|---|
customer | 5 min | Auto-renew on each API call | Merchant-issued, single-store scope, can create orders |
buyer | 30 min | Auto-renew on each API call | User-initiated login, cross-store scope |
shopper | 1 min | Single-use, deleted after first API call | Merchant-issued, one-time checkout only |
The current version always issues customer role tokens. The table above lists all supported session types for reference.
Shopper Sessions are single-use tokens. The first API call (e.g., create-order) consumes the session. Subsequent requests with the same token will return authentication failure.
Request Body
| Field | Type | Required | Description |
|---|
storeId | string | Yes | Target store ID (Short ID format STO_xxx) |
buyerIdentity | string | Yes | Buyer identity (e.g., email address) |
Example Request
const { token, expiresAt } = await client.auth.issueSessionToken({
storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
buyerIdentity: "customer@example.com",
});
Success Response (200)
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresAt": "2024-01-15T11:00:00.000Z"
}
}
Response Fields
| Field | Type | Description |
|---|
token | string | JWT Session Token |
expiresAt | string | Expiration time (ISO 8601) |
Error Responses
| Status | Error | Description |
|---|
| 400 | Missing required field: storeId | storeId not provided |
| 400 | Missing required field: buyerIdentity | buyerIdentity not provided |
| 400 | Store is not active | Store is inactive or suspended |
| 403 | Access denied: you do not have permission to this store | Merchant does not own this store |
| 404 | Store not found | Store ID does not exist |
