Authentication

Overview

The ZeroShop Admin API supports three authentication methods:

Personal Access Tokens (PATs) — recommended for scripts, integrations, and automation
JWT Cookie Sessions — used by the admin dashboard SPA
OAuth 2.1 + PKCE — used by MCP clients like Claude and ChatGPT

Personal Access Tokens

PATs are long-lived tokens scoped to a single shop. They inherit the permissions of the user who created them and are the recommended authentication method for any programmatic access.

Format: zspat_ followed by 43 random characters

Usage: Send as a Bearer token in the Authorization header:

curl https://yourshop.zeroshop.io/admin/api/products \
  -H "Authorization: Bearer zspat_abc123..."

import requests

session = requests.Session()
session.headers["Authorization"] = "Bearer zspat_abc123..."

# All requests through this session are authenticated
resp = session.get("https://yourshop.zeroshop.io/admin/api/products")

const headers = { "Authorization": "Bearer zspat_abc123..." };

const resp = await fetch("https://yourshop.zeroshop.io/admin/api/products", { headers });

require "net/http"

uri = URI("https://yourshop.zeroshop.io/admin/api/products")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer zspat_abc123..."
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

Key details:

Tokens are stored as SHA-256 hashes — they can't be recovered if lost
Default expiry: 90 days (configurable, or set to never expire)
Maximum 20 active tokens per user
Tokens cannot create other tokens
Subject to rate limiting (10 req/s burst, 600 req/min sustained)

JWT Cookie Sessions

The admin SPA uses cookie-based JWT sessions. This method is primarily for browser-based access and is not recommended for API integrations.

Login with POST /admin/api/login to receive a zeroshop_admin_jwt cookie. The cookie is HttpOnly and SameSite=Strict. Logout with POST /admin/api/logout.

OAuth 2.1 for MCP

MCP clients authenticate using OAuth 2.1 with PKCE (RFC 7636). This flow is fully automated when connecting through compatible AI assistants like Claude or ChatGPT.

The flow follows these standards:

RFC 9728 — Protected Resource Metadata (/.well-known/oauth-protected-resource)
RFC 8414 — Authorization Server Metadata (/.well-known/oauth-authorization-server)
RFC 7591 — Dynamic Client Registration (/mcp/oauth/register)

During authorization, the shop owner selects which MCP capabilities to grant (e.g., read products, manage orders). Tokens can be refreshed without re-authorization.

On this page

Overview

Personal Access Tokens

JWT Cookie Sessions

OAuth 2.1 for MCP