Issue or refresh an anonymous consumer token

1 min

POST

https://api.upstartcommerce.com/api/v1/auth/guest

Issues a short-lived JWT access token for anonymous browsing without credentials.

The endpoint serves both new and returning guests through a single call:

No cookie (new visitor): creates a new guest session, returns access token, sets guest_session HttpOnly cookie.
Valid cookie (returning visitor): rotates the cookie atomically, returns a new access token with the same stable session identity.
Unknown/expired cookie (reuse conflict or expiry): silently creates a new session (logs a warning server-side), returns access token, sets new cookie.

Access token — short-lived JWT (1 hour), hold in JS memory, send on every API call.

Guest session cookie — long-lived opaque UUID (30 days by default), stored as HttpOnly; Secure; SameSite=Strict, invisible to JavaScript.

JWT claims: sub = "guest:<stableSessionId>", type = "consumer", roles = [], tenant from the x-upstart-tenant header. The stableSessionId never changes for the lifetime of the guest session and can be used as a consistent identity key by downstream services (e.g. cart-svc).

Rate limiting: requests are rate-limited by client IP (guest:<ip>).

Header Parameters

x-upstart-tenantstring
Example
tenant-123
Description
Tenant identifier for multi-tenant authentication.

Required when user is authorized for multiple tenants. Optional when user has exactly one authorized tenant (auto-selected).
Cookiestring
Example
guest_session=3fa85f64-5717-4562-b3fc-2c963f66afa6
Description
Optional guest_session cookie from a previous call

Responses

200

Guest access token issued. The guest_session cookie in the response replaces any previously presented cookie — always store the latest value.

GuestTokenResponse
Example
```
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
```
Description
Response from POST /api/v1/auth/guest. The access token is returned in the body (store in JS memory, send on every API call). The opaque session token is set as an HttpOnly cookie by the server and is never exposed in the response body.
- accessTokenstringrequired
  Example
  eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
  Description
  JWT access token for anonymous API calls.
  
  Include in requests as: Authorization: Bearer <accessToken>
  
  Claims:
  
  sub: guest:<stableSessionId> — stable across session rotations
  
  type: consumer
  
  roles: ["customer.anonymous"] by default (configurable via guest-session.guestRoles)
  
  tenant: active tenant ID
  
  iat / exp / iss: standard JWT fields
- expiresIninteger<int64>required
  Example
  3600
  Description
  Seconds until the access token expires
  Format
  int64
- tokenTypestringrequired
  Example
  Bearer
  Description
  Token type (always "Bearer")

Response Headers

Set-Cookiestring
Example
guest_session=7fd113e1-1d30-48d2-88e0-50ef573ecef0; Max-Age=2592000; Secure; HTTPOnly; SameSite=Strict
Description
Rotated guest session cookie. Always HttpOnly; Secure; SameSite=Strict.

400

Missing required x-upstart-tenant header

ErrorResponse
Example
```
{
  "error": "tenant_required",
  "message": "x-upstart-tenant header is required",
  "code": "BAD_REQUEST"
}
```
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

429Rate limit exceeded

ErrorResponse
Example
```
{
  "error": "rate_limited",
  "message": "Too many guest token requests. Retry in 900s.",
  "code": "RATE_LIMITED"
}
```
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

500Internal server error

ErrorResponse
Description
Standard error response format
- errorstringrequired
  Example
  unauthorized
  Description
  Error type identifier:
  
  invalid_request: Malformed request or missing required fields
  
  unauthorized: Invalid credentials or token
  
  account_not_verified: Account exists but email/phone not verified
  
  session_expired: Maximum session lifetime exceeded, full re-login required
  
  unauthorized_tenant: User not authorized for requested tenant
  
  tenant_required: Multi-tenant user must specify tenant
  
  unauthorized_site: User not authorized for requested site
  
  site_required: Site context required for this operation
  
  no_authorized_sites: User has no authorized sites
  
  forbidden: Access denied (e.g., no authorized tenants)
  
  rate_limited: Too many requests, try again later
  
  account_locked: Account temporarily locked due to failed attempts
  
  internal_error: Server-side error
- messagestringrequired
  Example
  Invalid username or password
  Description
  Human-readable error description
- codestring<BAD_REQUEST | UNAUTHORIZED | UNAUTHORIZED_TENANT | TENANT_REQUIRED | FORBIDDEN | RATE_LIMITED | ACCOUNT_LOCKED | INTERNAL_SERVER_ERROR>required
  Example
  UNAUTHORIZED
  Description
  HTTP status code name
  Allowed
  BAD_REQUESTUNAUTHORIZEDUNAUTHORIZED_TENANTTENANT_REQUIREDFORBIDDENRATE_LIMITEDACCOUNT_LOCKEDINTERNAL_SERVER_ERROR

curl

curl --request POST \
     --url https://api.upstartcommerce.com/api/v1/auth/guest \
     --header 'accept: application/json'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/api/v1/auth/guest", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/api/v1/auth/guest")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.upstartcommerce.com/api/v1/auth/guest"

payload = {}
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Guest access token issued. The guest_session cookie in the response replaces
any previously presented cookie — always store the latest value.
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

400

// Missing required x-upstart-tenant header
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

429

// Rate limit exceeded
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

500

// Internal server error
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

GENERATED

// Internal server error
{
  "error": "unauthorized",
  "message": "Invalid username or password",
  "code": "UNAUTHORIZED"
}

tokenGenerationFailed

// Token generation failed
{
  "error": "internal_error",
  "message": "Token generation failed",
  "code": "INTERNAL_SERVER_ERROR"
}

serviceError

// Upstream service error
{
  "error": "internal_error",
  "message": "Failed to communicate with authentication backend",
  "code": "INTERNAL_SERVER_ERROR"
}