Authentication: Sessions and CSRF Tokens Explained

The Ecommerce API authenticates requests using server-side sessions with an opaque session cookie. Rather than long-lived API keys, each login or registration creates a new session. Write operations — any POST, PATCH, or DELETE — additionally require a short-lived CSRF token to prevent cross-site request forgery. This two-layer approach means your credentials never travel in a header or URL, and every sensitive action is explicitly authorized.

How Authentication Works

When you log in or register, the server issues an HttpOnly session cookie with SameSite=Lax. Because the cookie is HttpOnly, JavaScript running in the browser cannot read it — only the browser itself forwards it automatically on same-origin requests. The SameSite=Lax policy prevents the cookie from being sent on cross-site subresource requests while still allowing top-level navigations. Key properties of the session cookie:

HttpOnly — not accessible via document.cookie; protects against XSS token theft
SameSite=Lax — sent on same-site requests and top-level cross-site navigations, blocked on cross-site subrequests
Opaque — the cookie value is a random token; the server looks up the session record in the database on every request
Revocable — call DELETE /auth/session (current session) or DELETE /auth/sessions/{id} (any session) to invalidate immediately

The session remains valid until it expires naturally or you log out. Suspended or deleted accounts cannot obtain new sessions, and existing sessions for those accounts are rejected with 401 Unauthorized.

Getting a Session

Call POST /auth/login with your email and password to authenticate. On success the server sets the session cookie and returns your public_id and email_verified status.

curl -c cookies.txt -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "password": "S3cure!Pass"
  }'

const response = await fetch('https://api.example.com/api/v1/auth/login', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'jane@example.com',
    password: 'S3cure!Pass',
  }),
});
const data = await response.json();

import requests

session = requests.Session()
response = session.post(
    'https://api.example.com/api/v1/auth/login',
    json={'email': 'jane@example.com', 'password': 'S3cure!Pass'},
)
data = response.json()
# session cookie is stored automatically in session.cookies

Successful response (200 OK):

{
  "success": true,
  "data": {
    "public_id": "usr_01HXYZ",
    "email_verified": false
  }
}

To create a brand-new account instead, call POST /auth/register with the same fields plus first_name, last_name, and phone_number (E.164 format). Registration also sets the session cookie and queues a 24-hour verification email.

Cookie-based authentication requires your HTTP client to send credentials with every request. In the browser, always include credentials: 'include' in your fetch calls. In axios, set withCredentials: true. Without this flag the browser silently omits the session cookie and you receive a 401 on every authenticated endpoint.

CSRF Protection

Every state-changing request — any POST, PATCH, or DELETE — must include a valid CSRF token in the x-csrf-token header. The token is bound to your current session, so you must have an active session before fetching one. Step 1 — Fetch a token:

curl -b cookies.txt https://api.example.com/api/v1/auth/csrf-token

const res = await fetch('https://api.example.com/api/v1/auth/csrf-token', {
  credentials: 'include',
});
const { data } = await res.json();
const csrfToken = data.csrf_token;

resp = session.get('https://api.example.com/api/v1/auth/csrf-token')
csrf_token = resp.json()['data']['csrf_token']

Token response (200 OK):

{
  "success": true,
  "data": {
    "csrf_token": "csrf_abc123"
  }
}

Step 2 — Use the token in your write request:

curl -b cookies.txt -X POST https://api.example.com/api/v1/cart/items \
  -H "Content-Type: application/json" \
  -H "x-csrf-token: csrf_abc123" \
  -d '{"variant_public_id": "var_01H", "quantity": 1}'

await fetch('https://api.example.com/api/v1/cart/items', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'x-csrf-token': csrfToken,
  },
  body: JSON.stringify({ variant_public_id: 'var_01H', quantity: 1 }),
});

session.post(
    'https://api.example.com/api/v1/cart/items',
    json={'variant_public_id': 'var_01H', 'quantity': 1},
    headers={'x-csrf-token': csrf_token},
)

The CSRF token is also set as an HttpOnly cookie by the server alongside the JSON body response — the server validates it by comparing the cookie value with the x-csrf-token header value (double-submit cookie pattern). A missing or mismatched token returns 403 Forbidden.

Always fetch a fresh CSRF token immediately before starting a write sequence — especially before checkout or account updates. Tokens can expire with the session, and reusing a stale token causes a 403 that interrupts your flow. A single token fetch at the start of each user action is the safest strategy.

Session Management

The API gives you full visibility and control over all active sessions for your account.

Endpoint	Method	Description
`GET /auth/session`	GET	Returns the current session’s details and basic profile
`GET /auth/sessions`	GET	Lists all active sessions for your account, newest first
`DELETE /auth/session`	DELETE	Logs out and revokes the current session
`DELETE /auth/sessions/{session_public_id}`	DELETE	Revokes a specific session by its public ID

Each session entry in the list includes a public_id (prefixed ses_), device and IP metadata, created_at, and expires_at timestamps in ISO 8601 UTC. List all active sessions:

curl -b cookies.txt https://api.example.com/api/v1/auth/sessions

Revoke a specific session:

curl -b cookies.txt -c cookies.txt \
  -H "x-csrf-token: csrf_abc123" \
  -X DELETE https://api.example.com/api/v1/auth/sessions/ses_01H

Revoking your current session via DELETE /auth/sessions/{id} clears the session cookie immediately — the same effect as calling DELETE /auth/session. Revoking another session (e.g., from a different device) does not affect your current session or cookie.

Get Started

Core Concepts

Authentication: Sessions and CSRF Tokens Explained

How Authentication Works

Getting a Session

CSRF Protection

Session Management

​How Authentication Works

​Getting a Session

​CSRF Protection

​Session Management

How Authentication Works

Getting a Session

CSRF Protection

Session Management