Issue Session Token

Issue a Session Token for a customer to create orders in your store, or — with purpose: "portal" — to sign an already signed-in customer of your site into your store’s customer portal without email verification. This is an API Key exclusive endpoint.

POST /v1/actions/auth/issue-session-token

Authentication: API Key

How It Works

Your server calls this endpoint with API Key authentication
You receive a short-lived session token
Pass the token to the customer’s browser
The customer uses the token (Authorization: Bearer <token>) to create orders and interact with checkout

Session tokens are scoped to a single store and expire automatically.

Customer Portal Mode

Pass purpose: "portal" to get a link into the customer portal for the customer your site has already signed in. The call is the same; these rules change:

	Without `purpose`	`purpose: "portal"`
Store	`storeId` or `productId`	`storeId` required; `productId` is rejected with 400
Environment	Chosen per request by the `X-Environment` header	Fixed to the environment of the API Key that signed the call (test key → test portal data, production key → production portal data). There is no environment field
Response	`token`, `expiresAt`	`token`, `expiresAt`, `portalUrl`

To send the customer into the portal, append #token=<token> to portalUrl and answer the customer’s browser with a 302 redirect to the result. The SDK helpers build this URL for you — see Let Signed-In Customers Manage Orders.

The portal link is not single-use. Anyone holding it can open the portal as that customer while the session is alive. Treat the token and the full link as bearer credentials: mint them on your server right before the redirect, and never log them, store them, or send them by email.

A portal token is bound to its environment. If you also call the Customer Portal API with it, send an X-Environment header that matches the API Key’s environment; any other value is rejected with 403 Environment mismatch. Requests without purpose behave exactly as before.

Request Body

Field	Type	Required	Description
`storeId`	string	No	Target store ID (Short ID format `STO_xxx`). Required when `productId` is not provided
`productId`	string	No	Product ID (Short ID format `PROD_xxx`). When provided without `storeId`, the server derives the store from the product
`buyerIdentity`	string	Yes	Customer identity for order attribution (e.g., email or internal user ID). Encoded into the session JWT. In portal mode it must be the same value you passed when the customer’s orders were created
`purpose`	string	No	Set to `"portal"` to issue a customer portal session (see Customer Portal Mode). Omit it for checkout tokens

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",
});

// Customer portal link (calls this endpoint with purpose: "portal";
// portalUrl already ends with #token=...)
const { portalUrl } = await client.auth.createCustomerPortalLink({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  buyerIdentity: "user_8f3a2c",
});

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"storeId":"STO_2aUyqjCzEIiEcYMKj7TZtw","buyerIdentity":"customer@example.com"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/auth/issue-session-token
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/auth/issue-session-token" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"productId":"PROD_7J3K5L8M2N4P6Q9R","buyerIdentity":"customer@example.com"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/auth/issue-session-token
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/auth/issue-session-token" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"storeId":"STO_2aUyqjCzEIiEcYMKj7TZtw","buyerIdentity":"user_8f3a2c","purpose":"portal"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/auth/issue-session-token
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/auth/issue-session-token" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

# Using storeId
result = call_api_with_signature('POST', '/v1/actions/auth/issue-session-token', {
    'storeId': 'STO_2aUyqjCzEIiEcYMKj7TZtw',
    'buyerIdentity': 'customer@example.com'
})

# Using productId
result = call_api_with_signature('POST', '/v1/actions/auth/issue-session-token', {
    'productId': 'PROD_7J3K5L8M2N4P6Q9R',
    'buyerIdentity': 'customer@example.com'
})
print(result['data']['token'])

# Customer portal: append the token to portalUrl, then 302 the browser there
result = call_api_with_signature('POST', '/v1/actions/auth/issue-session-token', {
    'storeId': 'STO_2aUyqjCzEIiEcYMKj7TZtw',
    'buyerIdentity': 'user_8f3a2c',
    'purpose': 'portal'
})
redirect_url = result['data']['portalUrl'] + '#token=' + result['data']['token']

Success Response (200)

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

With purpose: "portal":

{
  "data": {
    "token": "opaque-session-token...",
    "expiresAt": "2024-01-15T11:00:00.000Z",
    "portalUrl": "https://pancake.waffo.ai/consumer/portal/store/STO_2aUyqjCzEIiEcYMKj7TZtw"
  }
}

Response Fields

Field	Type	Description
`token`	string	Session Token
`expiresAt`	string	Expiration time (ISO 8601) if the session stays idle. The session lasts 15 minutes and each use extends it, so an active session lives past this time
`portalUrl`	string	Only when `purpose` is `"portal"`. Portal page for this store, without the token. Append `#token=<token>` before redirecting

Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

Status	`errors[0].message`	What it means	Recommended handling
400	`Missing required field: buyerIdentity`	`buyerIdentity` is empty or missing	Fix the request body, then resubmit
400	`Missing required field: provide storeId or productId`	Neither `storeId` nor `productId` was provided	Provide one of them, then resubmit
400	`purpose=portal requires storeId and does not accept productId`	`purpose` is `"portal"` and `productId` was sent (with or without `storeId`)	Send `storeId` only (no `productId`), then resubmit
400	`Invalid purpose: expected "portal"`	`purpose` has a value other than `"portal"`	Set `purpose` to `"portal"` or omit it, then resubmit
400	`Expected format: STO_xxx, got "..."`	`storeId` Short ID could not be decoded	Fix the `storeId` format, then resubmit
400	`Expected format: PROD_xxx, got "..."`	`productId` Short ID could not be decoded	Fix the `productId` format, then resubmit
400	`Store is not active`	Store exists but its status is not `active`	Activate the store, then resubmit
401	`Missing merchantId in request context`	API Key authentication did not resolve a merchant	Verify API Key headers and signature
403	`Access denied: you do not have permission to this store`	Merchant does not own the store	Verify store ownership
404	`Store not found`	Store does not exist or has been deleted	Verify the store ID
404	`Product not found`	Product does not exist	Verify the product ID
500	`Internal server error`	Unexpected server-side failure	Retry with exponential backoff (start 5s, max 3 attempts)

Two pitfalls worth knowing

Do not reuse one idempotency key to mint tokens. Sending the same X-Idempotency-Key on repeated calls hits the platform’s 24-hour cache and replays the FIRST response — handing you a token that expired long ago. The SDKs no longer derive keys, so this only happens if you set the header yourself (directly over REST, or by passing the same idempotencyKey twice). If you mint tokens for the same buyer repeatedly (a token-refresh endpoint, a plan-change link generator), use a fresh key per call or none at all. Mint right before you redirect. The token lives 15 minutes (sliding), while a checkout or plan-change session lives 24 hours by default. A token minted alongside the session and parked in a queue or an email will be dead by the time the buyer clicks. For plan-change links specifically, the token goes in the URL fragment — see Building the link the customer opens.

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

How It Works

Customer Portal Mode

Request Body

Example Request

Success Response (200)

Response Fields

Errors

Two pitfalls worth knowing

​How It Works

​Customer Portal Mode

​Request Body

​Example Request

​Success Response (200)

​Response Fields

​Errors

​Two pitfalls worth knowing

How It Works

Customer Portal Mode

Request Body

Example Request

Success Response (200)

Response Fields

Errors

Two pitfalls worth knowing